Máscaras de objetos

Visão Geral

Para obter dados relacionais de um objeto na API, deve-se declarar uma máscara de objeto em sua chamada API. Com máscaras de objeto padrão, é efetuado pull de dados relacionais usando um cabeçalho SOAP, uma estrutura XML-RPC ou um parâmetro GET em REST. Máscaras de objetos estendidas usam uma Linguagem específica do domínio para reduzir o esforço requerido para expressar quais dados devem ser retornados da API. Para suportar esse novo método da máscara de objeto, um novo método de entrada foi incluído em cada protocolo.

Estrutura

Nó raiz

Máscaras de objetos estendidas iniciam em um "nó raiz", que é um conjunto de propriedades ou uma sequência de "máscara" que age como um alias para o objeto retornado pela chamada API. Por exemplo, ao chamar SoftLayer_Hardware::getObject, o nó raiz "mask" representará um SoftLayer_Hardware Object.

Portanto, se fossemos enviar "mask" como nosso objeto de máscara para SoftLayer_Hardware::getObject, todo o objeto SoftLayer_Hardware seria retornado como se nenhuma máscara estivesse incluída.

Propriedade

Uma propriedade pode ser o nome de qualquer propriedade local ou relacional do tipo de objeto retornado e é anexada à máscara com um ponto: ".".

mask.networkComponents

A máscara de objeto acima usada ao chamar SoftLayer_Hardware::getObject retornará o objeto SoftLayer_Hardware, além de uma matriz "networkComponents" que contém os SoftLayer_Network_Components associados a esse hardware.

É possível encadear diversas propriedades juntas para realizar drill down e receber até mesmo propriedades relacionais de propriedades relacionais. Por exemplo, se quiséssemos receber uma lista de componentes de rede relacionados a um dispositivo de hardware específico, uma lista de VLANs relacionadas a esses componentes de rede e, até mesmo, a sub-rede primária de cada uma dessas VLANs, poderíamos usar uma máscara de objeto:

mask.networkComponents.networkVlans.primarySubnet

Diversas propriedades podem ser definidas na máscara de objeto em uma lista separada por vírgula.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Conjunto de propriedades

Os conjuntos de propriedades podem ser usados como uma alternativa para a listagem de cada propriedade a partir de seu nó raiz. Um conjunto de propriedades é usado para declarar uma lista de propriedades a obter de um objeto e é útil para reduzir o detalhamento de uma máscara de objeto.

Um conjunto de propriedades é uma lista de propriedades separada por vírgula colocada entre colchetes [ ] que segue um nome de propriedade.

As máscaras a seguir podem ser consideradas equivalentes:

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

Redução de carga útil

Quaisquer propriedades locais definidas em uma máscara resultarão na API retornando somente as propriedades locais especificadas do objeto. Esse recurso permite a redução do tamanho dos dados de retorno da API e pode ajudar a evitar a necessidade de paginação ou complicação adicional.

Por exemplo, ao chamar SoftLayer_Hardware::getObject, a máscara a seguir poderá ser usada para recuperar somente id, fullyQualifiedDomainName e primaryIpAddress a partir do registro SoftLayer_Hardware. Além disso, retornará somente longName de datacenter e id, name e port de cada networkComponent.

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

Tipo

Por padrão, o tipo de objetos retornados será inferido e não é obrigatório. No entanto, é possível declarar um tipo para uma propriedade específica.

Um tipo é definido colocando um par de parênteses após o nome da propriedade com o nome do tipo entre parênteses. Um tipo precisará ser definido quando o tipo de propriedade padrão não tiver uma propriedade específica que você precisa.

Por exemplo, a propriedade controlPanel não está definida em SoftLayer_Hardware e, dessa forma, você obterá um erro se solicitá-la via mask.controlPanel em uma chamada para SoftLayer_Account::getHardware. Para solicitar o valor, deve-se declarar a root property como sendo de um tipo específico. Segue abaixo um exemplo.

mask(SoftLayer_Hardware_Server).controlPanel

Se necessário, uma propriedade pode ser definida diversas vezes no mesmo nível com diferentes tipos.

A máscara abaixo é um exemplo para chamar SoftLayer_Search::search, sendo esperado que dois tipos de dados sejam retornados:

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

Sintaxe

NOT FOUND: syntax.png

Interação da API

SOAP

Para enviar a máscara de objeto para a API SOAP, será necessário fornecer um cabeçalho SoftLayer_ObjectMask com a máscara de objeto de sequência para o valor na propriedade mask do cabeçalho.

XML-RPC

O mesmo cabeçalho SoftLayer_ObjectMask pode ser fornecido na seção de cabeçalhos XML-RPC da solicitação.

REST

A interface REST aceitará a máscara de objeto por meio do parâmetro GET de objectMask.

As ligações de nossa SLAPI encontradas em nossos projetos github foram atualizadas para suportar esse novo formato de máscara de objeto de sequência.

Máscaras de objetos anteriores

Consulte Máscaras de objetos anteriores para obter informações de uso sobre a sintaxe de máscara de objeto anterior