PHP

SoftLayer 提供一种基于 PHP 的 API 客户端,可避免手动发出 SOAP 或 XML-RPC 调用的繁重工作量。要使用基于 PHP 的 API 客户端,必须满足以下系统需求:

  • PHP 5.2.3 或更高版本
  • 以下某一项 PHP 扩展:

从 SoftLayer 的 github 配置文件内的项目页面中,下载 SoftLayer PHP API 客户端。完成下载后,请将 PHP API 客户端解压到 PHP 项目的本地目录,或解压到 PHP 安装的 include_path 中。
下载 SoftLayer API PHP 客户端

发出 SOAP 调用

下载并安装该 API 客户端后,要做的第一件事是在脚本中包含 SoapClient.class.php 文件。此文件定义 SoftLayer 的客户端对象。

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

接下来,为您要使用的 SoftLayer API 服务创建一个客户端对象。SoftLayer_SoapClient::getClient() 将为您照管这个对象,并接受四个参数:

  • 您要调用的服务的名称。
  • 您要使用的特定对象的可选 ID 号。请传递 null 值,前提是您正在使用 SoftLayer_Account 服务,或未在使用特定的服务器、支持凭单、发票或其他对象。在您的 API 调用中,此 ID 将创建一个初始化参数
  • 您的 API 用户名。
  • 您的 API 密钥。

以下代码片段提供了关于使用上述参数发出 SOAP 调用的示例:

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

准备好 API 客户端对象后,可调用 SoftLayer API 方法,如同它是客户端对象的本地方法一样。将 API 调用结果分配给一个变量,以获取该调用的结果。系统会将复杂类型对象作为 PHP stdClass 对象返回。同样,如果您需要将复杂类型参数传递至 API 调用,请使用 stdClass 对象。例如:

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;

使用 XML-RPC

SoftLayer API PHP 客户端互换地支持 SOAP 和 XML-RPC 协议。如果您要使用 XML-RPC(而不是 SOAP),那么需要做出两处更改:

  • 包含 XmlrpcClient.class.php(而不是 SoapClient.class.php
  • 使用 SoftLayer_XmlrpcClient::getClient()(而不是 SoftLayer_SoapClient::getClient())创建 API 客户端
    例如:
require_once('/path/to/SoftLayer/XmlrpcClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_XmlrpcClient::getClient('SoftLayer_Account' null, $apiUsername, $apiKey);

使用对象掩码

通过首先声明新的 SoftLayer_ObjectMask 对象,在 API 调用中创建对象掩码。定义您希望在新掩码对象中检索为本地属性的关系属性。最后,通过使用 setObjectMask() 方法,将其与 API 客户端绑定在一起。此示例将检索以下信息:

  • 帐户的物理硬件
  • 硬件的操作系统记录
  • 操作系统密码
  • 网络组件
  • 硬件所在的数据中心
  • 每个硬件中的处理器数目
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();

使用结果限制

当调用数据时,尤其是查询涉及到从较大组中抽取信息片段时,使用结果限制将极大地缩短返回的等待时间。
使用客户端对象的 setResultLimit() 方法来限制 API 调用中的结果数量。此方法接受两个参数:

  • 要为调用限制的结果数量。
  • 结果集开始的可选偏移量。
    以下示例包含用于设置结果限制的必需信息:
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();

错误处理

SoftLayer API 调用错误将作为异常由 PHP 客户端抛出。在 Try/Catch 块内调用 SoftLayer API 以确保正确处理。使用 PHP 异常类的 getMessage() 方法来访问 SoftLayer API 返回的错误。以下脚本包含此类错误的示例:

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

被引用的 API 组件

服务

数据类型

方法