DocumentaciónExperience PlatformGuía del modelo de datos (XDM) de Experience

Extremo de descriptores

Last update: Mon Feb 12 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Developer

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 mediante descriptores.

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

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

El /descriptors punto final en la Schema Registry La API permite administrar descriptores mediante programación dentro de la aplicación de experiencia.

Introducción

El extremo utilizado en esta guía forma parte de la variable Schema Registry API. Antes de continuar, consulte la guía de introducción para obtener 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 correctamente llamadas a cualquier API de Experience Platform.

Recuperación de una lista de descriptores list

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 el extremo utiliza Accept encabezados que son diferentes de todos los demás extremos de la Schema Registry API.

IMPORTANT
Los descriptores requieren funciones únicas Accept encabezados que reemplazan a xed con xdm, y también ofrecen un link que es única para los descriptores. La adecuada Accept Los encabezados de se han incluido en las llamadas de ejemplo siguientes, pero tenga especial precaución para asegurarse de que se utilizan los encabezados correctos cuando trabaje con descriptores.
Accept encabezado
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 se debe utilizar el encabezado para utilizar las funcionalidades de paginación.

Respuesta

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

Al usar el link Accept encabezado, cada descriptor se muestra como un elemento de matriz con 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"
  ]
}

Búsqueda de un descriptor lookup

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}
El @id del descriptor que desea buscar.

Solicitud

La siguiente solicitud recupera un descriptor mediante su @id valor. Los descriptores no tienen versiones, por lo que no Accept se requiere el encabezado en la solicitud de búsqueda.

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 devuelto @id debe coincidir con el descriptor @id indicada 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"
}

Creación de un descriptor create

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

IMPORTANT
El 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 los 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" en un esquema de ejemplo. Esto indica 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. El @id es un campo de solo lectura asignado por el Schema Registry y se utiliza 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"
}

Actualización de un descriptor put

Puede actualizar un descriptor incluyendo su @id en la ruta de una petición de PUT.

Formato de API

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

Solicitud

Básicamente, esta solicitud 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 solicitud para actualizar (PUT) un descriptor es la misma que la carga útil para crear (POST) un descriptor del mismo tipo.

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

En el siguiente ejemplo, se actualiza un descriptor de identidad para que haga referencia a un elemento diferente xdm:sourceProperty (mobile phone) y cambie la xdm:namespace hasta 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 el @id enviado en la solicitud).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

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

Eliminación de un descriptor delete

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

Formato de API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}
Parámetro
Descripción
{DESCRIPTOR_ID}
El @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 búsqueda frente al descriptor @id. La respuesta devuelve el estado HTTP 404 (no encontrado) porque el descriptor se ha eliminado del Schema Registry.

Apéndice

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

Definición de descriptores defining-descriptors

En las secciones siguientes se ofrece una descripción general de los tipos de descriptor disponibles, incluidos los campos obligatorios para definir un descriptor de cada tipo.

IMPORTANT
No puede etiquetar el objeto de área de nombres de inquilino, ya que el sistema aplicaría esa etiqueta a cada campo personalizado en esa zona protegida. En su lugar, debe especificar el nodo de hoja debajo de ese objeto que debe etiquetar.

Descriptor de identidad

Un descriptor de identidad indica que "sourceProperty" de la "sourceSchema" es un Identity tal como lo describe 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
El tipo de descriptor que se define. Para un descriptor de identidad, este valor debe establecerse en xdm:descriptorIdentity.
xdm:sourceSchema
El $id URI del esquema donde se define el descriptor.
xdm:sourceVersion
La versión principal del esquema de origen.
xdm:sourceProperty
La ruta a la propiedad específica que será la identidad. La ruta debe comenzar por "/" y no terminar por uno. No incluya "propiedades" en la ruta (por ejemplo, utilice "/personalEmail/address" en lugar de "/properties/personalEmail/properties/address")
xdm:namespace
El id o code valor del área de nombres de identidad. Se puede encontrar una lista de áreas de nombres con la variable Identity Service API.
xdm:property
Cualquiera xdm:id o xdm:code, según el xdm:namespace se utiliza.
xdm:isPrimary
Un valor booleano opcional. Cuando es true, indica el campo como identidad principal. Los esquemas solo pueden contener una identidad principal.

Descriptor de nombre descriptivo friendly-name

Los descriptores de nombres descriptivos permiten al usuario modificar la variable title, description, y meta:enum valores de los campos de esquema de la biblioteca principal. 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 interfaz de usuario puede usarlas para mostrar un nombre más descriptivo o solo para mostrar los campos que tienen 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"
  },
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out",
    "media.ping": "Media ping"
  }
}
Propiedad
Descripción
@type
El tipo de descriptor que se define. Para un descriptor de nombre descriptivo, este valor debe establecerse en xdm:alternateDisplayInfo.
xdm:sourceSchema
El $id URI del esquema donde se define el descriptor.
xdm:sourceVersion
La versión principal del esquema de origen.
xdm:sourceProperty
La ruta a la propiedad específica cuyos detalles desea modificar. La ruta debe comenzar con una barra (/) y no terminar con uno. No incluir properties 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 Mayúsculas y minúsculas.
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 se puede usar para agregar valores sugeridos para el campo en la interfaz de usuario de segmentación. Es importante tener en cuenta que meta:enum no declara una enumeración ni proporciona 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, debe editar el del campo meta:enum directamente a través de una solicitud del PATCH al recurso principal del campo.
meta:excludeMetaEnum
Si el campo indicado por xdm:sourceProperty es un campo de cadena que tiene valores sugeridos existentes proporcionados en una meta:enum , puede incluir este objeto en un descriptor de nombre descriptivo para excluir algunos o todos estos valores de la segmentación. La clave y el valor de cada entrada deben coincidir con los incluidos en el original meta:enum del campo para que se excluya la entrada.

Descriptor de relación

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 sobre 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
El tipo de descriptor que se define. Para un descriptor de relación, este valor debe establecerse en xdm:descriptorOneToOne.
xdm:sourceSchema
El $id URI del esquema donde se define el descriptor.
xdm:sourceVersion
La versión principal del esquema de origen.
xdm:sourceProperty
Ruta al campo en el esquema de origen donde se define la relación. Debe comenzar por "/" y no terminar con uno. No incluya "propiedades" en la ruta (por ejemplo, "/personalEmail/address" en lugar de "/properties/personalEmail/properties/address").
xdm:destinationSchema
El $id URI del esquema de referencia con el que define una relación este descriptor.
xdm:destinationVersion
La versión principal del esquema de referencia.
xdm:destinationProperty
Ruta opcional a un campo de destino dentro del esquema de referencia. Si se omite esta propiedad, cualquier campo que contenga un descriptor de identidad de referencia coincidente deducirá el campo de destino (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 referencia ya debe tener un campo de identidad principal definido antes de 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
El tipo de descriptor que se define. Para un descriptor de identidad de referencia, este valor debe establecerse en xdm:descriptorReferenceIdentity.
xdm:sourceSchema
El $id URI del esquema donde se define el descriptor.
xdm:sourceVersion
La 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 referencia. Debe comenzar por "/" 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 del área de nombres de identidad de la propiedad de origen.

Descriptor de campo obsoleto

Puede dejar de utilizar un campo dentro de un recurso XDM personalizado añadiendo una etiqueta meta:status atributo establecido en deprecated al campo en cuestión. Sin embargo, si desea dejar obsoletos los campos proporcionados por los recursos XDM estándar en los esquemas, puede asignar un descriptor de campo obsoleto al esquema en cuestión para lograr el mismo efecto. Uso del correcto Accept encabezadoSin embargo, puede ver qué campos estándar están en desuso para un esquema al buscarlo 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
El tipo de descriptor. Para un descriptor de obsolescencia de campo, este valor debe configurarse como xdm:descriptorDeprecated.
xdm:sourceSchema
El URI $id del esquema al que está aplicando el descriptor.
xdm:sourceVersion
La 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"]).
recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07