Ruby

Ruby 用戶端可作為 softlayer_api Ruby gem。在大部分系統上,該指令會:

gem install softlayer_api

安裝 gem,並使它可供 Ruby Script 使用。gem 安裝在您電腦上的位置視 Ruby 的特定發行套件而定。如需相關資訊,請參閱發行套件的 gem 文件。

Ruby 用戶端的原始碼可在 SoftLayer 的 Github 專案中取得。

發出 API 呼叫

若要開始使用 Ruby 用戶端,您必須為您的程式碼將呼叫的每一個「API 服務」建立 SoftLayer::Service 類別的執行實例。若要建立執行實例,您必須提供程式庫將用來向 API 伺服器鑑別您帳戶的資訊。

建立服務物件之後,您將使用該服務物件在 SoftLayer API 中呼叫方法。

鑑別

該執行實例必須知道由您帳戶的使用者名稱和 API 金鑰組成的 API 鑑別資訊。此外,您還必須選取一個端點,即該用戶端用來聯絡 SoftLayer API 的網址。您可以透過廣域變數或透過將其傳遞到建構子來提供此資訊。

透過廣域變數提供鑑別資訊

「SoftLayer Ruby 用戶端」在 SoftLayer 名稱空間中利用三個廣域變數,它們與建立 SoftLayer::Service 類別的執行實例相關:

  • $SL_API_USERNAME:作為建立「服務」物件時使用的預設使用者名稱的字串
  • $SL_API_KEY:作為建立「服務」物件時使用的預設 API 金鑰的字串。
  • $SL_API_BASE_URL:服務所使用的端點基本網址。此變數預設為 API_PUBLIC_ENDPOINT

如果您將要建立許多不同的「服務」物件,而且它們全都要使用相同的鑑別資訊,則在這些廣域變數中設定值可能比較方便。

除了廣域變數之外,SoftLayer 名稱空間還定義兩個常數來代表 SoftLayer API 在私人和公有網路上的端點:

您可以透過將廣域變數 $SL_API_BASE_URL 設定為這兩個值的其中之一,來變更預設端點網址。

以下的範例會使用這些廣域變數來建立服務:

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

請注意,並未指定端點網址。預設端點網址是設為 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 金鑰作為雜湊值引數。此範例也透過 :endpoint_url 符號變更端點,因此該服務將在「SoftLayer 私密網路」上使用該 API:

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 編碼器來編碼的引數。通常這表示引數應該是雜湊值、陣列、字串、數字、布林或零。以下的範例會呼叫 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 採用一個引數,即您感興趣的物件的物件 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_ref 的變數,它透過 ticket_service 參照問題單 98765。這個 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

錯誤處理

Ruby 用戶端以異常狀況物件擲出 SoftLayer API 呼叫錯誤。請在 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 元件

服務

資料類型

方法