오브젝트 마스크

개요

API에서 오브젝트의 관계형 데이터를 가져오려면 API 호출에서 오브젝트 마스크를 선언해야 합니다. 표준 오브젝트 마스크를 사용하는 경우, REST에 GET 매개변수, SOAP 헤더 또는 XML-RPC 구조체를 사용하여 관계형 데이터를 가져옵니다. 확장 오브젝트 마스크는 도메인 고유 언어를 사용하여 API에서 리턴되어야 하는 데이터를 표시하는 데 필요한 작업을 간소화합니다. 새로운 오브젝트 마스크 메소드를 지원하기 위해 새로운 입력 메소드가 각 프로토콜에 추가되었습니다.

구조

루트 노드

확장 오브젝트 마스크는 API 호출에서 리턴되는 오브젝트에 대한 별명 역할을 하는 "mask" 문자열 또는 특성 세트인 "루트 노드"에서 시작합니다. 예를 들어, SoftLayer_Hardware::getObject를 호출하는 경우 루트 노드 "mask"는 SoftLayer_Hardware 오브젝트를 나타냅니다.

따라서 SoftLayer_Hardware::getObject의 오브젝트 마스크로 "mask"를 전송한 경우, 전체 SoftLayer_Hardware 오브젝트가 마스크를 포함하지 않은 것처럼 리턴되어야 합니다.

특성

특성은 리턴되는 오브젝트 유형의 로컬 특성 또는 관계형 특성에 대한 이름일 수 있으며 마침표(".")가 붙어 마스크에 추가됩니다.

mask.networkComponents

SoftLayer_Hardware::getObject를 호출할 때 위의 오브젝트 마스크를 사용하면 하드웨어에 연결된 SoftLayer_Network_Components를 포함한 "networkComponents" 어레이 이외에도 SoftLayer_Hardware 오브젝트가 리턴됩니다.

관계형 특성의 상세 정보를 탐색하거나 관계형 특성의 관계형 특성을 확인하기 위해 여러 개의 특성을 하나로 연결할 수 있습니다. 예를 들어, 특정 하드웨어 디바이스와 관련된 네트워크 구성요소 목록, 해당 네트워크 구성요소와 관련된 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 레코드에서 id, fullyQualifiedDomainNameprimaryIpAddress만 가져옵니다. 또한, datacenterlongName, 각 networkComponentid, name, 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

필요한 경우, 동일한 레벨에서 다른 유형을 사용하여 특성을 여러 번 정의할 수 있습니다.

아래 마스크는 두 가지 데이터 유형이 리턴되어야 하는 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로 전송하려면 헤더의 mask 특성 값에 문자열 오브젝트 마스크를 사용하여 SoftLayer_ObjectMask 헤더를 제공해야 합니다.

XML-RPC

동일한 SoftLayer_ObjectMask 헤더가 요청의 XML-RPC 헤더 섹션에 제공될 수 있습니다.

REST

REST 인터페이스는 objectMask GET 매개변수를 통해 오브젝트 마스크를 받아들입니다.

당사 GitHub 프로젝트를 통해 얻은 SLAPI 바인딩이 이러한 새로운 형태의 문자열 오브젝트 마스크를 지원하도록 업데이트되었습니다.

레거시 오브젝트 마스크

레거시 오브젝트 마스크 구문에 대한 사용법 정보는 Legacy-Object-Masks를 참조하십시오.