Ruby

Ruby 客户端可作为 softlayer_api Ruby gem 来使用。在大多数系统上,以下命令:

gem install softlayer_api

可安装此 gem 并使其可用于 Ruby 脚本。此 gem 在计算机上的安装位置将取决于具体的 Ruby 发行版。请参阅您的发行版的 gem 文档,以获取更多信息。

SoftLayer 的 github 项目中提供了 Ruby 客户端的源代码。

发出 API 调用

要开始使用 Ruby 客户端,必须为您代码将调用的每一个 API 服务创建一个 SoftLayer::Service 类实例。要创建该实例,您必须提供相应信息,以供该库用来向 API 服务器认证您的帐户。

创建完服务对象后,您将使用此服务对象来调用 SoftLayer API 中的方法。

认证

该实例必须知道您的 API 认证信息(包含帐户用户名和 API 密钥)。此外,您还必须选择一个端点,这是供客户端用来联系 SoftLayer API 的 Web 地址。您可以通过全局变量或通过将全局变量传递到构造函数来提供这些信息。

通过全局变量提供认证信息

SoftLayer Ruby 客户端将在 SoftLayer 名称空间中使用三个全局变量,这些变量均与创建 SoftLayer::Service 类实例相关:

  • $SL_API_USERNAME:一个字符串,用作在创建“服务”对象时使用的默认用户名
  • $SL_API_KEY:一个字符串,用作在创建“服务”对象时使用的默认 API 密钥
  • $SL_API_BASE_URL:服务使用的端点基本 URL。此变量默认设置为 API_PUBLIC_ENDPOINT

如果您要创建大量不同的“服务”对象,并且这些对象都将使用相同的认证信息,那么通过为这些全局变量设置值,可以轻松做到这一点。

除全局变量外,SoftLayer 名称空间还定义了两个常量,分别表示专用网络和公用网络上 SoftLayer API 的端点:

您可以通过将全局变量 $SL_API_BASE_URL 设置为以下两个值之一来更改默认端点 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 密钥作为散列值参数提供。此示例还更改了具有 :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 编码器进行编码的参数。通常,这意味着参数应为散列值、数组、字符串、数字、布尔值或 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 将接受一个参数,即您感兴趣的对象的对象 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

错误处理

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

服务

数据类型

方法