Perl

SoftLayer が提供する Perl ベースの API クライアントは、手動の SOAP API 呼び出しから面倒な作業を取り除きます。この API クライアントを使用するには、以下のシステム要件が満たされなければなりません。

  • Perl 5.6 以上
  • SOAP::Lite
  • XML::Hash::LX

SoftLayer の github プロファイルのプロジェクト・ページから、SoftLayer Perl API クライアントをダウンロードします。ダウンロード後、Perl プロジェクトのローカル・ディレクトリー、または Perl インストール済み環境の @INC パスに Perl API クライアントを抽出します。

Download the SoftLayer API Perl client

API 呼び出しの実行

API クライアントがダウンロードされ、インストールされた後、最初の作業は、SoftLayer::API::SOAP モジュールをスクリプトに組み込むことです。このファイルは SoftLayer のクライアント・オブジェクトを定義します。モジュールを組み込む前に、モジュールの親ディレクトリーを @INC パスに追加する必要がある場合があります。次のコードを使用して親ディレクトリーを追加してください。

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

次に、使用したい SoftLayer API サービス用のクライアント・オブジェクトを作成します。SoftLayer::API::SOAP->new() はこれを処理し、4 つのパラメーターを使用します。

  • 呼び出したいサービスの名前。
  • 作業する特定のオブジェクトのオプションの ID 番号。SoftLayer_Account サービスを処理するか、特定のサーバー、サポート・チケット、請求書、またはその他のオブジェクトを処理しない場合は、undef 値を渡します。この ID は、API 呼び出しで 初期化パラメーター を作成します。
  • 自分の API ユーザー名。
  • 自分の API キー。
    以下のコード・スニペットは、上記で概要が示されたパラメーターを使用して 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 呼び出しの結果を変数に割り当てて、呼び出しの結果を取得します。複合タイプのオブジェクトは、呼び出しの戻りの型としてハッシュ blessed として戻されます。同様に、複合タイプのパラメーターを 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();

結果制限の使用

データを呼び出す際、特に大規模グループから情報のほんの一部を引き出す照会を呼び出す場合、結果の制限を使用することで、戻りまでの待ち時間を大幅に減らすことができます。
クライアント・オブジェクトの setResultLimit() メソッドを使用して、API 呼び出しの結果の数を制限します。このメソッドは 2 つのパラメーターを使用します。

  • 呼び出しを制限するための結果の数。
  • 結果セットを開始するオプションのオフセット。

以下のコードは、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();

エラー処理

SOAP 障害が SoftLayer API 呼び出しによってスローされた場合、クライアント・オブジェクトには、fault プロパティーと faultstring プロパティーが取り込まれます。API 呼び出し後に、有効なエラー処理がないか fault プロパティーを調べてください。呼び出しにエラーがあった場合、faultstring プロパティーには、SoftLayer API によって戻されたエラーが含まれています。以下のスクリプトはこれらのエラーの例を含んでいます。

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 コンポーネント

サービス

データ・タイプ

メソッド