オブジェクト・マスク

概要

API でオブジェクトからリレーショナル・データを取得するには、API 呼び出しでオブジェクト・マスクを宣言する必要があります。標準のオブジェクト・マスクでは、リレーショナル・データは、REST で SOAP ヘッダー、XML-RPC 構造、GET パラメーターを使用してプルされます。拡張オブジェクト・マスクは、ドメイン固有の言語を使用して、API から返される必要があるデータを表現するために必要な処理を減らします。オブジェクト・マスクのこの新しいメソッドをサポートするために、新しい入力メソッドが各プロトコルに追加されました。

構造

ルート・ノード

拡張オブジェクト・マスクは、API 呼び出しによって返されるオブジェクトの別名として機能するプロパティー・セットまたは「マスク」のストリングである「ルート・ノード」から始まります。例えば、SoftLayer_Hardware::getObject を呼び出すと、ルート・ノードの「マスク」は SoftLayer_Hardware Object を表します。

そのため、「mask」を SoftLayer_Hardware::getObject のオブジェクト・マスクとして送信すると、マスクが含まれていない場合と同様に、SoftLayer_Hardware オブジェクト全体が返されます。

プロパティー

プロパティーは、返されるオブジェクト・タイプのローカル・プロパティーまたはリレーショナル・プロパティーの名前として指定でき、ピリオド「.」を付けてマスクに追加されます。

mask.networkComponents

SoftLayer_Hardware::getObject を呼び出すときに上記のオブジェクト・マスクを使用すると、SoftLayer_Hardware オブジェクトのほか、そのハードウェアに関連付けられた SoftLayer_Network_Components が入った配列「networkComponents」が返されます。

リレーショナル・プロパティーをドリルダウンして、さらなるリレーショナル・プロパティーを受け取るために、複数のプロパティーをチェーニングすることが可能です。例えば、特定のハードウェア・デバイスに関連したネットワーク・コンポーネントのリスト、それらのネットワーク・コンポーネントに関連した VLAN のリスト、さらにはそれらの各 VLAN の 1 次サブネットのリストを受け取りたい場合は、次のオブジェクト・マスクを使用できます。

mask.networkComponents.networkVlans.primarySubnet

複数のプロパティーは、オブジェクト・マスクの中でコンマで区切ってリストすることにより、定義できます。

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

プロパティー・セット

プロパティー・セットは、ルート・ノードから各プロパティーをリストするのに代わる手段として使用できます。プロパティー・セットは、オブジェクトから取得するプロパティーのリストを宣言するために使用され、オブジェクト・マスクの詳細度を減らす上で役立ちます。

プロパティー・セットは、プロパティー名の後の大括弧 [ ] で囲まれたプロパティーのコンマ区切りリストです。

以下のマスクは同等とみなされます。

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

ペイロード削減

マスクでローカル・プロパティーを定義すると、API は、オブジェクトの指定されたローカル・プロパティーのみを返します。この機能により、API が返すデータ・サイズを削減でき、ページ編集の必要性や複雑化を回避できます。

例えば、SoftLayer_Hardware::getObject を呼び出すときに、以下のマスクを使用して、id, fullyQualifiedDomainName, と primaryIpAddress のみを SoftLayer_Hardware レコードから取得することができます。また、longNameのみを datacenterから返し、各 networkComponentidname、および port を返します。

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

タイプ

デフォルトでは、返されるオブジェクトのタイプは推定されるため、必須ではありません。ただし、特定のプロパティーのタイプを宣言することができます。

タイプは、プロパティー名の後でタイプ名を括弧で囲むことによって定義されます。デフォルトのプロパティー・タイプに必要な特定のプロパティーがない場合に、タイプを定義する必要があります。

例えば、controlPanel プロパティーは SoftLayer_Hardware で定義されていません。そのため、SoftLayer_Account::getHardware への呼び出し時に mask.controlPanel を使用して要求すると、エラーが発生します。この値を要求するには、root property を特定のタイプとして宣言する必要があります。以下に例があります。

mask(SoftLayer_Hardware_Server).controlPanel

必要な場合、あるプロパティーを、異なるタイプを指定して同じレベルで複数回定義できます。

下記のマスクは、2 つのタイプのデータが返されることを予期して SoftLayer_Search::search を呼び出す例を示しています。

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

構文

NOT FOUND: syntax.png

API 対話

SOAP

オブジェクト・マスクを SOAP API に送信するには、SoftLayer_ObjectMask ヘッダーと、ヘッダーの mask プロパティーの値のストリング・オブジェクト・マスクを指定する必要があります。

XML-RPC

要求の XML-RPC ヘッダーに同じ SoftLayer_ObjectMask ヘッダーを指定できます。

REST

REST インターフェースは、objectMask GET パラメーターを介してオブジェクト・マスクを受け入れます。

github プロジェクトにおける SLAPI バインディングは、この新しい形式のストリング・オブジェクト・マスクをサポートするように更新されています。

レガシー・オブジェクト・マスク

レガシー・オブジェクト・マスク構文の使用法については、Legacy-Object-Masks を参照してください。