Objektmasken

Übersicht

Um relationale Daten von einem Objekt in der API anzufordern, müssen Sie eine Objektmaske in Ihrem API-Aufruf deklarieren. Bei den Standardobjektmasken werden die relationalen Daten über einen SOAP-Header, ein XML-RPC-Struct oder einen GET-Parameter in REST extrahiert. Erweiterte Objektmasken verwenden eine domänenspezifische Sprache, um den erforderlichen Aufwand im Zusammenhang mit der Angabe, welche Daten von der API zurückgegeben werden sollen, gering zu halten. Zur Unterstützung dieser neuen Methode mit der Objektmaske wurde eine neue Eingabemethode in alle Protokolle aufgenommen.

Struktur

Rootknoten

Erweiterte Objektmasken gehen von einem "Rootknoten", also einer Eigenschaftengruppe oder Zeichenfolge der Maske "mask" aus, die als Alias für das Objekt fungiert, das vom API-Aufruf zurückgegeben wird. Wenn beispielsweise SoftLayer_Hardware::getObject aufgerufen wird, steht der Rootknoten "mask" für ein SoftLayer_Hardware-Objekt.

Wenn wir "mask" als unsere Objektmaske für SoftLayer_Hardware::getObject senden, dann wird das gesamte SoftLayer_Hardware-Objekt genau so zurückgegeben, als wäre gar keine Maske einbezogen worden.

Eigenschaft

Eine Eigenschaft kann der Name einer lokalen oder relationalen Eigenschaft des zurückgegebenen Objekttyps sein. Sie wird mit einem Punkt "." an die Maske angehängt.

mask.networkComponents

Die obige Objektmaske, die beim Aufruf von SoftLayer_Hardware::getObject verwendet wurde, gibt außer dem SoftLayer_Hardware-Objekt auch ein Array "networkComponents" zurück, das die SoftLayer_Network_Components (SoftLayer-Netzwerkkomponenten) enthält, die zu dieser Hardware gehören.

Sie können mehrere Eigenschaften miteinander verketten, um sie detaillierter anzuzeigen und so sogar die relationalen Eigenschaften von relationalen Eigenschaften abrufen. Wenn wir beispielsweise eine Liste der Netzkomponenten im Zusammenhang mit einer bestimmten Hardwareeinheit, eine Liste der VLANs für diese Netzwerkkomponenten und sogar das primäre Teilnetz für jedes dieser VLANs erhalten möchten, können wir eine Objektmaske verwenden.

mask.networkComponents.networkVlans.primarySubnet

Mehrere Eigenschaften können definiert werden, indem wir sie in der Objektmaske durch ein Komma getrennt auflisten.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Eigenschaftengruppe

Eigenschaftengruppen können alternativ verwendet werden, damit nicht jede einzelne Eigenschaft von ihrem Rootknoten ausgehend aufgelistet werden muss. Mit einer Eigenschaftengruppe können Sie eine Liste der Eigenschaften deklarieren, die von einem Objekt angefordert werden. Sie ist hilfreich, da sie die Ausführlichkeit einer Objektmaske verringert.

Eine Eigenschaftengruppe ist eine durch Kommas getrennte Liste der Eigenschaften, die in eckige Klammern [ ] eingeschlossen ist und hinter einem Eigenschaftsnamen steht.

Folgende Masken können als gleichwertig angesehen werden:

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

Nutzdatenreduzierung

Alle lokalen Eigenschaften, die in einer Maske definiert sind, führen zur API, die nur die angegebenen lokalen Eigenschaften des Objekts zurückgibt. Mit dieser Funktion kann die von der API zurückgegebenen Datenmenge verringert werden. Außerdem können damit notwendige Seitenumbrüche und weitere Komplikationen vermieden werden.

Wenn Sie beispielsweise SoftLayer_Hardware::getObject aufrufen, können Sie folgende Maske verwenden, um nur id, fullyQualifiedDomainName und primaryIpAddress vom Datensatz SoftLayer_Hardware abzurufen. Außerdem werden nur longName von datacenter und id, name sowieport von jedernetworkComponent zurückgegeben.

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

Typ

Der Typ der zurückgegebenen Objekte wird standardmäßig abgeleitet und ist nicht erforderlich. Sie können jedoch einen Typ für eine bestimmte Eigenschaft deklarieren.

Ein Typ wird definiert, indem Sie eine runde Klammer hinter den Eigenschaftsnamen setzen, worin der Typname eingeschlossen ist. Ein Typ muss definiert werden, wenn der Standardeigenschaftstyp keine besondere Eigenschaft hat, die Sie benötigen.

Beispiel: Die Eigenschaft controlPanel ist in SoftLayer_Hardware nicht definiert. Folglich erhalten Sie eine Fehlermeldung, wenn Sie diese über mask.controlPanel in einem SoftLayer_Account::getHardware-Aufruf anfordern. Wenn Sie den Wert anfordern möchten, müssen Sie einen bestimmten Typ für root property deklarieren. Nachfolgend sehen Sie ein Beispiel:

mask(SoftLayer_Hardware_Server).controlPanel

Falls erforderlich, kann eine Eigenschaft mehrfach auf derselben Ebene mit verschiedenen Typen definiert werden.

Die Maske unten ist ein Beispiel für das Aufrufen der Suche SoftLayer_Search::search, bei der zwei Datentypen zurückgegeben werden sollen:

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

Syntax

NOT FOUND: syntax.png

API-Interaktion

SOAP

Wenn Sie die Objektmaske an die SOAP-API senden möchten, müssen Sie einen Header SoftLayer_ObjectMask mit der Zeichenfolgeobjektmaske für den Wert in der Eigenschaft mask des Headers angeben.

XML-RPC

Der gleiche SoftLayer_ObjectMask-Header kann im XML-RPC-Headerabschnitt der Anforderung angegeben werden.

REST

Die REST-Schnittstelle akzeptiert die Objektmaske über den objectMask GET-Parameter.

Die SLAPI-Bindungen in unseren github-Projekten wurden aktualisiert und unterstützen nun diese neue Form der Zeichenfolgeobjektmaske.

Traditionelle Objektmasken

Weitere Informationen zur Verwendung der Syntax von traditionellen Objektmasken finden Sie unter Traditionelle Objektmasken.