Perl

SoftLayer fornisce un client API basato su PHP che semplifica non poco l'effettuazione di chiamate API SOAP manuali. Per utilizzare questo client API, devono essere soddisfatti i seguenti requisiti di sistema:

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

Scarica il client API Perl SoftLayer dalla sua pagina del progetto sul profilo github di SoftLayer. Una volta eseguito il download, estrai il client API Perl in una directory locale per il tuo progetto Perl o nel percorso @INC di installazione di Perl.

Download del client Perl API SoftLayer

Effettuazione di chiamate API

Una volta scaricato e installato il client API, la prima cosa da fare è includere il modulo SoftLayer::API::SOAP nel tuo script. Questo file definisce gli oggetti client di SoftLayer. È possibile che tu debba aggiungere la directory parent del modulo al tuo percorso @INC prima di includere il modulo. Aggiungi la directory parent con il seguente codice:

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

Crea quindi un oggetto client per il servizio API SoftLayer che vuoi utilizzare. SoftLayer::API::SOAP->new() si occuperà della cosa per tuo conto e accetterà quattro parametri:

  • Il nome del servizio che vuoi richiamare.
  • Un numero ID facoltativo dello specifico oggetto che desideri gestire. Passa un valore undef se stai lavorando con il servizio SoftLayer_Account o non stai lavorando con un server, un ticket di supporto, una fattura o un altro oggetto specifici. Questo ID crea un parametro di inizializzazione nella tua chiamata API.
  • Il tuo nome utente API.
  • La tua chiave API.
    Il frammento di codice qui di seguito fornisce un esempio di effettuazione di una chiamata API, utilizzando i parametri esposti in precedenza:
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 il tuo oggetto client API ($client) è pronto, richiama un metodo API SoftLayer come se fosse locale per il tuo oggetto client. Assegna il risultato della tua chiamata API a una variabile per ottenere il risultato della chiamata. Gli oggetti di tipo complesso sono restituiti come hash sottoposti a bless come tipo di restituzione della tua chiamata. In modo analogo, usa hash, hash contenenti hash o hash contenenti array se devi passare dei parametri di tipo complesso alle tue chiamate API. Ad esempio:

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

Utilizzo delle maschere oggetto

Utilizza una variabile hash nidificata per creare una maschera oggetto per la tua chiamata API. Definisci le proprietà relazionali che vuoi richiamare come chiavi hash. Se stai richiamando delle proprietà child, definisci un hash nidificato per la tua proprietà child. Altrimenti, definisci un hash vuoto come valore della tua chiave. Associa la tua maschera oggetto al tuo client API con il metodo the setObjectMask(). Questo esempio richiama i record di hardware fisico di un account insieme al record di sistema operativo di detto hardware, al record di sistema operativo, alle password del sistema operativo, ai componenti di rete, al datacenter su cui si trova l'hardware e al numero di processori in ciascun 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();

Utilizzo dei limiti dei risultati

Quando si richiamano i dati, in particolar modo nel caso di query che comportano l'estrazione di frammenti di informazioni da gruppi più grandi, l'utilizzo dei limiti dei risultati ridurrà notevolmente il tempo di attesa per la restituzione dei dati.
Limita il numero di risultati nella tua chiamata API con il metodo setResultLimit() del tuo oggetto client. Questo metodo accetta due parametri:

  • Il numero di risultati a cui limitare la tua chiamata.
  • Un offset facoltativo per l'inizio del set di risultati.

Il codice qui di seguito fornisce un esempio di utilizzo dei limiti dei risultati nella tua chiamata 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();

Gestione degli errori

Se la tua chiamata API SoftLayer ha generato un errore SOAP, per il tuo oggetto client saranno compilate le proprietà fault e faultstring. Controllare la
proprietà fault dopo aver effettuato una chiamata API per gestire in modo efficace gli errori. Se si è verificato un errore nella tua chiamata, la proprietà faultstring contiene l'errore restituito dall'API SoftLayer. Il seguente script contiene un esempio di un errore di questo tipo:

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;
}

Componenti API a cui si fa riferimento

Servizi

Tipi di dati

Metodi