Masques d'objet

Présentation

Pour obtenir les données relationnelles d'un objet de l'API, vous devez déclarer un masque d'objet dans votre appel de l'API. Les masques d'objet standard extraient les données relationnelles à l'aide d'un en-tête SOAP, d'une structure XML-RPC ou d'un paramètre GET dans REST. Les masques d'objet étendus utilisent un langage dédié pour indiquer plus rapidement les données qui doivent être renvoyées par l'API. Pour prendre en charge cette nouvelle méthode de masque d'objet, une nouvelle méthode d'entrée a été ajoutée à chaque protocole.

Structure

Nœud racine

Les masques d'objet étendus prennent leur origine à partir d'un "nœud racine" qui est un ensemble de propriétés ou une chaîne de "masque" jouant le rôle d'alias de l'objet renvoyé par l'appel d'API. Par exemple, lorsque vous appelez SoftLayer_Hardware::getObject, le nœud racine "masque" représente un objet SoftLayer_Hardware.

Si nous devions envoyer "mask" en tant que masque d'objet de SoftLayer_Hardware::getObject, tout l'objet SoftLayer_Hardware serait renvoyé comme si aucun masque n'était inclus.

Propriété

Une propriété est le nom d'une propriété locale ou relationnelle du type d'objet renvoyé et est ajoutée au masque et précédée d'un point : ".".

mask.networkComponents

Le masque d'objet ci-dessus utilisé lors de l'appel de SoftLayer_Hardware::getObject renvoie l'objet SoftLayer_Hardware, en plus d'un tableau "networkComponents" qui contient les composants SoftLayer_Network_Components associés à ce matériel.

Il est possible de créer une chaîne de plusieurs propriétés afin d'explorer et de recevoir les propriétés relationnelles de propriétés relationnelles. Par exemple, si nous souhaitons recevoir la liste de composants réseau associés à un périphérique matériel précis, ainsi que la liste des réseaux locaux virtuels (VLAN) de ces composants et même le sous-réseau principal de chacun de ces VLAN, nous pouvons utiliser un masque d'objet :

mask.networkComponents.networkVlans.primarySubnet

Plusieurs propriétés peuvent être définies à l'aide d'une liste délimitée par des virgules dans le masque d'objet.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Ensemble de propriétés

Les ensembles de propriétés sont une autre solution possible qui évitent de lister chaque propriété à partir de son nœud racine. Un ensemble de propriétés permet de déclarer une liste de propriétés à obtenir à partir d'un objet. Il est pratique pour réduire la prolixité d'un masque d'objet.

Un ensemble de propriétés est une liste de propriétés séparée par des virgules et placée entre crochets [ ], suivant un nom de propriété.

Les masques suivants peuvent être considérés comme équivalents :

[mask.id,mask.fullyQualifiedDomainName,mask.networkComponents.networkHardware,mask.networkComponents.uplinkComponent]
mask 
[
    id,fullyQualifiedDomainName,networkComponents [
        networkHardware,uplinkComponent
    ]
]

Réduction du contenu

Lorsque des propriétés locales sont définies dans un masque, l'API renvoie uniquement les propriétés locales de l'objet qui ont été spécifiées. Cette fonction permet de réduire la taille des données renvoyées par l'API et évite des complications supplémentaires ou la pagination.

Par exemple, lors de l'appel de SoftLayer_Hardware::getObject, vous pouvez utiliser le masque suivant pour récupérer uniquement les propriétés id, fullyQualifiedDomainName et primaryIpAddress de l'enregistrement SoftLayer_Hardware. En outre, ce masque renvoie uniquement la propriété longName de datacenter, et les propriétés id, name et port de chaque networkComponent.

mask[id,fullyQualifiedDomainName,primaryIpAddress,datacenter.longName,networkComponents[id,name,port]]

Type

Par défaut, le type des objets renvoyés est déduit et n'est pas requis. Toutefois, il est possible de déclarer un type pour une propriété particulière.

Pour définir un type, vous devez le placer entre parenthèses à la suite du nom de la propriété. Vous devez définir un type lorsque le type de la propriété par défaut ne comporte pas une propriété particulière dont vous ayez besoin.

Par exemple, la propriété controlPanel n'est pas définie dans SoftLayer_Hardware. Vous allez donc recevoir un message d’erreur si vous la demandez via mask.controlPanel dans un appel à SoftLayer_Account::getHardware. Pour demander la valeur, vous devez déclarer un type particulier pour la propriété root property. Voici un exemple :

mask(SoftLayer_Hardware_Server).controlPanel

Si nécessaire, une propriété peut être définie plusieurs fois au même niveau mais avec des types différents.

Le masque ci-dessous est un exemple qui appelle SoftLayer_Search::search et spécifie le renvoi de deux types de données attendus :

mask
[
    resource(SoftLayer_Hardware)
    [
        id,
        fullyQualifiedDomainName,
        datacenter.longName,
        networkComponents.primaryIpAddress
    ],
    resource(SoftLayer_Virtual_Guest)
    [
        id,
        fullyQualifiedDomainName,
        datacenter.longName,
        networkComponents.primaryIpAddress
    ]
]

Syntaxe

NOT FOUND: syntax.png

Interaction avec l'API

SOAP

Pour envoyer le masque d'objet à l'API SOAP, vous devez fournir un en-tête SoftLayer_ObjectMask avec le masque d'objet chaîne de la valeur dans la propriété mask de l'en-tête.

XML-RPC

Le même en-tête SoftLayer_ObjectMask peut être fourni dans la section des en-têtes XML-RPC de la demande.

REST

L'interface REST accepte le masque d'objet via le paramètre GET de objectMask.

Les liaisons SLAPI de nos projets github ont été mises à jour et prennent désormais en charge cette nouvelle forme de masque d'objet chaîne.

Anciens masques d'objet

Consultez l'article Legacy-Object-Masks pour connaître la syntaxe des anciens masques d'objet.