Ruby

Le client Ruby est disponible en tant que gem Ruby softlayer_api. Sur la plupart des systèmes, la commande :

gem install softlayer_api

installe le gem et le met à la disposition des scripts Ruby. Le point d'installation du gem sur votre ordinateur dépendra de votre distribution particulière de Ruby. Pour plus de détails, reportez-vous à la documentation gem propre à votre distribution.

Le code source du client Ruby est disponible dans le projet github de SoftLayer.

Exécution d'appels API

Pour commencer à utiliser le client Ruby, vous allez devoir créer une instance de la classe SoftLayer::Service pour chacun des services API que votre code va appeler. Pour créer cette instance, il vous faudra fournir les informations que la bibliothèque utilisera pour authentifier votre compte auprès des serveurs API.

Une fois que vous aurez créé un objet de service, vous utiliserez cet objet pour appeler des méthodes dans l'API SoftLayer.

Authentification

L'instance créée devra connaître vos informations d'authentification API, soit votre nom d'utilisateur de compte et votre clé API. En outre, vous devrez sélectionner un point d'accès, c'est-à-dire l'adresse Web que le client utilisera pour contacter l'API SoftLayer. Vous pouvez fournir ces différentes informations soit par le biais de variables globales, soit en les transmettant au constructeur.

Utilisation de variables globales pour les informations d'authentification

Le client Ruby de SoftLayer utilise, dans l'espace de nom SoftLayer, trois variables globales liées à la création d'instances de la classe SoftLayer::Service :

  • $SL_API_USERNAME : Chaîne utilisée comme nom d'utilisateur par défaut lors de la création d'objets de service.
  • $SL_API_KEY : Chaîne utilisée comme clé API par défaut lors de la création d'objets de service.
  • $SL_API_BASE_URL : URL de base utilisée par le service pour le point d'accès. La valeur par défaut de cette variable est API_PUBLIC_ENDPOINT.

Si vous devez créer un grand nombre d'objets de service différents et si ces objets doivent tous utiliser les mêmes informations d'authentification, il vous sera peut-être plus commode de définir les valeurs dans ces variables globales.

Parallèlement aux variables globales, l'espace de nom SoftLayer permet de définir deux constantes représentant les points d'accès pour l'API SoftLayer sur les réseaux privés et publics :

Vous pouvez modifier l'URL par défaut du point d'accès en attribuant l'une des deux valeurs ci-dessus à la variable globale $SL_API_BASE_URL.

Voici un exemple d'utilisation de ces variables pour la création d'un service :

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

À noter que l'URL du point d'accès n'est pas spécifiée. L'URL par défaut prend la valeur API_PUBLIC_ENDPOINT.

Utilisation du constructeur pour les informations d'authentification

Les informations d'authentification requises par un objet de service peuvent être fournies en tant qu'arguments de hachage dans le constructeur. Les clés utilisées dans ces arguments sont des symboles dont les valeurs doivent être des chaînes :

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

L'exemple ci-après, comparable à l'exemple proposé pour les variables globales, fournit le nom d'utilisateur et la clé API en tant qu'arguments de hachage. Par ailleurs, cet exemple modifie le point d'accès avec le symbole :endpoint_url de telle sorte que le service utilise l'API sur le réseau privé SoftLayer :

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

Appel de méthodes de service

Avec une instance de SoftLayer::Service à disposition, vous pouvez appeler les méthodes fournies par un service donné. L'appel d'une méthode API sur ce service est aussi facile que l'appel d'une méthode Ruby sur l'objet de service. Par exemple, si l'on prend les objets account_service créés précédemment, un appel visant à extraire une liste des tickets ouverts sur un compte via la méthode getOpenTickets du service SoftLayer_Account se présentera comme suit :

open_tickets = account_service.getOpenTickets

Si la méthode exige des arguments, vous pouvez les fournir en tant que tels à la méthode que vous appelez sur l'objet de service. Ces arguments doivent pouvoir être codés avec le codeur JSON mis à disposition par le gem json. En règle générale, cela signifie que vos arguments doivent être de l'un des types suivants : hachage, tableau, chaîne, booléen ou nil. Voici un exemple appelant 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}"

Identification d'objets particuliers

Certains appels de méthode dans l'API SoftLayer s'effectuent sur des objets particuliers plutôt que sur les services eux-mêmes. Toutefois, ces objets sont toujours obtenus par l'intermédiaire d'un service. Pour appeler une méthode sur un objet particulier, vous pouvez chaîner un appel à object_with_id avec le service qui fournit l'objet en question. object_with_id prend un unique argument, à savoir l'ID de l'objet qui vous intéresse. Par exemple, si vous souhaitez trouver le ticket avec l'ID 123456, vous écrirez le code suivant :

ticket_of_interest = ticket_service.object_with_id(123456).getObject

L'appel object_with_id renvoie un objet que vous pouvez utiliser en tant que référence à un objet particulier via le service. Vous pouvez ainsi réutiliser cet objet à différentes reprises sans devoir indiquer object_with_id pour toutes vos demandes. Par exemple si vous voulez trouver un ticket avec l'ID 98765 et lui ajouter une mise à jour s'il est affecté à l'utilisateur 123456, vous pourrez écrire le code comme suit :

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

Le code ci-dessus crée une variable ticket_ref qui se réfère au ticket 98765 via le service ticket_service. Cette variable est utilisée avec un masque d'objet pour extraire le ticket, et si celui-ci remplit les conditions, cette même variable est réutilisée pour ajouter une mise à jour au ticket.

Utilisation de masques d'objet

Utilisez des hachages pour créer un (??? question posée sur TCT) Utilisation de masques d'objet dans l'API SoftLayer pour votre appel API. Définissez ensuite les propriétés relationnelles que vous souhaitez extraire dans vos noms de clé de hachage. Si vous voulez extraire des propriétés enfant, définissez un hachage imbriqué pour ces propriétés, Sinon, définissez une chaîne vide en tant que valeur de clé. Liez ensuite votre masque d'objet à votre client API avec la méthode object_mask(). Cette méthode object_mask() crée une nouvelle référence de service API de façon très comparable à la méthode object_with_id(). Vous pouvez soit appliquer votre masque d'objet sur la même ligne en tant qu'appel API, soit créer une nouvelle référence de service API avec object_mask(), puis appeler votre méthode API sur le résultat.

L'exemple ci-après extrait les enregistrements de matériel physique d'un compte, ainsi que l'enregistrement du système d'exploitation de ce matériel, les mots de passe du système d'exploitation, les composants réseau, le centre de données où se situe le matériel et le nombre de processeurs de chaque élément matériel :

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

Traitement des erreurs

Les erreurs d'appel API SoftLayer sont signalées par le client Ruby en tant qu'objets exception. Pour un traitement approprié, vous placerez les appels SoftLayer dans des blocs 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

Composants API référencés

financiers

Types de données

Méthodes