Maschere oggetto

Panoramica

Per ottenere i dati relazionali da un oggetto nell'API, devi dichiarare una maschera oggetto nella tua chiamata API. Con le maschere oggetto standard, i dati relazionali vengono estratti utilizzando un'intestazione SOAP, una struttura XML-RPC o un parametro GET in REST. Le maschere oggetto estese usano un linguaggio specifico per il dominio per ridurre lo sforzo necessario per esprimere quali dati devono essere restituiti dall'API. Per supportare questo nuovo metodo di maschera oggetto, a ciascun protocollo è stato aggiunto un nuovo metodo di input.

Struttura

Nodo radice

Le maschere oggetto estese iniziano da un "nodo radice" che è una serie di proprietà o una stringa di "maschera" che funge da
alias per l'oggetto restituito dalla chiamata API. Ad esempio, quando si richiama SoftLayer_Hardware::getObject la "maschera" del nodo radice rappresenterà un oggetto SoftLayer_Hardware.

Quindi, se dovessimo inviare "mask" come nostra maschera oggetto per SoftLayer_Hardware::getObject, verrebbe restituito l'intero oggetto SoftLayer_Hardware, come se non fosse inclusa alcuna maschera.

Proprietà

Una proprietà può essere il nome di qualsiasi proprietà locale o relazionale del tipo di oggetto restituito e viene accodata alla maschera con un punto:".".

mask.networkComponents

La maschera oggetto di cui sopra utilizzata quando si richiama SoftLayer_Hardware::getObject restituirà l'oggetto SoftLayer_Hardware, oltre a un array "networkComponents" che contiene i SoftLayer_Network_Component associati a tale hardware.

È possibile concatenare più proprietà per eseguire il drill-down e ricevere anche proprietà relazionali di proprietà relazionali. Ad esempio, se vogliamo ricevere un elenco dei componenti di rete correlati a uno specifico dispositivo hardware, un elenco delle VLAN correlate a questi componenti di rete e anche una sottorete primaria di queste VLAN, possiamo utilizzare una maschera oggetto:

mask.networkComponents.networkVlans.primarySubnet

È possibile definire più proprietà nella maschera oggetto elencandole e separandole con una virgola.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Set di proprietà

I set di proprietà possono essere utilizzati come un'alternativa all'elencazione di ciascuna proprietà dal relativo nodo root. Un set di proprietà viene utilizzato per dichiarare un elenco di proprietà da ottenere da un oggetto ed è utile per ridurre il livello di dettaglio di una maschera oggetto.

Un set di proprietà è un elenco separato da virgole di proprietà, racchiuso tra le parentesi [ ], che segue un nome proprietà.

Le seguenti maschere possono essere considerate equivalenti:

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

Riduzione del payload

Qualsiasi proprietà locale definita in una maschera determinerà la restituzione, da parte dell'API, solo delle proprietà locali specificate dell'oggetto. Questa funzione consente di ridurre la dimensione dei dati restituiti dall'API e può servire a evitare attività di impaginazione o ulteriori complicazioni.

Ad esempio, quando si richiama SoftLayer_Hardware::getObject, è possibile utilizzare la
seguente maschera per richiamare solo id, fullyQualifiedDomainName e primaryIpAddress dal record SoftLayer_Hardware. Inoltre, restituirà solo il longName dal datacenter e id, name e port di ogni networkComponent.

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

Tipo

Per impostazione predefinita, il tipo di oggetti restituito verrà dedotto e non è richiesto. È tuttavia possibile dichiarare un tipo per una specifica proprietà.

Un tipo viene definito posizionando delle parentesi dopo il nome della proprietà che racchiudono il nome del tipo. Un tipo dovrà essere definito quando il tipo proprietà predefinito non ha una specifica proprietà di cui hai bisogno.

Ad esempio, la proprietà controlPanel non è definita
su SoftLayer_Hardware e, pertanto, otterrai un errore se la richiedi tramite mask.controlPanel su una chiamata a SoftLayer_Account::getHardware. Per richiedere il valore, devi dichiarare
la root property perché sia di uno specifico tipo. Ecco un esempio.

mask(SoftLayer_Hardware_Server).controlPanel

Se necessario, è possibile definire una proprietà più volte sullo stesso livello con tipi differenti.

La maschera di seguito è un esempio per richiamare SoftLayer_Search::search con due tipi di dati previsti da restituire:

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

Sintassi

NOT FOUND: syntax.png

Interazione API

SOAP

Per inviare la maschera oggetto all'API SOAP, dovrai fornire un'intestazione SoftLayer_ObjectMask con la maschera oggetto stringa per il valore nella proprietà mask dell'intestazione.

XML-RPC

La stessa intestazione SoftLayer_ObjectMask può essere fornita nella sezione delle intestazioni XML-RPC della richiesta.

REST

L'interfaccia REST accetterà la maschera oggetto tramite il parametro GET di objectMask.

Le nostre associazioni SLAPI presenti nei nostri progetti github sono state aggiornate per supportare questo nuovo formato di maschera oggetto stringa.

Maschere oggetto legacy

Consulta Maschere oggetto legacy per informazioni sull'utilizzo relative alla sintassi della maschera oggetto legacy