Ruby

O cliente Ruby está disponível como a gem Ruby softlayer_api. Na maioria dos sistemas, o comando:

gem install softlayer_api

instala a gem e a torna disponível para scripts Ruby. Onde a gem será instalada em seu computador dependerá da distribuição específica do Ruby. Consulte a documentação da gem para sua distribuição para obter mais informações.

O código-fonte do cliente Ruby está disponível no projeto github da SoftLayer.

Fazendo chamadas de API

Para começar a usar o cliente Ruby, será necessário criar uma instância da classe SoftLayer::Service para cada um dos Serviços da API que o código chamará. Para criar a instância, será necessário fornecer informações que a biblioteca usará para autenticar sua conta com os servidores da API.

Após ter criado um objeto de serviço, esse objeto de serviço será usado para chamar métodos na API da SoftLayer.

Autenticação

Essa instância precisará saber as informações sobre autenticação da API que consistem no nome do usuário da conta e na chave da API. Além disso, será necessário selecionar um terminal, o endereço da web que o cliente usará para contatar a API da SoftLayer. Essas informações podem ser fornecidas por meio de variáveis globais ou passando as mesmas ao construtor.

Fornecendo informações sobre autenticação por meio de globais

O cliente Ruby da SoftLayer usa três variáveis globais no namespace da SoftLayer relacionadas à criação de instâncias da classe SoftLayer::Service:

  • $SL_API_USERNAME: uma sequência usada como o nome do usuário padrão ao criar objetos de Serviço
  • $SL_API_KEY: uma sequência usada como a chave da API padrão usada ao criar objetos de Serviço.
  • $SL_API_BASE_URL: a URL base do terminal usada pelo serviço. Essa variável usa como padrão API_PUBLIC_ENDPOINT

Se você for criar muitos objetos de Serviço diferentes e eles forem usar as mesmas informações sobre autenticação, pode ser conveniente configurar os valores nessas globais.

Além das globais, o namespace da SoftLayer define duas constantes que representam os terminais para a API da SoftLayer nas redes privadas e públicas:

É possível mudar a URL de terminal padrão configurando a variável global $SL_API_BASE_URL para um desses dois valores.

Segue um exemplo de como usar essas globais para criar um serviço:

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

Observe que a URL de terminal não está especificada. A URL de terminal padrão está configurada para API_PUBLIC_ENDPOINT

Fornecendo informações sobre autenticação por meio do construtor

É possível fornecer as informações sobre autenticação necessárias para um objeto de Serviço como argumentos hash no construtor. As chaves usadas nos argumentos hash são símbolos cujos valores devem ser sequências:

 :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.

Segue um exemplo, análogo àquele para variáveis globais, que fornece o nome do usuário e a chave da API como argumentos hash. Este exemplo também muda o terminal com o símbolo :endpoint_url de forma que o serviço usará a API na rede privada da SoftLayer:

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

Chamando métodos de serviços

Com uma instância de SoftLayer::Service em mãos, é possível chamar os métodos fornecidos por esse serviço. Chamar um método da API em um serviço é tão fácil quanto chamar um método Ruby no objeto de serviço. Por exemplo, considerando os objetos account_service criados acima, uma chamada para obter uma lista dos chamados abertos em uma conta usando o método getOpenTickets do serviço SoftLayer_Account teria a aparência a seguir:

open_tickets = account_service.getOpenTickets

Se o métodos precisar de argumentos, será possível fornecê-los como argumentos para o método que está sendo chamado no objeto de serviço. Os argumentos devem ser argumentos que podem ser codificados usando o codificador JSON fornecido pela gem json. Em geral, isso significa que o argumento deve ser hashes, matrizes, sequências, números, booleanos ou inexistente. Segue um exemplo de como chamar 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}"

Identificando objetos específicos

Algumas chamadas de métodos na API da SoftLayer são feitas em objetos específicos, em vez de nos próprios serviços. Esses objetos, no entanto, são sempre obtidos por um serviço. Para chamar um método em um objeto específico, será possível encadear uma chamada a object_with_id no serviço que fornece o objeto em questão. object_with_id aceita um argumento, o ID do objeto no qual você está interessado. Por exemplo, se você estiver interessado em obter o chamado com um ID de chamado igual a 123456, é possível fazer isso chamando:

ticket_of_interest = ticket_service.object_with_id(123456).getObject

A chamada object_with_id retorna um objeto que pode ser usado como uma referência para um objeto específico por meio do serviço. Isso permite reutilizar esse objeto diversas vezes sem precisar afixar object_with_id repetidamente em todas as suas solicitações. Por exemplo, se desejar localizar um chamado com o ID 98765 e incluir uma atualização no mesmo se estiver atribuído ao usuário 123456, você poderá escrever código como este:

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

O código cria uma variável denominada ticket_ref que refere-se ao chamado 98765 por meio do ticket_service. Essa ticket_ref é usada com uma object_mask para recuperar o chamado e, se o chamado atender o requisito condicional, essa mesma ticket_ref será reutilizada para incluir uma atualização no chamado.

Usando máscaras de objetos

Use hashes para criar Usando máscaras de objetos na API da SoftLayer para sua chamada API. Defina as propriedades relacionais que deseja recuperar nos nomes das chaves de hash. Se estiver recuperando propriedades-filhas, então, defina um hash aninhado para a propriedade-filha, caso contrário, defina uma sequência de caracteres vazia como o valor da chave. Ligue a máscara de objeto ao cliente da API com o método object_mask(). object_mask() cria uma nova referência de serviço da API, muito semelhante ao método object_with_id(). É possível aplicar a máscara de objeto na mesma linha que sua chamada API ou criar nova referência de serviço da API com object_Mask() e chamar o método da API em seu resultado.

Este exemplo recupera os registros de hardware físico de uma conta com o registro do sistema operacional desse hardware, senhas do sistema operacional, componentes da rede, o datacenter no qual o hardware está localizado e o número de processadores em cada hardware:

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

Manipulação de erros

Erros de chamada API da SoftLayer são lançados pelo cliente Ruby como objetos de exceções. Faça chamadas à API da SoftLayer em blocos de iniciar/recuperar para assegurar a manipulação adequada.

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

Componentes da API referidos

Serviços

Tipos de dados

Métodos