PHP

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

  • PHP 5.2.3 oder höher
  • Eine der nachstehenden PHP-Erweiterungen:

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

Durchführung von SOAP-Aufrufen

Sobald der API-Client heruntergeladen und installiert wurde, sollten Sie zuerst die Datei SoapClient.class.php in Ihr Script aufnehmen. Diese Datei definiert die SoftLayer-Clientobjekte.

require_once('/path/to/SoftLayer/SoapClient.class.php');

Erstellen Sie als Nächstes ein Clientobjekt für den SoftLayer-API-Service, den Sie verwenden möchten. SoftLayer_SoapClient::getClient() ü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 null-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 SOAP-Aufrufs unter Verwendung der vorstehend genannten Parameter:

require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
/**
 * Create a client to the SoftLayer_Account API service.
 */
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
/**
 * Work directly with the SoftLayer_Hardware_Server record with the hardware id 
 * 1234.
 */
$serverId = 1234;
$client = SoftLayer_SoapClient::getClient('SoftLayer_Hardware_Server', $serverId, $apiUsername, $apiKey);

Sobald Ihr API-Clientobjekt 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 PHP stdClass-Objekte zurückgegeben. Verwenden Sie dementsprechend stdClass-Objekte, wenn Sie Parameter (komplexer Typ) an Ihre API-Aufrufe weitergeben müssen. Beispiel:

require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
$domainId = 1234;
 
$client = SoftLayer_SoapClient::getClient('SoftLayer_Dns_Domain', $domainId, $apiUsername, $apiKey);
 
/**
 * Create a new A record in a domain.
 */
$newRecord = $client->createARecord('myhost', '127.0.0.1', 86400);
 
echo 'New A record id: ' . $newRecord->id;
 
/**
 * Create a new domain record. 
 * 
 * This requires an API client with a null id, and use a stdClass object to model 
 *our new domain.
 */
$client = SoftLayer_SoapClient::getClient('SoftLayer_Dns_Domain', null, $apiUsername, $apiKey);
 
$domain = new stdClass();
$domain->name = 'example.org';
$domain->resourceRecords = array();
$domain->resourceRecords[0] = new stdClass();
$domain->resourceRecords[0]->host = '@';
$domain->resourceRecords[0]->data = '127.0.0.1';
$domain->resourceRecords[0]->type = 'a';
 
$newDomain = $client->createObject($domain);
 
echo 'New domain id: ' . $newDomain->id;

Verwendung von XML-RPC

Der PHP-Client der SoftLayer-API unterstützt sowohl SOAP- als auch XML-RPC-Protokolle. Wenn Sie XML-RPC statt SOAP verwenden möchten, sind zwei Änderungen erforderlich:

  • Nehmen Sie XmlrpcClient.class.php statt SoapClient.class.php auf
  • Erstellen Sie einen API-Client mit SoftLayer_XmlrpcClient::getClient() statt SoftLayer_SoapClient::getClient()
    Beispiel:
require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);

Verwendung von Objektmasken

Erstellen Sie eine Objektmaske in Ihrem API-Aufruf, indem Sie zuerst ein neues SoftLayer_ObjectMask-Objekt deklarieren. Definieren Sie die relationalen Eigenschaften, die Sie als lokale Eigenschaften in Ihrem neuen Maskenobjekt abrufen möchten. Binden Sie die Objektmaske schließlich unter Verwendung der setObjectMask()-Methode an Ihren API-Client. In diesem Beispiel werden die folgenden Informationen abgerufen:

  • Die physische Hardware des Accounts
  • Der Betriebssystemdatensatz der Hardware
  • Das Betriebssystemkennwort
  • Die Netzwerkkomponenten
  • Das Rechenzentrum, in dem sich die Hardware befindet
  • Die Anzahl Prozessoren in der jeweiligen Hardware
require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
/**
 * 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.
 */
$objectMask = new SoftLayer_ObjectMask();
$objectMask->hardware->operatingSystem->passwords;
$objectMask->hardware->networkComponents;
$objectMask->hardware->datacenter;
$objectMask->hardware->processorCount;
$client->setObjectMask($objectMask);
 
$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.
    Das nachstehende Beispiel berücksichtigt die erforderlichen Informationen, um eine Ergebnisbegrenzung festzulegen:
require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
/**
 * Retrieve our first two open support tickets.
 */
$client->setResultLimit(2);
 
$tickets = $client->getOpenTickets();

Fehlerbehandlung

Fehler beim Aufruf der SoftLayer-API werden vom PHP-Client als Ausnahmebedingungen ausgelöst. Führen Sie Aufrufe der SoftLayer-API in Try/Catch-Blocks durch, um eine ordnungsgemäße Abwicklung sicherzustellen. Verwenden Sie die getMessage()-Methode der PHP-Ausnahmeklassen, um auf Fehler zuzugreifen, die von der SoftLayer-API zurückgegeben werden. Das folgende Script enthält ein Beispiel für einen solchen Fehler:

require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me!';
$apiKey = 'an incorrect API key';
 
$client = new SoftLayer_SoapClient('SoftLayer_Account', null, $apiUsername, $apiKey);
 
/**
 * Exit the script with the message:
 * "Unable to retrieve account information: Invalid API key"
 */
try {
    $account = $client->getObject();
} catch (Exception $e) {
    die('Unable to retrieve account information: ' . $e->getMessage());
}

Referenzierte API-Komponenten

Services

Datentypen

Methoden