Perl

SoftLayer proporciona un cliente de API basado en Perl que agiliza la realización de llamadas de API SOAP manuales. Para utilizar el cliente de API, deben cumplirse los siguientes requisitos del sistema:

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

Descargue el cliente de API Perl de SoftLayer de su página de proyecto en el perfil github de SoftLayer. Una vez descargado, extraiga el cliente de API Perl en un directorio local para el proyecto Perl o en la vía de acceso @INC de su instalación de Perl.

Descargue el cliente Perl de API de SoftLayer

Realización de llamadas de API

Una vez descargado e instalado el cliente de API, lo primero que hay que hacer es incluir el módulo SoftLayer::API::SOAP en el script. Este archivo define los objetos de cliente de SoftLayer. Puede añadir el directorio padre del módulo a la vía de acceso de @INC antes de incluir el módulo. Añada el directorio padre utilizando el código siguiente:

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

A continuación, cree un objeto de cliente para el servicio de API de SoftLayer que desee utilizar. SoftLayer::API::SOAP->new() lo hace automáticamente utilizando cuatro parámetros:

  • El nombre del servicio que desea invocar.
  • Un número de ID opcional del objeto específico con el que desea trabajar. Pase un valor undef si está trabajando con el servicio SoftLayer_Account o si no está trabajando con un servidor, una incidencia de soporte técnico, una factura u otro objeto específico. Este ID crea un parámetro de inicialización en la llamada de API.
  • El nombre de usuario de API.
  • La clave de API.
    El siguiente fragmento de código proporciona un ejemplo de cómo realizar una llamada de API utilizando los parámetros anteriores:
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);

Cuando el objeto del cliente de API ($client) esté preparado, invoque un método de API de SoftLayer como si fuera local para su objeto de cliente. Asigne el resultado de la llamada de API a una variable para obtener el resultado de la llamada. Los objetos de tipo complejo se devuelven como hashes aprobados como el tipo de retorno de la llamada. De la misma manera, utilice hashes que contengan hashes o hashes que contengan matrices si necesita pasar parámetros de tipo complejo a las llamadas de API. Por ejemplo:

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();

Utilización de máscaras de objeto

Utilice una variable de hash anidada para crear una máscara de objeto en la llamada de API. Defina las propiedades relacionales que desee recuperar como claves hash. Si está recuperando propiedades hijo, defina un hash anidado para la propiedad hijo. De lo contrario, defina un hash vacío como valor de la clave. Enlace la máscara de objeto al cliente de API con el método the setObjectMask(). En este ejemplo, se recuperan los registros de hardware físico de una cuenta, junto con el registro del sistema operativo del hardware, las contraseñas del sistema operativo, los componentes de red, el centro de datos donde se encuentra el hardware y el número de procesadores en 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();

Utilización de los límites de resultados

Cuando se invocan datos, especialmente en las consultas que implican la extracción de fragmentos de código de información de grupos de gran tamaño, el uso de límites de resultados disminuye significativamente el tiempo de espera de la devolución.
Limite el número de resultados en la llamada de API con el método setResultLimit() del objeto de cliente. Este método utiliza dos parámetros:

  • El número de resultados al que se limita la llamada.
  • Un desplazamiento opcional para iniciar el conjunto de resultados.

El código siguiente proporciona un ejemplo de uso de límites de resultados en la llamada de 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();

Manejo de errores

Si la llamada de API de SoftLayer ha generado un error SOAP, se rellenarán las propiedades fault y faultstring en el objeto de cliente. Compruebe la propiedad fault después de realizar una llamada de API para garantizar un manejo de errores eficaz. Si hay un error en la llamada, la propiedad faultstring contiene el error devuelto por la API de SoftLayer. El siguiente script contiene un ejemplo de este tipo de error:

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 de API referenciados

Servicios

Tipos de datos

Métodos