Ruby

Ruby クライアントは、softlayer_api Ruby gem として使用できます。大部分のシステムで、次のコマンドは、

gem install softlayer_api

gem をインストールし、Ruby スクリプトから使用できるようにします。コンピューター上のどこに gem がインストールされるかは、Ruby の特定のディストリビューションによって異なります。詳しくは、ご使用のディストリビューションの gem 資料を参照してください。

Ruby クライアントのソース・コードは、SoftLayer の github プロジェクトで入手できます。

API 呼び出しの実行

Ruby クライアントの使用を開始するには、コードが呼び出す API サービスごとに SoftLayer::Service クラスのインスタンスを作成する必要があります。このインスタンスを作成するには、API サーバーでアカウントを認証するのにライブラリーが使用する情報を提供する必要があります。

サービス・オブジェクトを作成した後、そのサービス・オブジェクトを使用して SoftLayer API でメソッドを呼び出します。

認証

そのインスタンスは、アカウントのユーザー名と API キーで構成される API 認証情報を認識する必要があります。さらに、エンドポイント、すなわち SoftLayer API への接続にクライアントが使用する Web アドレスを選択することも必要です。この情報はグローバル変数から提供するか、コンストラクターに渡すことによって提供することができます。

グローバル変数による認証情報の提供

SoftLayer Ruby クライアントは、SoftLayer::Service クラスのインスタンスの作成に関連した次の 3 つのグローバル変数を SoftLayer 名前空間で利用します。

  • $SL_API_USERNAME: サービス・オブジェクトの作成時に使用されるデフォルト・ユーザー名として使用されるストリング。
  • $SL_API_KEY: サービス・オブジェクトの作成時に使用されるデフォルト API キーとして使用されるストリング。
  • $SL_API_BASE_URL: サービスで使用されるエンドポイント・ベース URL。この変数はデフォルトで API_PUBLIC_ENDPOINT に設定されます。

多数の異なるサービス・オブジェクトを作成しようとしているときに、それらのオブジェクトがすべて同じ認証情報を使用する場合、これらのグローバル変数で値を設定すると便利な場合があります。

グローバル変数の他に、SoftLayer 名前空間は、プライベート・ネットワークとパブリック・ネットワークで SoftLayer API のエンドポイントを表す次の 2 つの定数を定義します。

  • API_PUBLIC_ENDPOINT: SoftLayer API のパブリック・ネットワーク REST ベース・エンドポイントの基底アドレスを含む定数 – https://api.softlayer.com/rest/v3/
  • API_PRIVATE_ENDPOINT: SoftLayer API のプライベート・ネットワーク REST ベース・エンドポイントの基底アドレスを含む定数 – https://api.service.softlayer.com/rest/v3/

グローバル変数 $SL_API_BASE_URL を上記の 2 つの値のいずれかに設定すると、デフォルトのエンドポイント URL を変更することができます。

これらのグローバル変数を使用してサービスを作成する例は次のとおりです。

$SL_API_USERNAME = "set me";
$SL_API_KEY = "set me"
 
account_service = SoftLayer::Service.new("SoftLayer_Account")

エンドポイント URL が指定されていないことに注目してください。デフォルトのエンドポイント URL は API_PUBLIC_ENDPOINT に設定されます。

コンストラクターによる認証情報の提供

サービス・オブジェクトで必要な認証情報をコンストラクターでハッシュ引数として提供することができます。ハッシュ引数で使用されるキーはシンボルであり、その値は次のストリングでなければなりません。

 :username      The username used to authenticate with the server.
 :api_key       The API key used to authenticate with the server.
 :endpoint_url  The endpoint address that will receive the method calls.

ユーザー名と API キーをハッシュ引数として提供する、グローバル変数に似た例は次のとおりです。また、この例では、サービスが SoftLayer プライベート・ネットワーク上の API を使用するように、:endpoint_url シンボルを使用してエンドポイントを変更します。

account_service = SoftLayer::Service.new("SoftLayer_Account",
    :username => "set me",
    :api_key => "set me",
    :endpoint_url => API_PRIVATE_ENDPOINT)

サービス・メソッドの呼び出し

SoftLayer::Service インスタンスがあると、そのサービスで提供されるメソッドを呼び出すことができます。サービスで API メソッドを呼び出すのは、サービス・オブジェクトで Ruby メソッドを呼び出すのと同じように簡単です。例えば、上記で作成された account_service オブジェクトがあるとすると、SoftLayer_Account サービスの getOpenTickets メソッドを使用してアカウントのオープン・チケットのリストを取得する呼び出しは、次のようになります。

open_tickets = account_service.getOpenTickets

メソッドで引数が必要な場合は、サービス・オブジェクトで呼び出すメソッドの引数として提供することができます。これらの引数は、json gem によって提供される JSON エンコーダーを使用してエンコードできる引数でなければなりません。通常、これは、引数がハッシュ、アレイ、ストリング、数値、ブール、または nil であることを意味します。SoftLayer_Dns_Domain::createObject を呼び出す例は次のとおりです。

#authentication information will be found in the global variables
domain_service = SoftLayer::Service.new("SoftLayer_Dns_Domain")
new_domain = domain_service.createObject(
{
    "name" => "example.org",
    "resourceRecords" => [
        {
            "host" => "@",
            "data" => "127.0.0.1",
            "type" => "a"
        }
    ]
})
 
puts "New domain id: #{new_domain.id}"

特定オブジェクトの識別

SoftLayer API における一部のメソッド呼び出しは、サービス自体ではなく、特定のオブジェクトに対して行われます。ただし、これらのオブジェクトは常にサービスによって取得されます。特定のオブジェクトに対するメソッドを呼び出すには、object_with_id への呼び出しを、該当するオブジェクトを提供するサービスにチェーニングすることができます。object_with_id は 1 つの引数、すなわちお客様が関心を持つオブジェクトのオブジェクト ID を取ります。例えば、チケット ID 123456 のチケットの取得に関心がある場合は、以下を呼び出すことができます。

ticket_of_interest = ticket_service.object_with_id(123456).getObject

この object_with_id 呼び出しは、サービスから特定のオブジェクトへの参照として使用できるオブジェクトを戻します。これを使用すると、object_with_id をすべての要求に繰り返し付加することなく、そのオブジェクトを複数回再利用することができます。例えば、ID 98765 を持つチケットを検出し、ユーザー 123456 に割り当てられる場合に更新を追加したい場合、次のようなコードを作成できます。

ticket_service = SoftLayer::Service.new("SoftLayer_Ticket")
 
begin
    ticket_ref = ticket_service.object_with_id(98765)
    ticket = ticket_ref.object_mask("assignedUserId").getObject
 
    if ticket['assignedUserId'] = 123456
 
        updates = ticket_ref.addUpdate({"entry" => "Get to work on these tickets!"})
    end
rescue Exception => exception
    puts "An error occurred while updating the ticket: #{exception}"
end

このコードは、ticket_service からチケット 98765 を参照する、ticket_ref という名前の変数を作成します。この ticket_ref は、チケットを取得するために object_mask と一緒に使用されます。チケットが条件付き要件を満たす場合、その同じ ticket_ref がチケットへの更新の追加に再利用されます。

オブジェクト・マスクの使用

ハッシュを使用して、API 呼び出しに「SoftLayer API でのオブジェクト・マスクの使用」を作成します。ハッシュ・キー名で取得したいリレーショナル・プロパティーを定義します。子プロパティーを取得する場合は、子プロパティーにネストされたハッシュを定義します。それ以外の場合は、キーの値として空ストリングを定義します。object_mask() メソッドを使用して、オブジェクト・マスクを API クライアントにバインドします。object_mask() は新しい API サービス参照を作成します。これは、object_with_id() メソッドと同じです。API 呼び出しと同じ行でオブジェクト・マスクを適用するか、または object_Mask() を使用して新しい API サービス参照を作成して、その結果で API メソッドを呼び出すことができます。

この例では、アカウントの物理ハードウェア記録を取得します。これには、そのハードウェアのオペレーティング・システム記録、オペレーティング・システム・パスワード、ネットワーク・コンポーネント、ハードウェアが存在するデータ・センター、各ハードウェア内のプロセッサーの数が含まれます。

require 'rubygems'
require 'softlayer_api'
 
account_service = SoftLayer::Service.new("SoftLayer_Account",
    :username => "set me",                                                                                                                                             
    :api_key => "set me")
 
# 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.
object_mask = {
     "hardware" => {
        "operatingSystem" => {
            "passwords" => "",
        },
        "networkComponents" => "",
        "datacenter" => "",
        "processorCount" => ""
    }
}
 
account = account_service.object_mask(object_mask).getHardware
 
# This will also work:
 
masked_service = account_service.object_mask(object_mask)
account = masked_service.getHardware

エラー処理

SoftLayer API 呼び出しエラーは、例外オブジェクトとして Ruby クライアントによってスローされます。適切な処理を確実にするには、begin/rescue ブロック内で SoftLayer API を呼び出してください。

require 'rubygems'
require 'softlayer_api'
 
account_service = SoftLayer::Service.new("SoftLayer_Account",
    :username => "set me",
    :api_key => "incorrect password")
 
# Exit the script with the message:
# "Unable to retrieve account information: Access Denied"
begin
    account = account_service.getObject
rescue Exception => exception
    puts "Unable to retrieve account information: #{exception}"
end

参照 API コンポーネント

サービス

データ・タイプ

メソッド