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 用戶端之後,首要任務是在 Script 中包含 SoapClient.class.php 檔案。此檔案定義 SoftLayer 的用戶端物件。

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

接下來,為您想要使用的 SoftLayer API 服務建立一個用戶端物件。SoftLayer_SoapClient::getClient() 將為您完成這項工作並採用四個參數:

  • 您想要呼叫的服務名稱。
  • 您想要使用的特定物件的選用 ID 號碼。請傳遞 null值,如果您使用 SoftLayer_Account 服務,或者未使用特定的伺服器、支援問題單、發票或其他物件。這個 ID 會在 API 呼叫中建立起始設定參數
  • API 使用者名稱。
  • API 金鑰。

以下的程式碼 Snippet 提供利用上述參數發出 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);

使用物件遮罩

在 API 呼叫中建立物件遮罩,首先宣告一個新 SoftLayer_ObjectMask 物件。定義您想要擷取作為新遮罩物件中的區域內容的關聯式內容。最後,使用 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();

使用結果限制

呼叫資料時,尤其是涉及從較大群組取回資訊 Snippet 的查詢,利用結果限制將大幅減少您等待傳回的時間。
透過用戶端物件的 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();

錯誤處理

PHP 用戶端以異常狀況擲出 SoftLayer API 呼叫錯誤。請在 Try/Catch 區塊內對 SoftLayer API 發出呼叫,以確保適當的處理。使用 PHP 異常狀況類別的 getMessage() 方法,來存取 SoftLayer API 傳回的錯誤。下列 Script 包含這類錯誤的範例:

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 元件

服務

資料類型

方法