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에 접속할 때 사용하는 웹 주소, 엔드포인트를 선택해야 합니다. 글로벌 변수를 사용하거나 생성자에 전달하여 이 정보를 제공합니다.

Globals를 통해 인증 정보 제공

SoftLayer Ruby 클라이언트는 SoftLayer::Service 클래스 인스턴스 작성과 관련하여 SoftLayer 네임스페이스에서 3가지 글로벌 변수를 사용합니다.

  • $SL_API_USERNAME: 서비스 오브젝트 작성 시 사용되는 기본 사용자 이름 문자열
  • $SL_API_KEY: 서비스 오브젝트 작성 시 사용되는 기본 API 키 문자열
  • $SL_API_BASE_URL: 서비스에 사용되는 엔드포인트 기본 URL. 이 변수의 기본값은 API_PUBLIC_ENDPOINT입니다.

동일한 인증 정보를 사용하는 서로 다른 서비스 오브젝트를 다수 작성하는 경우, 이 글로벌에 값을 설정하면 편리합니다.

글로벌뿐만 아니라, SoftLayer 네임스페이스는 프라이빗 네트워크와 퍼블릭 네트워크에서 SoftLayer API의 엔드포인트를 나타내는 두 개의 상수를 정의합니다.

  • 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을 이 두 값 중 하나로 설정하여 기본 엔드포인트 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는 해당 오브젝트의 오브젝트 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()object_with_id() 메소드와 매우 비슷한 새로운 API 서비스 참조를 작성합니다. 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 호출 오류가 예외 오브젝트로 발생합니다. 올바른 처리를 위해 SoftLayer API에 대한 호출을 begin/rescue 블록 안에 배치합니다.

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 구성요소

서비스

데이터 유형

메소드