Extremo de esquemas

Un esquema se puede considerar como el modelo para los datos que desea ingerir en Adobe Experience Platform. Cada esquema está compuesto por una clase y cero o más mezclas. El extremo /schemas de la API Schema Registry le permite administrar esquemas mediante programación dentro de la aplicación de experiencia.

Primeros pasos

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

Recuperar una lista de esquemas

Puede realizar la lista de todos los esquemas bajo el contenedor global o tenant haciendo una solicitud de GET a /global/schemas o /tenant/schemas, respectivamente.

NOTA

Al enumerar los recursos, el Registro de Esquemas limita los conjuntos de resultados a 300 elementos. Para devolver recursos más allá de este límite, debe utilizar parámetros de paginación. También se recomienda utilizar parámetros de consulta adicionales para filtrar los resultados y reducir el número de recursos devueltos. Consulte la sección sobre parámetros de consulta en el documento del apéndice para obtener más información.

Formato API

GET /{CONTAINER_ID}/schemas?{QUERY_PARAMS}
Parámetro Descripción
{CONTAINER_ID} El contenedor que aloja los esquemas que desea recuperar: global para esquemas creados en Adobe o tenant para esquemas que son propiedad de su organización.
{QUERY_PARAMS} Parámetros de consulta opcionales para filtrar los resultados. Consulte el documento del apéndice para obtener una lista de los parámetros disponibles.

Solicitud

La siguiente solicitud recupera una lista de esquemas del contenedor tenant, mediante un parámetro de consulta orderby para ordenar los resultados por su atributo title.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?orderby=title \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

El formato de respuesta depende del encabezado Accept enviado en la solicitud. Los siguientes Accept encabezados están disponibles para los esquemas de listado:

Accept header Descripción
application/vnd.adobe.xed-id+json Devuelve un breve resumen de cada recurso. Éste es el encabezado recomendado para enumerar los recursos. (Límite: 300)
application/vnd.adobe.xed+json Devuelve el esquema JSON completo para cada recurso, con $ref y allOf originales incluidos. (Límite: 300)

Respuesta

En la solicitud anterior se utilizó el encabezado application/vnd.adobe.xed-id+json Accept, por lo que la respuesta sólo incluye los atributos title, $id, meta:altId y version para cada esquema. El uso del otro encabezado Accept (application/vnd.adobe.xed+json) devuelve todos los atributos de cada esquema. Seleccione el encabezado Accept correspondiente en función de la información que necesite en la respuesta.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0238be93d3e7a06aec5e0655955901ec",
      "meta:altId": "_{TENANT_ID}.schemas.0238be93d3e7a06aec5e0655955901ec",
      "version": "1.4",
      "title": "Hotels"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0ef4ce0d390f0809fad490802f53d30b",
      "meta:altId": "_{TENANT_ID}.schemas.0ef4ce0d390f0809fad490802f53d30b",
      "version": "1.0",
      "title": "Loyalty Members"
    }
  ],
  "_page": {
        "orderby": "title",
        "next": null,
        "count": 2
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

Buscar un esquema

Puede buscar un esquema específico realizando una solicitud de GET que incluya el ID del esquema en la ruta.

Formato API

GET /{CONTAINER_ID}/schemas/{SCHEMA_ID}
Parámetro Descripción
{CONTAINER_ID} El contenedor que aloja el esquema que desea recuperar: global para un esquema creado por Adobe o tenant para un esquema propiedad de su organización.
{SCHEMA_ID} El meta:altId o el $id con codificación URL del esquema que desea buscar.

Solicitud

La siguiente solicitud recupera un esquema especificado por su valor meta:altId en la ruta.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.f579a0b5f992c69458ea408ec36571f7da9de15901bab116 \
  -H 'Accept: application/vnd.adobe.xed+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

El formato de respuesta depende del encabezado Accept enviado en la solicitud. Todas las solicitudes de búsqueda requieren que se incluya version en el encabezado Accept. Los siguientes Accept encabezados están disponibles:

Accept header Descripción
application/vnd.adobe.xed+json; version={MAJOR_VERSION} Sin procesar con $ref y allOf, tiene títulos y descripciones.
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref y allOf resuelto, tiene títulos y descripciones.
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} Sin formato con $ref y allOf, sin títulos ni descripciones.
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref y allOf resuelto, sin títulos ni descripciones.
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $ref y allOf resueltos, se incluyen los descriptores.

Respuesta

Una respuesta correcta devuelve los detalles del esquema. Los campos devueltos dependen del encabezado Accept enviado en la solicitud. Experimente con diferentes Accept encabezados para comparar las respuestas y determinar qué encabezado es el mejor para su caso de uso.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:altId": "_{TENANT_ID}.schemas.20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:resourceType": "schemas",
  "version": "1.1",
  "title": "Example schema",
  "type": "object",
  "description": "An example schema created within the tenant container.",
  "allOf": [
      {
          "$ref": "https://ns.adobe.com/xdm/context/profile",
          "type": "object",
          "meta:xdmType": "object"
      },
      {
          "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
          "type": "object",
          "meta:xdmType": "object"
      }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": false,
  "meta:abstract": false,
  "meta:extends": [
      "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
      "https://ns.adobe.com/xdm/common/auditable",
      "https://ns.adobe.com/xdm/data/record",
      "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
      "repo:createdDate": 1602872911226,
      "repo:lastModifiedDate": 1603381419889,
      "xdm:createdClientId": "{CLIENT_ID}",
      "xdm:lastModifiedClientId": "{CLIENT_ID}",
      "xdm:createdUserId": "{USER_ID}",
      "xdm:lastModifiedUserId": "{USER_ID}",
      "eTag": "84b4da79b7445a4bf1c59269e718065effddb983c492f48e223d49c049c6d589",
      "meta:globalLibVersion": "1.15.4"
  },
  "meta:class": "https://ns.adobe.com/xdm/context/profile",
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Crear un esquema

El proceso de composición de esquema comienza asignando una clase. La clase define los aspectos de comportamiento clave de los datos (registro o serie temporal), así como los campos mínimos requeridos para describir los datos que se van a ingestar.

NOTA

La llamada de ejemplo siguiente es sólo un ejemplo básico de cómo crear un esquema en la API, con los requisitos de composición mínimos de una clase y sin mezclas. Para ver los pasos completos sobre cómo crear un esquema en la API, incluido cómo asignar campos mediante mezclas y tipos de datos, consulte el tutorial de creación de esquemas.

Formato API

POST /tenant/schemas

Solicitud

La solicitud debe incluir un atributo allOf que haga referencia al $id de una clase. Este atributo define la "clase base" que implementará el esquema. En este ejemplo, la clase base es una clase "Información de propiedad" que se creó anteriormente.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -H 'Authorization: Bearer {ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Property Information",
        "description": "Property-related information.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590" 
          } 
        ]
      }'
Propiedad Descripción
allOf Matriz de objetos, con cada objeto haciendo referencia a una clase o mezcla cuyos campos implementa el esquema. Cada objeto contiene una sola propiedad ($ref) cuyo valor representa el $id de la clase o mezcla que implementará el nuevo esquema. Se debe proporcionar una clase, con cero o más mezclas adicionales. En el ejemplo anterior, el objeto único de la matriz allOf es la clase del esquema.

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 (Creado) y una carga útil que contiene los detalles del esquema recién creado, incluidos los valores $id, meta:altId y version. Estos valores son de sólo lectura y son asignados por Schema Registry.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.0",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088461236,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Realizar una solicitud de GET para lista de todos los esquemas en el contenedor del inquilino ahora incluiría el nuevo esquema. Puede realizar una solicitud de búsqueda (GET) mediante el URI $id con codificación URL para realizar la vista del nuevo esquema directamente.

Para agregar campos adicionales a un esquema, puede realizar una operación de PATCH para agregar mezclas a los arreglos de discos allOf y meta:extends del esquema.

Actualizar un esquema

Puede reemplazar un esquema completo a través de una operación de PUT, básicamente reescribiendo el recurso. Al actualizar un esquema a través de una solicitud de PUT, el cuerpo debe incluir todos los campos que serían necesarios cuando cree un nuevo esquema en una solicitud de POST.

NOTA

Si solo desea actualizar parte de un esquema en lugar de reemplazarlo por completo, consulte la sección sobre actualización de una porción de un esquema.

Formato API

PUT /tenant/schemas/{SCHEMA_ID}
Parámetro Descripción
{SCHEMA_ID} El meta:altId o el $id codificado con URL del esquema que desea volver a escribir.

Solicitud

La siguiente solicitud reemplaza un esquema existente y cambia sus atributos title, description y allOf.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -H 'Authorization: Bearer {ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Commercial Property Information",
        "description": "Information related to commercial properties.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7" 
          } 
        ]
      }'

Respuesta

Una respuesta correcta devuelve los detalles del esquema actualizado.

{
    "title":"Commercial Property Information",
    "description": "Information related to commercial properties.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.0",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088470592,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Actualizar una parte de un esquema

Puede actualizar una parte de un esquema mediante una solicitud de PATCH. El Schema Registry soporta todas las operaciones estándar de parche JSON, incluyendo add, remove y replace. Para obtener más información sobre JSON Patch, consulte la guía de principios de API.

NOTA

Si desea reemplazar un recurso completo con nuevos valores en lugar de actualizar campos individuales, consulte la sección sobre reemplazo de un esquema mediante una operación de PUT.

Una de las operaciones de PATCH más comunes consiste en añadir mezclas previamente definidas a un esquema, como se muestra en el ejemplo siguiente.

Formato API

PATCH /tenant/schema/{SCHEMA_ID}
Parámetro Descripción
{SCHEMA_ID} El URI $id con codificación URL o meta:altId del esquema que desea actualizar.

Solicitud

La solicitud de ejemplo siguiente agrega una nueva mezcla a un esquema agregando el valor $id de la mezcla a los arreglos de discos meta:extends y allOf.

El cuerpo de la solicitud adopta la forma de una matriz, y cada objeto de la lista representa un cambio específico en un campo individual. Cada objeto incluye la operación que se va a realizar (op), el campo en el que se debe realizar la operación (path) y la información que se debe incluir en esa operación (value).

curl -X PATCH\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '[
        { 
          "op": "add",
          "path": "/meta:extends/-",
          "value":  "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        },
        {
          "op": "add",
          "path": "/allOf/-",
          "value":  {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
          }
        }
      ]'

Respuesta

La respuesta muestra que ambas operaciones se realizaron correctamente. La mezcla $id se ha agregado a la matriz meta:extends y ahora aparece una referencia ($ref) a la mezcla $id en la matriz allOf.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Habilite un esquema para utilizarlo en el Perfil del cliente en tiempo real

Para que un esquema pueda participar en Perfil del cliente en tiempo real, debe agregar una etiqueta union a la matriz meta:immutableTags del esquema. Esto se puede lograr haciendo una solicitud de PATCH para el esquema en cuestión.

IMPORTANTE

Las etiquetas inmutables son etiquetas que se pretenden definir, pero que nunca se eliminan.

Formato API

PATCH /tenant/schema/{SCHEMA_ID}
Parámetro Descripción
{SCHEMA_ID} El URI $id con codificación URL o meta:altId del esquema que desea habilitar.

Solicitud

La solicitud de ejemplo siguiente agrega una matriz meta:immutableTags a un esquema existente, lo que proporciona a la matriz un valor de cadena único de union para habilitarla para su uso en Perfil.

curl -X PATCH\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '[
        {
          "op": "add",
          "path": "/meta:immutableTags",
          "value": ["union"]
        }
      ]'

Respuesta

Una respuesta correcta devuelve los detalles del esquema actualizado, mostrando que se ha agregado la matriz meta:immutableTags.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    },
    "meta:immutableTags": [
      "union"
    ]
}

Ahora puede realizar una vista de la unión de esta clase de esquema para confirmar que los campos del esquema están representados. Consulte la guía del extremo uniones para obtener más información.

Eliminar un esquema

En ocasiones puede ser necesario retirar un esquema del Registro de Esquemas. Esto se realiza realizando una solicitud de DELETE con el ID de esquema proporcionado en la ruta.

Formato API

DELETE /tenant/schemas/{SCHEMA_ID}
Parámetro Descripción
{SCHEMA_ID} El URI $id con codificación URL o meta:altId del esquema que desea eliminar.

Solicitud

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

Respuesta

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

Puede confirmar la eliminación mediante una solicitud de búsqueda (GET) al esquema. Deberá incluir un encabezado Accept en la solicitud, pero debe recibir un estado HTTP 404 (no encontrado) porque el esquema se ha eliminado del Registro de Esquemas.

En esta página