PHP

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

  • PHP 5.2.3 o successive
  • Una delle seguenti estensioni PHP:

Scarica il client API PHP SoftLayer dalla relativa pagina del progetto sul profilo github di SoftLayer. Dopo averlo scaricato, estrai il client API PHP in una directory locale per il tuo progetto PHP o nell'include_path della tua installazione di PHP.
Download del client PHP API SoftLayer

Effettuazione di chiamate SOAP

Una volta scaricato e installato il client API, la prima cosa da fare è includere il file SoapClient.class.php nel tuo script. Questo file definisce gli oggetti client di SoftLayer.

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

Crea quindi un oggetto client per il servizio dell'API SoftLayer che desideri utilizzare. SoftLayer_SoapClient::getClient() 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 null 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 SOAP, utilizzando i parametri esposti in precedenza:

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

Quando il tuo oggetto client API è 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 vengono restituiti come oggetti PHP stdClass. Allo stesso modo, usa gli oggetti stdClass se devi passare dei parametri di tipo complesso alle tue chiamate API. Ad esempio:

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;

Utilizzo di XML-RPC

Il client PHP API SoftLayer supporta entrambi i protocolli SOAP e XML-RPC in modo interscambiabile. Se vuoi utilizzare XML-RPC invece di SOAP, sono necessarie due modifiche:

  • Includi XmlrpcClient.class.php invece di SoapClient.class.php
  • Crea un client API con SoftLayer_XmlrpcClient::getClient() invece di SoftLayer_SoapClient::getClient()
    Ad esempio:
require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);

Utilizzo delle maschere oggetto

Crea una maschera oggetto nella tua chiamata API dichiarando prima un nuovo oggettoSoftLayer_ObjectMask. Definisci le proprietà relazionali che vuoi richiamare come proprietà locali nella tua nuova maschera oggetto. Infine, associala al tuo client API utilizzando il metodo setObjectMask(). Questo esempio richiama le seguenti informazioni:

  • L'hardware fisico dell'account
  • Il record di sistema operativo dell'hardware
  • La password del sistema operativo
  • I componenti di rete
  • Il datacenter in cui si trova l'hardware
  • Il numero di processori in ciascun 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();

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.
    L'esempio qui di seguito incorpora le informazioni necessarie per impostare un limite dei risultati:
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();

Gestione degli errori

Gli errori di chiamata API SoftLayer sono generati dal client PHP come eccezioni. Effettua le chiamate alla API SoftLayer all'interno di blocchi try/catch per assicurare una corretta gestione. Utilizza il metodo getMessage() delle classi di eccezione PHP per accedere agli errori restituiti dall'API SoftLayer. Il seguente script contiene un esempio di un errore di questo tipo:

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

Componenti API a cui si fa riferimento

Servizi

Tipi di dati

Metodi