Ruby

El cliente Ruby está disponible como la gema Ruby softlayer_api. En la mayoría de los sistemas, el mandato:

gem install softlayer_api

instala la gema para que esté disponible para los scripts Ruby. El lugar donde se instala la gema en el sistema dependerá de su distribución específica de Ruby. Consulte la documentación de la gema correspondiente a su distribución para obtener más información.

El código fuente del cliente Ruby está disponible en el proyecto GitHub de SoftLayer.

Realización de llamadas de API

Para empezar a utilizar el cliente Ruby, deberá crear una instancia de la clase SoftLayer::Service para cada uno de los servicios de API que invocará el código. Para crear la instancia, deberá proporcionar la información que la biblioteca utilizará para autenticar su cuenta con los servidores de API.

Una vez creado un objeto de servicio, lo utilizará para invocar métodos en la API de SoftLayer.

Autenticación

La instancia deberá conocer la información de autenticación de la API, que consiste en el nombre de usuario de la cuenta y la clave de API. Asimismo, deberá seleccionar un punto final, la dirección web que el cliente utilizará para ponerse en contacto con la API de SoftLayer. Puede proporcionar esta información utilizando variables globales o pasándolas al constructor.

Proporcionar la información de autenticación mediante variables globales

El cliente Ruby de SoftLayer utiliza tres variables globales en el espacio de nombres de SoftLayer relacionadas con la creación de instancias de la clase SoftLayer::Service:

  • $SL_API_USERNAME: una serie que se utiliza como nombre de usuario predeterminado cuando se crean objetos de servicio.
  • $SL_API_KEY: una serie que se utiliza como clave de API predeterminada cuando se crean objetos de servicio.
  • $SL_API_BASE_URL: el URL base del punto final que utiliza el servicio. Esta variable toma el valor predeterminado API_PUBLIC_ENDPOINT.

Si va a crear muchos objetos de servicio diferentes y todos van a utilizar la misma información de autenticación, se recomienda establecer los valores en estas variables globales.

Además de las variables globales, el espacio de nombre de SoftLayer define dos constantes que representan los puntos finales de la API de SoftLayer en las redes privada y pública:

Puede cambiar el URL de punto final predeterminado estableciendo la variable general $SL_API_BASE_URL en cualquiera de estos dos valores.

A continuación, se muestra un ejemplo de uso de estas variables globales para crear un servicio:

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

Observe que no se ha especificado el URL de punto final. El URL de punto final predeterminado se establece en API_PUBLIC_ENDPOINT.

Proporcionar la información de autenticación mediante el constructor

Puede proporcionar la información de autenticación que necesita un objeto de servicio como argumentos hash en el constructor. Las claves utilizadas en los argumentos hash son símbolos cuyos valores deben ser series:

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

A continuación, se muestra un ejemplo análogo a una de las variables globales que proporciona el nombre de usuario y la clave de API como argumentos hash. Este ejemplo también cambia el punto final por el símbolo :endpoint_url, para que el servicio utilice la API en la red privada de SoftLayer:

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

Invocación de métodos de servicio

Con una instancia de SoftLayer::Service a mano, puede invocar los métodos proporcionados por ese servicio. La invocación de un método de API en un servicio es tan sencilla como la invocación de un método Ruby en el objeto de servicio. Por ejemplo, dados los objetos account_service creados anteriormente, una llamada para obtener una lista de los tíquets en una cuenta utilizando el método getOpenTickets del servicio SoftLayer_Account será parecida a la siguiente:

open_tickets = account_service.getOpenTickets

Si el método requiere argumentos, puede proporcionarlos como argumentos al método que está invocando en el objeto de servicio. Los argumentos deberán ser argumentos que puedan codificarse utilizando el codificador JSON que proporciona la gema json. Generalmente, esto significa que los argumentos deberán ser hashes, matrices, series, números, booleanos o nulos. A continuación, se muestra un ejemplo de una invocación de 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}"

Identificación de objetos concretos

Algunas llamadas de método en la API de SoftLayer se realizan en objetos concretos, en lugar de en los propios servicios. No obstante, estos objetos siempre los obtiene un servicio. Para invocar un método en un determinado objeto, puede encadenar una llamada a object_with_id en el servicio que proporciona el objeto en cuestión. object_with_id utiliza un argumento, el ID del objeto en el que está interesado. Por ejemplo, si está interesado en obtener el tíquet con un ID de tíquet 123456, invoque:

ticket_of_interest = ticket_service.object_with_id(123456).getObject

La llamada object_with_id devuelve un objeto que puede utilizar como referencia a un objeto concreto a través del servicio. Esto permite reutilizar el objeto varias veces sin necesidad de tener que adjuntar repetidamente object_with_id en todas las solicitudes. Por ejemplo, si desea encontrar un tíquet con el ID 98765 y añadirle una actualización si está asignado al usuario 123456, puede escribir un código como el siguiente:

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

El código crea una variable denominada ticket_ref, que hace referencia al tíquet 98765 mediante ticket_service. La variable ticket_ref se utiliza con object_mask para recuperar el tíquet y, si el tíquet cumple el requisito condicional, se reutiliza la misma variable ticket_ref para añadir una actualización al tíquet.

Utilización de máscaras de objeto

Utilice hashes para crear una Using Object Masks in the SoftLayer API en la llamada de API. Defina las propiedades relacionales que desee recuperar en los nombres de clave hash. Si está recuperando propiedades hijo, defina un hash anidado para la propiedad hijo; de lo contrario, defina una serie vacía como valor de la clave. Enlace la máscara de objeto al cliente de API con el método object_mask(). object_mask() crea una nueva referencia de servicio de API, de forma parecida al método object_with_id(). Puede aplicar la máscara de objeto en la misma línea que la llamada de API o crear una nueva referencia de servicio de API con object_Mask() e invocar el método de API en su resultado.

En este ejemplo, se recuperan los registros de hardware físico de una cuenta, junto con el registro del sistema operativo del hardware, las contraseñas del sistema operativo, los componentes de red, el centro de datos donde se encuentra el hardware y el número de procesadores en 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

Manejo de errores

El cliente Ruby genera los errores de llamada de API de SoftLayer como objetos de excepción. Realice llamadas a la API de SoftLayer dentro de bloques begin/rescue para garantizar un manejo correcto.

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 de API referenciados

Servicios

Tipos de datos

Métodos