PHP

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

  • PHP version 5.2.3 ou supérieure
  • L'une des extensions PHP suivantes :

Téléchargez le client API PHP 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 PHP ou dans un répertoire include_path de votre installation PHP.
Téléchargement du client API PHP de SoftLayer

Exécution d'appels SOAP

Une fois le client API téléchargé et installé, la première chose à faire est d'inclure le fichier SoapClient.class.php dans votre script. Ce fichier définit les objets de client de SoftLayer.

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

Ensuite, créez un objet de client pour le service API SoftLayer que vous voulez utiliser. SoftLayer_SoapClient::getClient() 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 null 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 SOAP utilisant les paramètres indiqués ci-dessus :

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

Une fois votre objet de client API 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 qu'objets PHP stdClass. Par ailleurs, vous utiliserez des objets stdClass si vous devez entrer des paramètres de type complexe pour vos appels API. Exemple :

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;

Utilisation de XML-RPC

Le client API PHP de SoftLayer prend en charge les deux protocoles SOAP XML-RPC de façon interchangeable. Si vous souhaitez utiliser XML-RPC plutôt que SOAP, deux modifications sont nécessaires :

  • Incluez XmlrpcClient.class.php en lieu et place de SoapClient.class.php
  • Créez un client API avec SoftLayer_XmlrpcClient::getClient() en lieu et place de SoftLayer_SoapClient::getClient()
    Exemple :
require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);

Utilisation de masques d'objet

Créez un masque d'objet dans votre appel API en commençant par déclarer un nouvel objet SoftLayer_ObjectMask. Définissez ensuite les propriétés relationnelles que vous souhaitez extraire en tant que propriétés locales dans votre nouveau masque d'objet. Enfin, liez ce masque à votre client API en utilisant la méthode setObjectMask(). Notre exemple va extraire les informations suivantes :

  • Le matériel physique du compte
  • L'enregistrement du système d'exploitation du matériel
  • Le mot de passe du système d'exploitation
  • Les composants réseau
  • Le centre de données dans lequel se trouve le matériel
  • Le nombre de processeurs pour chaque élément matériel
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();

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).
    L'exemple ci-dessous intègre les informations nécessaires pour définir une limite de résultats :
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();

Traitement des erreurs

Les erreurs d'appel API SoftLayer sont signalées par le client PHP en tant qu'exceptions. Pour un traitement approprié, vous placerez les appels SoftLayer dans des blocs try/catch. Vous utiliserez la méthode getMessage() des classes d'exceptions PHP pour accéder aux erreurs renvoyées par l'API SoftLayer. Vous avez un exemple d'erreur avec le script ci-dessous :

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

Composants API référencés

financiers

Types de données

Méthodes