Ruby

Il client Ruby è disponibile come gem Ruby softlayer_api. Sulla maggior parte dei sistemi, il comando:

gem install softlayer_api

installa la gem e la rende disponibile agli script Ruby. Dove verrà installata la gem sul tuo computer dipenderà dalla specifica distribuzione di Ruby di cui disporrai. Per ulteriori informazioni, consulta la documentazione sulla gem per la tua distribuzione.

Il codice sorgente del client Ruby è disponibile nel progetto github di SoftLayer.

Effettuazione di chiamate API

Per iniziare a utilizzare il client Ruby, dovrai creare un'istanza della classe SoftLayer::Service per ciascuno dei servizi API che verranno richiamati dal
tuo codice. Per creare l'istanza, dovrai fornire informazioni che verranno utilizzate dalla libreria per autenticare il tuo account presso i server API.

Una volta creato un oggetto servizio, utilizzerai tale oggetto servizio per richiamare i metodi nell'API SoftLayer.

Autenticazione

L'istanza dovrà conoscere le tue informazioni di autenticazione API, ossia il nome utente del tuo account e la chiave API. Dovrai inoltre selezionare un endpoint, l'indirizzo web che verrà utilizzato dal client per contattare l'API SoftLayer. Puoi fornire queste informazioni mediante variabili globali oppure passandole al costruttore.

Come fornire le informazioni di autenticazione mediante variabili globali

Il client Ruby SoftLayer utilizza tre variabili globali, nello spazio dei nomi SoftLayer, correlate alla creazione di istanze della classe SoftLayer::Service:

  • $SL_API_USERNAME: una stringa utilizzata come nome utente predefinito impiegato quando si creano gli oggetti servizio
  • $SL_API_KEY: una stringa utilizzata come chiave API predefinita impiegata quando si creano oggetti servizio.
  • $SL_API_BASE_URL: l'URL di base dell'endpoint utilizzato dal servizio. Questa variabile ha come valore predefinito API_PUBLIC_ENDPOINT

Se creerai molti oggetti servizio differenti e utilizzeranno tutti le stesse informazioni di autenticazione, potrebbe essere comodo impostare i valori in queste variabili globali.

Oltre alle variabili globali, lo spazio dei nomi SoftLayer definisce due costanti che rappresentano gli endpoint per l'API SoftLayer sulle reti private e pubbliche:

Puoi modificare l'URL dell'endpoint predefinito impostando la variabile globale $SL_API_BASE_URL su uno di questi due valori.

Questo è un esempio di utilizzo di queste globali per creare un servizio:

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

Nota che l'URL dell'endpoint non è specificato. L'URL dell'endpoint predefinito è impostato su API_PUBLIC_ENDPOINT

Come fornire informazioni di autenticazione mediante il costruttore

Puoi fornire le informazioni di autenticazione di cui ha bisogno l'oggetto servizio come argomenti hash nel costruttore. Le chiavi utilizzate negli argomenti hash sono dei simboli i cui valori devono essere delle stringhe:

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

Questo è un esempio, analogo a quello per le variabili globali, che fornisce il nome utente e la chiave API come argomenti hash. Questo esempio modifica anche l'endpoint con il simbolo :endpoint_url in modo che il servizio utilizzi l'API sulla rete privata SoftLayer:

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

Richiamo dei metodi di servizio

Con un'istanza di SoftLayer::Service a disposizione, puoi richiamare i metodi forniti da tale servizio. Il richiamo di un metodo API su un servizio è facile come richiamare un metodo Ruby sull'oggetto servizio. Ad esempio, dati gli oggetti account_service creati in precedenza, una chiamata per ottenere un elenco dei ticket aperti su un account utilizzando il metodo getOpenTickets del servizio SoftLayer_Account si presenterebbe così:

open_tickets = account_service.getOpenTickets

Se il metodo richiede degli argomenti, è possibile fornirli come argomenti al metodo che stai richiamando sull'oggetto servizio. Gli argomenti devono essere codificabili con il codificatore JSON fornito dalla gem json. Generalmente questo significa che il tuo argomento deve essere hash, array, stringhe, numeri, booleani o nullo. Ecco un esempio di richiamo di 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}"

Identificazione di oggetti specifici

Alcune chiamate di metodo nell'API SoftLayer sono effettuate su specifici oggetti invece che sui servizi stessi. Questi oggetti, tuttavia, sono sempre ottenuti da un servizio. Per richiamare un metodo su uno specifico oggetto, è possibile concatenare una chiamata a object_with_id sul servizio che fornisce l'oggetto in questione. object_with_id accetta un argomento, l'ID dell'oggetto al quale sei interessato. Ad esempio, se sei interessato a ottenere il ticket con ID 123456, puoi farlo richiamando:

ticket_of_interest = ticket_service.object_with_id(123456).getObject

La chiamata object_with_id restituisce un oggetto che puoi utilizzare come un riferimento a uno specifico oggetto tramite il servizio. Questo ti consente di riutilizzare l'oggetto più volte senza dovere applicare ripetutamente object_with_id su tutte le tue richieste. Ad esempio, se vuoi trovare un ticket con ID 98765 e aggiungere un
aggiornamento ad esso se è assegnato all'utente 123456, puoi scrivere del codice come questo:

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

Il codice crea una variabile denominata ticket_ref che fa riferimento al ticket 98765 tramite il ticket_service. Questo ticket_ref viene utilizzato con una maschera oggetto per richiamare il ticket e, se il ticket soddisfa il requisito condizionale, questo stesso ticket_ref viene riutilizzato per aggiungere un aggiornamento al ticket.

Utilizzo delle maschere oggetto

Utilizza gli hash per creare un utilizzo delle maschere oggetto nell'API SoftLayer alla tua
chiamata API. Definisci le proprietà relazionali che vuoi richiamare nei tuoi nomi chiave hash. Se stai richiamando delle proprietà child, definisci un hash nidificato per la tua proprietà child, altrimenti definisci una stringa vuota come valore della tua chiave. Associa la tua maschera oggetto al tuo client
API con il metodo object_mask(). object_mask() crea un nuovo riferimento al servizio API, molto simile al metodo object_with_id(). Puoi applicare la tua maschera oggetto sulla stessa riga della tua chiamata API oppure creare un nuovo riferimento al servizio API con object_Mask() e richiamare il tuo metodo API sul suo risultato.

Questo esempio richiama i record di hardware fisico di un account insieme al record di sistema operativo di detto hardware, al record di sistema operativo, alle password del sistema operativo, ai componenti di rete, al datacenter su cui si trova l'hardware e al numero di processori in ciascun 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

Gestione degli errori

Gli errori di chiamata API SoftLayer sono generati dal client Ruby come oggetti eccezione. Effettua le chiamate alla API SoftLayer all'interno di blocchi begin/rescue per assicurare una corretta gestione.

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

Componenti API a cui si fa riferimento

Servizi

Tipi di dati

Metodi