Perl

SoftLayer bietet einen Perl-basierten API-Client, der manuelle Aufrufe der SOAP-API vereinfacht. Damit dieser API-Client verwendet werden kann, müssen die folgenden Systemanforderungen erfüllt sein:

  • Perl 5.6 oder höher
  • SOAP::Lite
  • XML::Hash::LX

Laden Sie den Perl-Client der SoftLayer-API von der Projektseite des GitHub-Profils von SoftLayer herunter. Extrahieren Sie den Perl-Client der API nach dem Download in ein lokales Verzeichnis Ihres Perl-Projekts oder in den @INC-Pfad Ihrer Perl-Installation.

Perl-Client der SoftLayer-API herunterladen

Durchführung von API-Aufrufen

Sobald der API-Client heruntergeladen und installiert wurde, sollten Sie zuerst das Modul SoftLayer::API::SOAP in Ihr Script aufnehmen. Diese Datei definiert die SoftLayer-Clientobjekte. Möglicherweise müssen Sie das übergeordnete Verzeichnis des Moduls in Ihren @INC-Pfad aufnehmen, bevor Sie das Modul hinzufügen können. Sie können das übergeordnete Verzeichnis unter Verwendung des folgenden Codes aufnehmen:

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

Erstellen Sie als Nächstes ein Clientobjekt für den SoftLayer-API-Service, den Sie verwenden möchten. SoftLayer::API::SOAP->new() übernimmt das für Sie und verwendet vier Parameter:

  • Den Namen des Service, den Sie aufrufen möchten.
  • Eine optionale ID des bestimmten Objekts, mit dem Sie arbeiten möchten. Geben Sie einen undef-Wert weiter, wenn Sie den SoftLayer_Account-Service nutzen oder nicht mit einem bestimmten Server, einem bestimmten Support-Ticket, einer bestimmten Rechnung oder einem anderen bestimmten Objekt arbeiten. Mit dieser ID wird ein Initialisierungsparameter in Ihrem API-Aufruf erstellt.
  • Ihren API-Benutzernamen.
  • Ihren API-Schlüssel.
    Das nachstehende Code-Snippet ist ein Beispiel für die Durchführung eines API-Aufrufs unter Verwendung der vorstehend genannten Parameter:
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);

Sobald Ihr API-Clientobjekt ($client) bereit ist, rufen Sie eine SoftLayer-API-Methode auf, als wäre sie für Ihr Clientobjekt lokal. Weisen Sie das Ergebnis des API-Aufrufs einer Variablen zu, um das Ergebnis des Aufrufs zu erhalten. Objekte, bei denen es sich um komplexe Typen handelt, werden als Hashes (Rückgabetyp Ihres Aufrufs) zurückgegeben. Verwenden Sie auch Hashes, Hashes, die Hashes enthalten, oder Hashes, die Arrays enthalten, wenn Sie komplexe Typenparameter an Ihre API-Aufrufe weitergeben müssen. Beispiel:

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

Verwendung von Objektmasken

Verwenden Sie eine verschachtelte Hashvariable, um für Ihren API-Aufruf eine Objektmaske zu erstellen. Definieren Sie die relationalen Eigenschaften, die Sie als Hashschlüssel abrufen möchten. Wenn Sie untergeordnete Eigenschaften abrufen, definieren Sie einen verschachtelten Hash für die untergeordnete Eigenschaft. Ansonsten definieren Sie einen leeren Hash als Schlüsselwert. Binden Sie Ihre Objektmaske mit der Methode the setObjectMask() an Ihren API-Client. In diesem Beispiel werden die physischen Hardwaredatensätze eines Accounts sowie der Betriebssystemdatensatz der Hardware, die Betriebssystemkennwörter, die Netzwerkkomponenten, das Rechenzentrum, in dem sich die Hardware befindet, und die Anzahl Prozessoren in der jeweiligen Hardware abgerufen:

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

Verwendung von Ergebnisbegrenzungen

Beim Abrufen von Daten, insbesondere bei Abfragen, die das Extrahieren von Informationssnippets aus größeren Gruppen beinhalten, können Sie durch Verwendung von Ergebnisbegrenzungen Ihre Wartezeit auf die Rückgabe erheblich verkürzen.
Begrenzen Sie die Anzahl Ergebnisse in Ihrem API-Aufruf mit der setResultLimit()-Methode Ihres Clientobjekts. Diese Methode verwendet zwei Parameter:

  • Die Anzahl Ergebnisse, um den Aufruf zu begrenzen.
  • Einen optionalen Offset, um die Ergebnisliste zu beginnen.

Der nachstehende Code ist ein Beispiel für die Verwendung von Ergebnisbegrenzungen in Ihrem API-Aufruf.

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

Fehlerbehandlung

Wenn Ihr Aufruf der SoftLayer-API einen SOAP-Fehler ausgelöst hat, belegt Ihr Clientobjekt die Eigenschaften fault und faultstring. Überprüfen Sie die Eigenschaft fault nach Durchführung eines API-Aufrufs, um eine effektive Fehlerbehandlung sicherzustellen. Wenn bei Ihrem Aufruf ein Fehler auftrat, enthält die Eigenschaft faultstring den Fehler, den die SoftLayer-API zurückgegeben hat. Das folgende Script enthält ein Beispiel für einen solchen Fehler:

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

Referenzierte API-Komponenten

Services

Datentypen

Methoden