对象掩码

概述

为了从 API 中的对象获取关系数据,必须在 API 调用中声明一个对象掩码。利用标准对象掩码,可以使用 SOAP 头、XML-RPC 结构或 REST 中的 GET 参数来抽取关系数据。扩展对象掩码会使用域特有的语言来简化表达 API 应返回数据的过程。为了支持这种新的对象掩码方法,已经为每个协议添加了新的输入方法。

结构

根节点

扩展对象掩码的起点是一个“根节点”,而根节点是属性集或字符串“mask”,用作 API 调用所返回对象的别名。例如,当调用 SoftLayer_Hardware::getObject 时,根节点“mask”将表示 SoftLayer_Hardware 对象

因此,如果我们要发送“mask”作为 SoftLayer_Hardware::getObject 的对象掩码,那么会返回整个 SoftLayer_Hardware 对象,如同未包含掩码一样。

属性

属性可以是所返回对象类型的任何本地属性或关系属性的名称,并通过句点附加到掩码:“.”。

mask.networkComponents

在调用 SoftLayer_Hardware::getObject 时使用的上述对象掩码将返回 SoftLayer_Hardware 对象,此外还将返回包含与该硬件关联的 SoftLayer_Network_Components 的数组“networkComponents”。

可以将多个属性链接在一起,以便向下钻取并甚至收到关系属性的关系属性。例如,如果要接收与特定硬件设备相关的网络组件列表、与这些网络组件相关的 VLAN 列表,甚至是其中每个 VLAN 的主子网,那么可以使用对象掩码:

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]]

类型

默认情况下,将会推断所返回对象的类型,所以类型不是必需的。但是,可以声明特定属性的类型。

通过在属性名称后面放置一对括号来将类型名称括起来,可以定义类型。当默认属性类型没有所需的特定属性时,将需要定义类型。

例如,在 SoftLayer_Hardware 上未定义 controlPanel 属性,因此,如果在调用 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 绑定已更新为支持这种新形式的字符串对象掩码。

旧对象掩码

请参阅旧对象掩码,以获取有关旧对象掩码语法的用法信息。