Ruby

Der Ruby-Client ist als Ruby Gem softlayer_api verfügbar. Auf den meisten Systemen wird mit dem Befehl:

gem install softlayer_api

das Gem installiert und für Ruby-Scripts zur Verfügung gestellt. Wo das Gem auf Ihrem Computer installiert ist, hängt von Ihrer jeweiligen Distribution von Ruby ab. Weitere Informationen sind in der Gem-Dokumentation für Ihre Distribution enthalten.

Der Quellcode des Ruby-Client ist im SoftLayer GitHub-Projekt verfügbar.

Durchführung von API-Aufrufen

Damit Sie den Ruby-Client verwenden können, müssen Sie eine Instanz der SoftLayer::Service-Klasse für jeden der API-Services erstellen, den Ihr Code aufrufen wird. Für die Erstellung der Instanz müssen Sie Informationen bereitstellen, die die Bibliothek verwendet, um Ihren Account für die API-Server zu authentifizieren.

Sobald Sie ein Serviceobjekt erstellt haben, verwenden Sie dieses Serviceobjekt, um in der SoftLayer-API Methoden aufzurufen.

Authentifizierung

Diese Instanz muss Ihre API-Authentifizierungsdaten kennen, die aus Ihrem Benutzernamen und dem API-Schlüssel bestehen. Darüber hinaus müssen Sie einen Endpunkt auswählen, also die Webadresse, die der Client verwendet, um die SoftLayer-API zu kontaktieren. Sie können diese Informationen entweder über globale Variablen oder durch Weitergabe an den Konstruktor bereitstellen.

Authentifizierungsdaten über globale Variablen bereitstellen

Der Ruby-Client von SoftLayer verwendet drei globale Variablen im SoftLayer-Namensbereich, die im Zusammenhang mit der Erstellung von Instanzen der SoftLayer::Service-Klasse stehen:

  • $SL_API_USERNAME: Eine Zeichenfolge, die als Standardbenutzername für die Erstellung von Serviceobjekten verwendet wird.
  • $SL_API_KEY: Eine Zeichenfolge, die als Standard-API-Schlüssel für die Erstellung von Serviceobjekten verwendet wird.
  • $SL_API_BASE_URL: Die vom Service verwendete Basis-URL des Endpunkts. Diese Variable hat standardmäßig den Wert API_PUBLIC_ENDPOINT.

Wenn Sie viele verschiedene Serviceobjekte erstellen, die alle dieselben Authentifizierungsdaten verwenden, kann es sinnvoll sein, die Werte in diesen globalen Variablen festzulegen.

Zusätzlich zu den globalen Variablen definiert der SoftLayer-Namensbereich zwei Konstanten, die die Endpunkte für die SoftLayer-API in den privaten und öffentlichen Netzwerken darstellen:

Sie können die Standard-Endpunkt-URL ändern, indem Sie die globale Variable $SL_API_BASE_URL auf einen dieser beiden Werte festlegen.

Hier ein Beispiel, wie diese globalen Variablen verwendet werden, um einen Service zu erstellen:

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

Bitte berücksichtigen Sie, dass die Endpunkt-URL nicht angegeben ist. Die Standard-Endpunkt-URL ist auf API_PUBLIC_ENDPOINT festgelegt.

Authentifizierungsdaten über den Konstruktor bereitstellen

Sie können die Authentifizierungsdaten, die von einem Serviceobjekt benötigt werden, als Hash-Argumente im Konstruktor bereitstellen. Bei den in den Hash-Argumenten verwendeten Schlüsseln handelt es sich um Symbole, deren Werte Zeichenfolgen sein sollten:

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

Nachstehend ein Beispiel analog zu dem für globale Variablen, in dem Benutzername und API-Schlüssel als Hash-Argumente bereitgestellt werden. Dieses Beispiel ändert auch den Endpunkt mit dem :endpoint_url-Symbol, sodass der Service die API im privaten Netzwerk von SoftLayer verwendet:

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

Servicemethoden aufrufen

Mit einer Instanz von SoftLayer::Service können Sie die von diesem Service bereitgestellten Methoden aufrufen. Das Aufrufen einer API-Methode in einem Service ist genauso einfach wie das Aufrufen einer Ruby-Methode im Serviceobjekt. Angesichts der oben erstellten account_service-Objekte würde ein Aufruf zur Abfrage einer Liste der offenen Tickets in einem Account unter Verwendung der getOpenTickets-Methode des SoftLayer_Account-Service z. B. wie folgt aussehen:

open_tickets = account_service.getOpenTickets

Sollten für die Methode Argumente erforderlich sein, können Sie diese als Argumente für die Methode bereitstellen, die Sie im Serviceobjekt aufrufen. Bei den Argumenten sollte es sich um Argumente handeln, die mit dem JSON-Encoder des JSON Gem codiert werden können. Im Allgemeinen bedeutet das, dass Ihr Argument aus Hashes, Arrays, Zeichenfolgen, Zahlen, booleschen Werten oder Nullwerten bestehen sollte. Beispiel für den Aufruf von 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}"

Bestimmte Objekte identifizieren

Einige Methodenaufrufe in der SoftLayer-API werden in bestimmten Objekten statt in den Services selbst durchgeführt. Diese Objekte werden jedoch grundsätzlich von einem Service angefordert. Wenn Sie eine Methode in einem bestimmten Objekt aufrufen möchten, können Sie einen Aufruf für object_with_id mit dem Service verketten, der das besagte Objekt bereitstellt. object_with_id verwendet ein Argument, die Objekt-ID des Objekts, an dem Sie interessiert sind. Wenn Sie beispielsweise daran interessiert wären, das Ticket mit der Ticket-ID 123456 abzurufen, könnten Sie dies durch folgenden Aufruf erreichen:

ticket_of_interest = ticket_service.object_with_id(123456).getObject

Der Aufruf object_with_id gibt ein Objekt zurück, das Sie während des Service als Verweis auf ein bestimmtes Objekt verwenden können. So können Sie dieses Objekt mehrmals wiederverwenden, ohne object_with_id immer wieder für alle Anforderungen angeben zu müssen. Wenn Sie z. B. ein Ticket mit der ID 98765 suchen und diesem ein Update hinzufügen möchten, sofern es Benutzer 123456 zugeordnet ist, könnten Sie folgenden Code verwenden:

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

Der Code erstellt eine Variable mit dem Namen ticket_ref, der sich während des Ticket-Service auf das Ticket 98765 bezieht. Diese ticket_ref-Variable wird mit einer object_mask-Variablen verwendet, um das Ticket abzurufen. Wenn das Ticket den Bedingungen entspricht, wird dieselbe ticket_ref-Variable verwendet, um dem Ticket ein Update hinzuzufügen.

Verwendung von Objektmasken

Verwenden Sie Hashes, um Using Object Masks in the SoftLayer API für Ihren API-Aufruf zu erstellen. Definieren Sie die relationalen Eigenschaften, die Sie in Ihren Hashschlüsselnamen abrufen möchten. Wenn Sie untergeordnete Eigenschaften abrufen, definieren Sie einen verschachtelten Hash für die untergeordnete Eigenschaft. Ansonsten definieren Sie eine leere Zeichenfolge als Schlüsselwert. Binden Sie Ihre Objektmaske mit der Methode object_mask() an Ihren API-Client. object_mask() erstellt eine neue API-Servicereferenz, vergleichbar mit der object_with_id()-Methode. Sie können Ihre Objektmaske entweder auf dieselbe Zeile anwenden wie Ihren API-Aufruf oder mit object_Mask() eine neue API-Servicereferenz erstellen und basierend auf dem Ergebnis Ihre API-Methode aufrufen.

In diesem Beispiel werden die physischen Hardwaredatensätze eines Accounts sowie der Betriebssystemdatensatz der Hardware, die Betriebssystemkennwörter, die Netzwerkkomponenten, das Rechenzentrum, in dem sich die Hardware befindet, und die Anzahl Prozessoren in der jeweiligen Hardware abgerufen:

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

Fehlerbehandlung

Fehler beim Aufruf der SoftLayer-API werden vom Ruby-Client als Ausnahmebedingungsobjekte ausgelöst. Führen Sie Aufrufe der SoftLayer-API in Begin/Rescue-Blocks durch, um eine ordnungsgemäße Abwicklung sicherzustellen.

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

Referenzierte API-Komponenten

Services

Datentypen

Methoden