Perl

SoftLayer met à disposition un client API basé Perl qui dispense des lourdeurs qu'impliquent les appels d'API SOAP manuels. L'utilisation de ce client exige la configuration système suivante :

  • Perl version 5.6 ou supérieure
  • SOAP::Lite
  • XML::Hash::LX

Téléchargez le client API Perl de SoftLayer à partir de sa page projet sur le profil github de SoftLayer. Une fois le client téléchargé, placez-le dans un répertoire associé à votre projet Perl ou dans le chemin @INC de votre installation Perl.

Téléchargement du client API Perl de SoftLayer

Exécution d'appels API

Une fois le client API téléchargé et installé, la première chose à faire est d'inclure le module SoftLayer::API::SOAP dans votre script. Ce module définit les objets de client de SoftLayer. Éventuellement,vous devrez ajouter le répertoire parent du module dans votre chemin @INC avant d'inclure ce module. Vous ajouterez le répertoire parent en entrant le code suivant :

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

Ensuite, créez un objet de client pour le service API SoftLayer que vous voulez utiliser. SoftLayer::API::SOAP->new() prendra cette opération en charge pour vous, avec quatre paramètres :

  • Le nom du service que vous voulez appeler.
  • Un numéro d'identification facultatif pour l'objet spécifique sur lequel vous allez travailler. Entrez une valeur undef soit si vous travaillez avec le service SoftLayer_Account, soit si vous ne travaillez pas sur un serveur, un ticket de support, une facture ou tout autre objet spécifique. Le numéro d'identification crée un paramètre d'initialisation dans votre appel API.
  • Votre nom d'utilisateur API.
  • Votre clé API.
    Le fragment de code ci-dessous est un exemple d'appel API utilisant les paramètres indiqués ci-dessus :
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);

Une fois que votre objet de client API ($client) est prêt, appelez une méthode API SoftLayer comme si cette méthode était en local pour votre objet de client. Pour obtenir le résultat de votre appel API, affectez-le à une variable. Les objets de type complexe sont renvoyés en tant que hachages "bénis" avec le type de retour de votre appel. Par ailleurs, si vous devez entrer des paramètres de type complexe pour vos appels API, vous utiliserez des hachages, des hachages contenant des hachages ou des hachages contenant des tableaux. Exemple :

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

Utilisation de masques d'objet

Utilisez une variable de hachage imbriquée pour créer un masque d'objet pour votre appel API. Définissez ensuite les propriétés relationnelles que vous souhaitez extraire en tant que clés de hachage. Si vous voulez extraire des propriétés enfant, définissez un hachage imbriqué pour ces propriétés, Sinon, définissez un hachage vide en tant que valeur de clé. Liez ensuite votre masque d'objet à votre client API avec la méthode the setObjectMask(). L'exemple ci-après extrait les enregistrements de matériel physique d'un compte, ainsi que l'enregistrement du système d'exploitation de ce matériel, les mots de passe du système d'exploitation, les composants réseau, le centre de données où se situe le matériel et le nombre de processeurs de chaque élément matériel :

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

Utilisation de limites de résultats

Lors de l'appel de données, et notamment s'il s'agit d'extraire des fragments d'information relevant de structures plus importantes, vous réduirez sensiblement votre temps d'attente en fixant des limites pour les résultats.
Vous limiterez le nombre de résultats de votre appel API avec la méthode setResultLimit() de votre objet client. Cette méthode peut prendre deux paramètres :

  • le nombre de résultats auquel votre appel doit se limiter,
  • un décalage à partir duquel doit s'afficher votre ensemble de résultats (facultatif).

Le code ci-dessous est un exemple d'utilisation d'une limite de résultats dans un appel 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();

Traitement des erreurs

Si une erreur SOAP est générée par votre appel API SoftLayer, les propriétés fault et faultstring sont renseignées pour votre objet de client. Après exécution d'un appel API, vérifiez la propriété fault afin de vous assurer que toute erreur rencontrée a été correctement traitée. En cas d'erreur dans votre appel, la propriété faultstring va contenir le message renvoyé par l'API SoftLayer. Vous avez un exemple d'erreur avec le script ci-dessous :

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

Composants API référencés

financiers

Types de données

Méthodes