物件遮罩

概觀

為了從 API 的物件取得關聯式資料,您必須在 API 呼叫中宣告物件遮罩。
有了標準物件遮罩,就可以在 REST 中利用 SOAP 標頭、XML-RPC struct 或 GET 參數,拉出關聯式資料。
延伸物件遮罩利用網域專用語言,減少表示應從 API 傳回哪些資料所需的工作。
為了支援物件遮罩的這個新方法,已在每個通訊協定中新增了輸入方法。

結構

根節點

延伸物件遮罩會從「根節點」啟動,「根節點」是一個內容集或字串 "mask",作為 API 呼叫所傳回物件的別名使用。
例如,呼叫 SoftLayer_Hardware::getObject 時,根節點 "mask" 將代表 SoftLayer_Hardware 物件

所以如果傳送 "mask" 作為 SoftLayer_Hardware::getObject 的物件遮罩,還是會傳回整個 SoftLayer_Hardware 物件,就好像不含任何遮罩一樣。

內容

內容可以是所傳回物件類型的任何區域或關聯式內容的名稱,而且要在遮罩中增添句點:"."。

mask.networkComponents

呼叫 SoftLayer_Hardware::getObject 時使用的上述物件遮罩將傳回 SoftLayer_Hardware 物件,另外還有陣列 "networkComponents",其中含有與該硬體相關聯的 SoftLayer_Network_Components。

可以將多個內容鏈結在一起,以便往下探查,甚至是接收關聯式內容的關聯式內容。
例如,如果我們要接收與特定硬體裝置相關的網路元件清單、與那些網路元件相關的虛擬區域網路清單,甚至是每個虛擬區域網路的主要子網域,我們可以使用物件遮罩:

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 時,可以使用下列遮罩,從 SoftLayer_Hardware 記錄中僅擷取 idfullyQualifiedDomainNameprimaryIpAddress
此外,它只會從 datacenter 傳回 longName,以及傳回每個 networkComponentidnameport

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

如果必要,可以在同一層次上以不同類型定義內容多次。

下面的遮罩範例示範以預期要傳回的兩個資料類型呼叫 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 連結,已更新為支援字串物件遮罩的這個新格式。

舊式物件遮罩

請參閱舊式物件遮罩,以取得舊式物件遮罩語法的相關使用資訊