Perl

SoftLayer 提供以 Perl 為基礎的 API 用戶端,承擔起發出手動 SOAP API 呼叫的重任。若要使用此 API 用戶端,必須符合下列系統需求:

  • Perl 5.6 或更高版本
  • SOAP::Lite
  • XML::Hash::LX

從 SoftLayer 的 Github 設定檔的專案頁面中下載 SoftLayer Perl API 用戶端。下載之後,將 Perl API 用戶端解壓縮到 Perl 專案的本端目錄或 Perl 安裝的 @INC 路徑。

下載 SoftLayer API Perl 用戶端

發出 API 呼叫

下載及安裝 API 用戶端之後,首要任務是在 Script 中包含 SoftLayer::API::SOAP 模組。此檔案定義 SoftLayer 的用戶端物件。在包括該模組之前,您可能必須將該模組的上層目錄加入到 @INC 路徑。請使用下列程式碼加入上層目錄:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;

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

  • 您想要呼叫的服務名稱。
  • 您想要使用的特定物件的選用 ID 號碼。請傳遞 undef 值,如果您使用 SoftLayer_Account 服務,或者未使用特定的伺服器、支援問題單、發票或其他物件。這個 ID 會在 API 呼叫中建立起始設定參數
  • API 使用者名稱。
  • API 金鑰。
    以下的程式碼 Snippet 提供利用上述參數發出 API 呼叫的範例:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
# Create a client to the SoftLayer_Account API service.
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
 
# Work directly with the SoftLayer_Hardware_Server record with the hardware id 
# 1234.
#my $server_id = 1234;
#my $client = SoftLayer::API::SOAP->new('SoftLayer_Hardware_Server', $server_id, $api_username, $api_key);

當 API 用戶端物件 ($client) 備妥之後,請呼叫 SoftLayer API 方法,就如同它在用戶端物件的本端一樣。將 API 呼叫的結果指派給一個變數,以取得該呼叫的結果。複式類型物件以經過 bless 處理的雜湊值傳回,作為呼叫的傳回類型。同樣地,如果您需要將複式類型參數傳遞至 API 呼叫,請使用雜湊值、包含雜湊值的雜湊值或包含陣列的雜湊值。例如:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
my $domain_id = 1234;
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', $domain_id, $api_username, $api_key);
 
# Create a new A record in a domain.
my $new_record = $client->createARecord('myhost', '127.0.0.1', 86400);
 
print 'New A record id: ' . $new_record->{id}; 
 
# Create a new domain record. 
#
# This requires an API client with an undef id, and use a hash with an array to model 
# our new domain.
$client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', undef, $api_username, $api_key);
 
my $domain = {
    'name' => 'example.org',
    'resourceRecords' => [
        {
            'host' => '@',
            'data' => '127.0.0.1',
            'type' => 'a',
        }
    ]
};
 
my $new_domain = $client->createObject($domain);
 
print 'New domain id: ' . $new_domain->{id};
If you wish, you can declare your client object and make an API call on a single line.  The following code outlines this scenario:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $account = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key)->getObject();

使用物件遮罩

使用巢狀雜湊值變數,為 API 呼叫建立一個物件遮罩。定義您想要擷取作為雜湊值金鑰的關聯式內容。如果您要擷取子項內容,請為子項內容定義巢狀雜湊值。否則,請定義空白雜湊值作為金鑰值。透過 the setObjectMask() 方法,將物件遮罩連結到 API 用戶端。此範例會擷取帳戶的實際硬體記錄,以及該硬體的作業系統記錄、作業系統密碼、網路元件、該硬體所在的資料中心,和每一個硬體中的處理器數目:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# 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.
my $object_mask = {
    'hardware' => {
        'operatingSystem' => {
            'passwords' => {},
        },
        'networkComponents' => {},
        'datacenter' => {},
        'processorCount' => {},
    }
};
 
$client->setObjectMask($object_mask);
 
my $hardware = $client->getHardware();

使用結果限制

呼叫資料時,尤其是涉及從較大群組取回資訊 Snippet 的查詢,利用結果限制將大幅減少您等待傳回的時間。
透過用戶端物件的 setResultLimit() 方法,來限制 API 呼叫中的結果數。此方法採用兩個參數:

  • 限制呼叫的結果數。
  • 開始結果集的選用偏移。

下列程式碼提供的範例是在 API 呼叫中使用結果限制。

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# Retrieve our first two open support tickets.
$client->setResultLimit(2);
 
$tickets = $client->getOpenTickets();

錯誤處理

如果 SoftLayer API 呼叫發生 SOAP 錯誤,則您的用戶端物件中將移入 faultfaultstring 內容。在發出 API 呼叫來進行有效的錯誤處理之後,請檢查 fault 內容。如果呼叫發生錯誤,則 faultstring 內容包含 SoftLayer API 傳回的錯誤。下列 Script 包含這類錯誤的範例:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'an incorrect key';
 
$client = SoftLayer::API::SOAP->new('SoftLayer_Account', null, $api_username, $api_key);
 
# Exit the script with the message:
# "Unable to retrieve account information: Invalid API key"
my $account = $client->getObject();
 
if ($account->fault) {
    die 'Unable to retrieve account information: ' . $account->faultstring;
}

參照的 API 元件

服務

資料類型

方法