Máscaras de objeto

Visión general

Para obtener datos relacionales de un objeto en la API, tiene que declarar una máscara de objeto en la llamada de API. Con las máscaras de objeto estándar, los datos relacionales se extraen utilizando una cabecera SOAP, una estructura XML-RPC o un parámetro GET en REST. Las máscaras de objeto ampliadas utilizan un lenguaje específico del dominio que pretende reducir el trabajo necesario para expresar los datos que se deben devolver desde la API. Se ha añadido a cada protocolo un nuevo método de entrada que garantiza la compatibilidad con este nuevo método de máscara de objeto.

Estructura

Nodo raíz

Las máscaras de objetos ampliadas empiezan a partir de un "nodo raíz", que es un conjunto de propiedades o una serie de "máscara" que actúa como un alias para el objeto devuelto por la llamada de API. Por ejemplo, cuando se invoca SoftLayer_Hardware::getObject, la "máscara" del nodo raíz representará un objeto SoftLayer_Hardware.

Por lo tanto, si desea enviar "mask" como la máscara de objeto para SoftLayer_Hardware::getObject, se devolverá el objeto SoftLayer_Hardware completo como si no se hubiera incluido ninguna máscara.

Propiedad

Una propiedad puede ser el nombre de cualquier propiedad local o relacional del tipo de objeto devuelto, que se añade a la máscara con un punto: ".".

mask.networkComponents

La máscara de objeto anterior, que se utiliza cuando se invoca SoftLayer_Hardware::getObject, devolverá el objeto SoftLayer_Hardware, además de una matriz "networkComponents" que contiene los SoftLayer_Network_Components asociados con ese hardware.

Es posible encadenar varias propiedades para descender a un mayor nivel de detalle y recibir incluso propiedades relacionales de propiedades relacionales. Por ejemplo, si desea recibir una lista de componentes de red relacionados con un determinado dispositivo de hardware, por ejemplo, una lista de las VLAN relacionadas con esos componentes de red e incluso la subred primaria de cada una de esas VLAN, puede utilizar una máscara de objeto:

mask.networkComponents.networkVlans.primarySubnet

Para definir varias propiedades, lístelas en la máscara de objeto separadas por una coma.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Conjunto de propiedades

Los conjuntos de propiedades pueden utilizarse como una alternativa a listar cada propiedad desde su nodo raíz. Un conjunto de propiedades se utiliza para declarar una lista de propiedades que se obtienen desde un objeto y es muy útil para reducir el nivel de detalle de una máscara de objeto.

Un conjunto de propiedades es una lista separada por comas de propiedades entre corchetes [ ] que aparece después de un nombre de propiedad.

Las siguientes máscaras pueden considerarse equivalentes:

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

Reducción de la carga útil

Las propiedades locales definidas en una máscara harán que la API devuelva sólo las propiedades locales especificadas del objeto. Esta característica permite reducir el tamaño de los datos de devolución de API y evitar la necesidad de paginación o complicaciones adicionales.

Por ejemplo, cuando se invoca SoftLayer_Hardware::getObject, puede utilizarse la siguiente máscara para recuperar sólo id, fullyQualifiedDomainName y primaryIpAddress del registro de SoftLayer_Hardware. Asimismo, devolverá sólo el longName del datacenter, y los valores id, name y port de cada networkComponent.

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

Tipo

De forma predeterminada, el tipo de los objetos devueltos se deduce y no es necesario. No obstante, puede declarar un tipo para una propiedad específica.

Un tipo se define añadiendo el nombre de tipo entre paréntesis después del nombre de propiedad. Debe definir un tipo cuando el tipo de propiedad predeterminado no tenga la propiedad específica que necesita.

Por ejemplo, la propiedad controlPanel no está definida en SoftLayer_Hardware y, como tal, obtendrá un error si la solicita en mask.controlPanel en una llamada a SoftLayer_Account::getHardware. Para solicitar el valor, debe declarar root property para que sea de un determinado tipo. A continuación se muestra un ejemplo.

mask(SoftLayer_Hardware_Server).controlPanel

Si es necesario, una propiedad puede definirse varias veces en el mismo nivel con tipos diferentes.

La máscara es un ejemplo de invocación de SoftLayer_Search::search con la devolución de dos tipos de datos esperados:

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

Sintaxis

NOT FOUND: syntax.png

Interacción de la API

SOAP

Para enviar la máscara de objeto a la API SOAP, deberá proporcionar una cabecera SoftLayer_ObjectMask con la máscara de objeto de serie para el valor en la propiedad mask de la cabecera.

XML-RPC

La misma cabecera SoftLayer_ObjectMask puede proporcionarse en la sección de cabeceras XML-RPC de la solicitud.

REST

La interfaz REST aceptará la máscara de objeto mediante el parámetro GET de objectMask.

Nuestros enlaces de SLAPI encontrados en los proyectos de github se han actualizado para dar soporte a este nuevo formato de máscara de objeto de serie.

Máscaras de objeto existentes

Consulte Legacy-Object-Masks para obtener información de uso sobre la sintaxis de las máscaras de objetos existentes.