Perl

O SoftLayer fornece um cliente da API baseado em Perl que retira o peso de fazer chamadas de API SOAP manuais. Para usar esse cliente da API, os requisitos do sistema a seguir devem ser atendidos:

  • Perl 5.6 ou superior
  • SOAP::Lite
  • XML::Hash::LX

Faça download do cliente da API da SoftLayer Perl de sua página de projeto no perfil do github da SoftLayer. Após ser transferido por download, extraia o cliente da API Perl para um diretório local do projeto Perl ou no caminho @INC da instalação do Perl.

Fazer download do cliente da API da SoftLayer Perl

Fazendo chamadas de API

Quando o cliente da API tiver sido transferido por download e instalado, a primeira coisa a fazer é incluir o módulo SoftLayer::API::SOAP em seu script. Esse arquivo define os objetos do cliente SoftLayer. Pode ser necessário incluir o diretório-pai do módulos no caminho @INC antes de incluir o módulo. Inclua o diretório-pai usando o código a seguir:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;

Em seguida, crie um objeto do cliente para o serviço da API da SoftLayer que deseja usar. SoftLayer::API::SOAP->new() cuidará disso para você e aceita quatro parâmetros:

  • O nome do serviço que você deseja chamar.
  • Um número de ID opcional do objeto específico com o qual deseja trabalhar. Passe um valor undef se estiver trabalhando com o serviço SoftLayer_Account ou não estiver trabalhando com um servidor, chamado de suporte, fatura ou outro objeto específico. Esse ID cria um parâmetro de inicialização na chamada API.
  • Seu nome do usuário da API.
  • A chave da API.
    O fragmento de código abaixo fornece um exemplo de como fazer uma chamada API usando os parâmetros esboçados acima:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
# Create a client to the SoftLayer_Account API service.
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
 
# Work directly with the SoftLayer_Hardware_Server record with the hardware id 
# 1234.
#my $server_id = 1234;
#my $client = SoftLayer::API::SOAP->new('SoftLayer_Hardware_Server', $server_id, $api_username, $api_key);

Quando o objeto do cliente da API ($client) estiver pronto, chame um método de API da SoftLayer como se fosse local para o objeto do cliente. Atribua o resultado da chamada API a uma variável para obter o resultado da chamada. Objetos de tipo complexo são retornados como hashes consagrados como o tipo de retorno da chamada. De forma semelhante, use hashes, hashes que contêm hashes ou hashes que contêm matrizes se precisar passar parâmetros de tipo complexo para as chamadas de API. Por exemplo:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
my $domain_id = 1234;
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', $domain_id, $api_username, $api_key);
 
# Create a new A record in a domain.
my $new_record = $client->createARecord('myhost', '127.0.0.1', 86400);
 
print 'New A record id: ' . $new_record->{id}; 
 
# Create a new domain record. 
#
# This requires an API client with an undef id, and use a hash with an array to model 
# our new domain.
$client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', undef, $api_username, $api_key);
 
my $domain = {
    'name' => 'example.org',
    'resourceRecords' => [
        {
            'host' => '@',
            'data' => '127.0.0.1',
            'type' => 'a',
        }
    ]
};
 
my $new_domain = $client->createObject($domain);
 
print 'New domain id: ' . $new_domain->{id};
If you wish, you can declare your client object and make an API call on a single line.  The following code outlines this scenario:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $account = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key)->getObject();

Usando máscaras de objetos

Use uma variável hash aninhada para criar uma máscara de objeto para sua chamada API. Defina as propriedades relacionais que deseja recuperar como chaves de hash. Se estiver recuperando propriedades-filhas, defina um hash aninhado para a propriedade-filha. Caso contrário, defina um hash vazio como o valor da chave. Ligue a máscara de objeto ao cliente da API com o método the setObjectMask(). Este exemplo recupera os registros de hardware físico de uma conta com o registro do sistema operacional desse hardware, senhas do sistema operacional, componentes da rede, o datacenter no qual o hardware está localizado e o número de processadores em cada hardware:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# Retrieve items related to hardware.
#
# Operating system, operating system passwords, all network components, the
# datacenter the server is located in, and the number of processors in each 
# server.
my $object_mask = {
    'hardware' => {
        'operatingSystem' => {
            'passwords' => {},
        },
        'networkComponents' => {},
        'datacenter' => {},
        'processorCount' => {},
    }
};
 
$client->setObjectMask($object_mask);
 
my $hardware = $client->getHardware();

Usando limites de resultados

Ao chamar dados, principalmente consultas que envolvem puxar fragmentos de informações de grupos maiores, usar limites de resultados irá reduzir muito seu tempo de espera pelo retorno.
Limite o número de resultados na chamada API com o método setResultLimit() do objeto do cliente. Esse método aceita dois parâmetros:

  • O número de resultados para limitar sua chamada.
  • Um deslocamento opcional para iniciar o conjunto de resultados.

O código abaixo fornece um exemplo de como usar limites de resultados na chamada API.

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# Retrieve our first two open support tickets.
$client->setResultLimit(2);
 
$tickets = $client->getOpenTickets();

Manipulação de erros

Se uma falha de SOAP for lançada pela chamada API da SoftLayer, então, o objeto do cliente terá
as propriedades fault
e faultstring preenchidas. Verifique a propriedade fault após fazer uma chamada API para manipulação efetiva de erros. Se havia um erro na chamada, a propriedade faultstring contém o erro retornado pela API da SoftLayer. O script a seguir contém um exemplo desse erro:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'an incorrect key';
 
$client = SoftLayer::API::SOAP->new('SoftLayer_Account', null, $api_username, $api_key);
 
# Exit the script with the message:
# "Unable to retrieve account information: Invalid API key"
my $account = $client->getObject();
 
if ($account->fault) {
    die 'Unable to retrieve account information: ' . $account->faultstring;
}

Componentes da API referidos

Serviços

Tipos de dados

Métodos