Punto final del descriptor

Los esquemas definen una vista estática de las entidades de datos, pero no proporcionan detalles específicos sobre cómo los datos basados en estos esquemas (conjuntos de datos, por ejemplo) pueden relacionarse entre sí. Adobe Experience Platform permite describir estas relaciones y otros metadatos interpretativos sobre un esquema con descriptores.

Los descriptores de esquema son metadatos de nivel de inquilino, lo que significa que son únicos para su organización de IMS y todas las operaciones de descriptor se realizan en el contenedor de inquilino.

Cada esquema puede tener una o más entidades descriptor de esquema aplicadas a él. Cada entidad descriptor de esquema incluye un descriptor @type y sourceSchema a los que se aplica. Una vez aplicados, estos descriptores se aplican a todos los conjuntos de datos creados con el esquema .

La variable /descriptors en la variable Schema Registry La API de le permite administrar mediante programación los descriptores dentro de la aplicación de experiencia.

Primeros pasos

El extremo utilizado en esta guía forma parte de la Schema Registry API de . Antes de continuar, revise la guía de introducción para ver vínculos a documentación relacionada, una guía para leer las llamadas de API de ejemplo en este documento e información importante sobre los encabezados necesarios para realizar llamadas correctamente a cualquier API de Experience Platform.

Recuperar una lista de descriptores

Puede enumerar todos los descriptores definidos por su organización realizando una solicitud de GET a /tenant/descriptors.

Formato de API

GET /tenant/descriptors

Solicitud

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xdm-link+json'

El formato de respuesta depende de la variable Accept encabezado enviado en la solicitud. Observe que la variable /descriptors usos de extremo Accept encabezados que son diferentes a todos los demás extremos de la variable Schema Registry API.

IMPORTANTE

Los descriptores requieren Accept encabezados que reemplazan xed con xdmy también ofrecen un link que es única para los descriptores. El Accept los encabezados se han incluido en las llamadas de ejemplos siguientes, pero tenga cuidado de que se usen los encabezados correctos al trabajar con descriptores.

Accept header Descripción
application/vnd.adobe.xdm-id+json Devuelve una matriz de ID de descriptor
application/vnd.adobe.xdm-link+json Devuelve una matriz de rutas de API de descriptor
application/vnd.adobe.xdm+json Devuelve una matriz de objetos descriptor expandidos
application/vnd.adobe.xdm-v2+json Esta Accept para utilizar las capacidades de paginación, debe usarse .

Respuesta

La respuesta incluye una matriz para cada tipo de descriptor que tiene descriptores definidos. En otras palabras, si no hay descriptores de un @type definido, el registro no devolverá una matriz vacía para ese tipo de descriptor.

Al usar la variable link Accept , cada descriptor se muestra como un elemento de matriz en el formato /{CONTAINER}/descriptors/{DESCRIPTOR_ID}

{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

Buscar un descriptor

Si desea ver los detalles de un descriptor específico, puede buscar (GET) un descriptor individual utilizando su @id.

Formato de API

GET /tenant/descriptors/{DESCRIPTOR_ID}
Parámetro Descripción
{DESCRIPTOR_ID} La variable @id del descriptor que desea buscar.

Solicitud

La siguiente solicitud recupera un descriptor mediante su @id valor. Los descriptores no tienen versiones, por lo tanto no Accept en la solicitud de consulta.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve los detalles del descriptor, incluido su @type y sourceSchema, así como información adicional que varía según el tipo de descriptor. El @id debe coincidir con el descriptor @id en la solicitud.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{ORG_ID}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Crear un descriptor

Puede crear un nuevo descriptor realizando una solicitud de POST al /tenant/descriptors punto final.

IMPORTANTE

La variable Schema Registry permite definir varios tipos de descriptor diferentes. Cada tipo de descriptor requiere que se envíen sus propios campos específicos en el cuerpo de la solicitud. Consulte la apéndice para obtener una lista completa de descriptores y los campos necesarios para definirlos.

Formato de API

POST /tenant/descriptors

Solicitud

La siguiente solicitud define un descriptor de identidad en un campo "dirección de correo electrónico" de un esquema de ejemplo. Esto indica que Experience Platform para utilizar la dirección de correo electrónico como identificador para ayudar a unir información sobre el individuo.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 (Creado) y los detalles del descriptor recién creado, incluido su @id. La variable @id es un campo de solo lectura asignado por la variable Schema Registry y se usan para hacer referencia al descriptor en la API.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Actualizar un descriptor

Puede actualizar un descriptor incluyendo su @id en la ruta de una solicitud del PUT.

Formato de API

PUT /tenant/descriptors/{DESCRIPTOR_ID}
Parámetro Descripción
{DESCRIPTOR_ID} La variable @id del descriptor que desea actualizar.

Solicitud

Esta solicitud básicamente reescribe el descriptor, por lo que el cuerpo de la solicitud debe incluir todos los campos necesarios para definir un descriptor de ese tipo. En otras palabras, la carga útil de la solicitud para actualizar (PUT) un descriptor es la misma que la carga útil para crear (POST) un descriptor del mismo tipo.

IMPORTANTE

Al igual que con la creación de descriptores mediante solicitudes de POST, cada tipo de descriptor requiere que sus propios campos específicos se envíen en cargas de solicitud de PUT. Consulte la apéndice para obtener una lista completa de descriptores y los campos necesarios para definirlos.

El siguiente ejemplo actualiza un descriptor de identidad para que haga referencia a otro xdm:sourceProperty (mobile phone) y cambie la variable xdm:namespace a Phone.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 (Creado) y la variable @id del descriptor actualizado (que debe coincidir con la variable @id enviado en la solicitud).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Realización de una solicitud de búsqueda (GET) para ver el descriptor, se mostrará que los campos se han actualizado para reflejar los cambios enviados en la solicitud del PUT.

Eliminar un descriptor

En ocasiones, es posible que tenga que eliminar un descriptor que haya definido de la variable Schema Registry. Esto se hace haciendo una solicitud de DELETE que hace referencia al @id del descriptor que desea eliminar.

Formato de API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}
Parámetro Descripción
{DESCRIPTOR_ID} La variable @id del descriptor que desea eliminar.

Solicitud

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve el estado HTTP 204 (sin contenido) y un cuerpo en blanco.

Para confirmar que el descriptor se ha eliminado, puede realizar una solicitud de consulta frente al descriptor @id. La respuesta devuelve el estado HTTP 404 (no encontrado) porque el descriptor se ha eliminado del Schema Registry.

Apéndice

La siguiente sección proporciona información adicional sobre cómo trabajar con descriptores en la Schema Registry API.

Definición de descriptores

Las siguientes secciones proporcionan información general sobre los tipos de descriptor disponibles, incluidos los campos obligatorios para definir un descriptor de cada tipo.

Descriptor de identidad

Un descriptor de identidad indica que la variablesourceProperty" de la "sourceSchema" es un Identity tal como se describe en Servicio de identidad de Adobe Experience Platform.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}
Propiedad Descripción
@type Tipo de descriptor que se está definiendo. Para un descriptor de identidad, este valor debe establecerse en xdm:descriptorIdentity.
xdm:sourceSchema La variable $id URI del esquema en el que se está definiendo el descriptor.
xdm:sourceVersion Versión principal del esquema de origen.
xdm:sourceProperty La ruta a la propiedad específica que será la identidad. La ruta debe comenzar con "/" y no terminar con una. No incluya "propiedades" en la ruta (por ejemplo, use "/personalEmail/address" en lugar de "/properties/personalEmail/properties/address")
xdm:namespace La variable id o code valor del área de nombres de identidad. Se puede encontrar una lista de áreas de nombres utilizando la variable Identity Service API.
xdm:property Cualquiera xdm:id o xdm:code, según la variable xdm:namespace se utiliza.
xdm:isPrimary Un valor booleano opcional. Si es true, indica el campo como identidad principal. Los esquemas solo pueden contener una identidad principal.

Descriptor de nombres descriptivos

Los descriptores de nombres descriptivos permiten al usuario modificar el title, descriptiony meta:enum valores de los campos de esquema de la biblioteca principal. Resulta especialmente útil cuando se trabaja con "eVars" y otros campos "genéricos" que desea etiquetar como que contienen información específica de su organización. La IU puede utilizarlos para mostrar un nombre más descriptivo o solo para mostrar campos con un nombre descriptivo.

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  }
}
Propiedad Descripción
@type Tipo de descriptor que se está definiendo. Para un descriptor de nombre descriptivo, este valor debe establecerse en xdm:alternateDisplayInfo.
xdm:sourceSchema La variable $id URI del esquema en el que se está definiendo el descriptor.
xdm:sourceVersion Versión principal del esquema de origen.
xdm:sourceProperty La ruta a la propiedad específica que será la identidad. La ruta debe comenzar con "/" y no terminar con una. No incluya "propiedades" en la ruta (por ejemplo, use "/personalEmail/address" en lugar de "/properties/personalEmail/properties/address")
xdm:title El nuevo título que desea mostrar para este campo, escrito en el caso Título.
xdm:description Se puede añadir una descripción opcional junto con el título.
meta:enum Si el campo indicado por xdm:sourceProperty es un campo de cadena, meta:enum determina la lista de valores sugeridos para el campo en la variable Experience Platform IU. Es importante señalar que meta:enum no declara una enumeración ni proporciona ninguna validación de datos para el campo XDM.

Esto solo debe utilizarse para campos XDM principales definidos por el Adobe. Si la propiedad de origen es un campo personalizado definido por su organización, en su lugar debe editar el meta:enum directamente a través de una solicitud de PATCH al recurso principal del campo.

Descriptor de relaciones

Los descriptores de relación describen una relación entre dos esquemas diferentes, con claves en las propiedades descritas en sourceProperty y destinationProperty. Consulte el tutorial en definición de una relación entre dos esquemas para obtener más información.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}
Propiedad Descripción
@type Tipo de descriptor que se está definiendo. Para un descriptor de relación, este valor debe establecerse en xdm:descriptorOneToOne.
xdm:sourceSchema La variable $id URI del esquema en el que se está definiendo el descriptor.
xdm:sourceVersion Versión principal del esquema de origen.
xdm:sourceProperty Ruta al campo en el esquema de origen donde se está definiendo la relación. Debe comenzar con "/" y no terminar con uno. No incluya "propiedades" en la ruta (por ejemplo, "/personalEmail/address" en lugar de "/properties/personalEmail/properties/address").
xdm:destinationSchema La variable $id URI del esquema de destino con el que este descriptor define una relación.
xdm:destinationVersion La versión principal del esquema de destino.
xdm:destinationProperty Ruta opcional a un campo de destino dentro del esquema de destino. Si se omite esta propiedad, el campo de destino se deduce por cualquier campo que contenga un descriptor de identidad de referencia coincidente (consulte a continuación).

Descriptor de identidad de referencia

Los descriptores de identidad de referencia proporcionan un contexto de referencia a la identidad principal de un campo de esquema, lo que permite que los campos de otros esquemas hagan referencia a él. El esquema de destino ya debe tener un campo de identidad principal definido para que otros esquemas puedan hacer referencia a él a través de este descriptor.

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}
Propiedad Descripción
@type Tipo de descriptor que se está definiendo. Para un descriptor de identidad de referencia, este valor debe establecerse en xdm:descriptorReferenceIdentity.
xdm:sourceSchema La variable $id URI del esquema en el que se está definiendo el descriptor.
xdm:sourceVersion Versión principal del esquema de origen.
xdm:sourceProperty Ruta al campo en el esquema de origen que se utilizará para hacer referencia al esquema de destino. Debe comenzar con "/" y no terminar con uno. No incluya "propiedades" en la ruta (por ejemplo, /personalEmail/address en lugar de /properties/personalEmail/properties/address).
xdm:identityNamespace El código de área de nombres de identidad para la propiedad de origen.

Descriptor de campo obsoleto

Puede Poner en desuso un campo dentro de un recurso XDM personalizado añadiendo un meta:status establecido en deprecated al campo en cuestión. Sin embargo, si desea eliminar de los esquemas los campos proporcionados por recursos XDM estándar, puede asignar un descriptor de campo obsoleto al esquema en cuestión para lograr el mismo efecto. Al usar la variable correcto Accept header, puede ver qué campos estándar están en desuso para un esquema al buscarlos en la API.

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}
Propiedad Descripción
@type Tipo de descriptor. Para un descriptor de desaprobación de campos, este valor debe establecerse en xdm:descriptorDeprecated.
xdm:sourceSchema El URI $id del esquema al que está aplicando el descriptor.
xdm:sourceVersion Versión del esquema al que está aplicando el descriptor. Debe configurarse como 1.
xdm:sourceProperty Ruta a la propiedad dentro del esquema al que está aplicando el descriptor. Si desea aplicar el descriptor a varias propiedades, puede proporcionar una lista de rutas en forma de matriz (por ejemplo, ["/firstName", "/lastName"]).

En esta página