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

Extremo de tipos de datos

Last update: Thu Dec 14 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Temas:

Creado para:

  • Desarrollador

Los tipos de datos se utilizan como campos de tipo de referencia en clases o grupos de campos de esquema de la misma manera que los campos literales básicos, con la diferencia clave de que los tipos de datos pueden definir varios subcampos. Aunque son similares a los grupos de campos en el sentido de que permiten el uso coherente de una estructura de varios campos, los tipos de datos son más flexibles porque se pueden incluir en cualquier parte de la estructura del esquema, mientras que los grupos de campos solo se pueden añadir en el nivel raíz. El /datatypes punto final en la Schema Registry La API permite administrar mediante programación los tipos de datos dentro de la aplicación de experiencia.

NOTE
Si un campo está definido como un tipo de datos específico, no se puede crear el mismo campo con un tipo de datos diferente en otro esquema. Esta restricción se aplica a todo el inquilino de la organización.

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 tipos de datos list

Puede enumerar todos los tipos de datos en global o tenant al realizar una solicitud de GET a /global/datatypes o /tenant/datatypes, respectivamente.

NOTE
Al enumerar recursos, el Registro de esquemas limita los conjuntos de resultados a 300 elementos. Para devolver recursos que superen 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 de API

GET /{CONTAINER_ID}/datatypes?{QUERY_PARAMS}
Parámetro
Descripción
{CONTAINER_ID}
El contenedor del que desea recuperar los tipos de datos: global para tipos de datos creados por Adobe o tenant para tipos de datos propiedad de su organización.
{QUERY_PARAMS}
Parámetros de consulta opcionales por los que filtrar los resultados. Consulte la documento anexo para obtener una lista de los parámetros disponibles.

Solicitud

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

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes?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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

El formato de respuesta depende de la variable Accept encabezado enviado en la solicitud. Lo siguiente Accept Los encabezados de están disponibles para enumerar tipos de datos:

Accept encabezado
Descripción
application/vnd.adobe.xed-id+json
Devuelve un breve resumen de cada recurso. Este es el encabezado recomendado para enumerar recursos. (Límite: 300)
application/vnd.adobe.xed+json
Devuelve el tipo de datos JSON completo de cada recurso, con el original $ref y allOf incluido. (Límite: 300)

Respuesta

La solicitud anterior utilizaba el application/vnd.adobe.xed-id+json Accept encabezado, por lo tanto la respuesta incluye solo el title, $id, meta:altId, y version atributos para cada tipo de datos. Uso del otro Accept encabezado (application/vnd.adobe.xed+json) devuelve todos los atributos de cada tipo de datos. Seleccione el adecuado Accept encabezado en función de la información que requiera en su respuesta.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
      "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
      "version": "1.0",
      "title": "Loyalty"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/4b0329b5573cbb7cb757db667d7fdf66",
      "meta:altId": "_{TENANT_ID}.datatypes.4b0329b5573cbb7cb757db667d7fdf66",
      "version": "1.0",
      "title": "Property Details"
    }
  ],
  "_page": {
    "orderby": "title",
    "next": null,
    "count": 2
  },
  "_links": {
    "next": null,
    "global_schemas": {
      "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/datatypes?orderby=title"
    }
  }
}

Búsqueda de un tipo de datos lookup

Puede buscar un tipo de datos específico incluyendo el ID del tipo de datos en la ruta de una solicitud de GET.

Formato de API

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

Solicitud

La siguiente solicitud recupera un tipo de datos mediante su meta:altId valor proporcionado en la ruta.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44 \
  -H 'Accept: application/vnd.adobe.xed+json' \
  -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}'

El formato de respuesta depende de la variable Accept encabezado enviado en la solicitud. Todas las solicitudes de búsqueda requieren un version se incluirá en la Accept encabezado. Lo siguiente Accept Los encabezados de están disponibles:

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

Respuesta

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

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
  "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Loyalty",
  "type": "object",
  "description": "Loyalty object containing loyalty-specific fields.",
  "definitions": {
    "customFields": {
      "properties": {
        "loyaltyId": {
          "title": "Loyalty ID",
          "description": "Unique loyalty program member ID. Should be in the format of an email address.",
          "type": "string",
          "meta:xdmType": "string"
        },
        "memberSince": {
          "title": "Member Since",
          "description": "Date person joined loyalty program.",
          "type": "string",
          "format": "date",
          "meta:xdmType": "date"
        },
        "points": {
          "title": "Points",
          "description": "Accumulated loyalty points",
          "type": "integer",
          "meta:xdmType": "int"
        },
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "The current loyalty program level to which the individual member belongs.",
          "type": "string",
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ],
          "meta:enum": {
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          },
          "meta:xdmType": "string"
        }
      },
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields"
    }
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1557529442681,
    "repo:lastModifiedDate": 1557529442681,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "50b8008b588e911314f9685240dd4c23a247f37179a6d9ff6ba3877dc11ca504",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Creación de un tipo de datos create

Puede definir un tipo de datos personalizados en la variable tenant contenedor realizando una solicitud de POST.

Formato de API

POST /tenant/datatypes

Solicitud

A diferencia de los grupos de campos, la definición de un tipo de datos no requiere meta:extends o meta:intendedToExtend tampoco es necesario anidar los campos para evitar conflictos.

Cuando se trata de definir la estructura de campo del propio tipo de datos, puede utilizar tipos primitivos (como string o object) o puede hacer referencia a otros tipos de datos existentes mediante $ref atributos. Consulte la guía de definición de campos XDM personalizados en la API para obtener instrucciones detalladas sobre el formato esperado para diferentes tipos de campo XDM.

La siguiente solicitud crea un tipo de datos de objeto "Property Construction" con subpropiedades yearBuilt, propertyType, y location:

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes \
  -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 '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type": "integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type": "string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "location": {
            "title": "Location",
            "description": "The physical location of the property.",
            "$ref": "https://ns.adobe.com/xdm/common/address"
          }
        }
      }'

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 (Creado) y una carga útil que contiene los detalles del tipo de datos recién creado, incluido el $id, meta:altId, y version. Estos tres valores son de solo lectura y los asigna el Schema Registry.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/669ffcc61cf5e94e8640dbe6a15f0f24eb3cd1ddbbfb6b36",
  "meta:altId": "_{TENANT_ID}.datatypes.669ffcc61cf5e94e8640dbe6a15f0f24eb3cd1ddbbfb6b36",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "location": {
      "title": "Location",
      "description": "The physical location of the property.",
      "$ref": "https://ns.adobe.com/xdm/common/address",
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "refs": [
    "https://ns.adobe.com/xdm/common/address"
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1670885230789,
    "repo:lastModifiedDate": 1670885230789,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "d3cc803a1f8daa06b7c150d882bd337d88f4d5d5f08d36cfc4c2849dc0255f7e",
    "meta:globalLibVersion": "1.38.3.1"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "1bd86660-c5da-11e9-93d4-6d5fc3a66a8e",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Realización de una solicitud de GET a enumerar todos los tipos de datos en el contenedor de inquilino ahora incluiría el tipo de datos Detalles de la propiedad, o bien puede realizar una solicitud de búsqueda (GET) uso de la codificación URL $id URI para ver directamente el nuevo tipo de datos.

Actualización de un tipo de datos put

Puede reemplazar un tipo de datos completo mediante una operación de PUT, básicamente reescribiendo el recurso. Al actualizar un tipo de datos mediante una solicitud de PUT, el cuerpo debe incluir todos los campos que serían necesarios al creación de un nuevo tipo de datos en una solicitud de POST.

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

Formato de API

PUT /tenant/datatypes/{DATA_TYPE_ID}
Parámetro
Descripción
{DATA_TYPE_ID}
El meta:altId o con codificación URL $id del tipo de datos que desea volver a escribir.

Solicitud

La siguiente solicitud reescribe un tipo de datos existente y agrega un nuevo floorSize field.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1 \
  -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 '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type": "integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type": "string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "floorSize" {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      }'

Respuesta

Una respuesta correcta devuelve los detalles del tipo de datos actualizado.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "floorSize" {
      "type":  "integer",
      "title":  "Floor Size",
      "description":  "The floor size of the property, in square feet.",
      "meta:xdmType": "int"
    }
  },
  "refs": [],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Actualizar una parte de un tipo de datos patch

Puede actualizar una parte de un tipo de datos mediante una solicitud de PATCH. El Schema Registry admite todas las operaciones de parche de JSON estándar, incluidas las siguientes add, remove, y replace. Para obtener más información sobre el parche JSON, consulte la Guía de aspectos básicos de API.

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

Formato de API

PATCH /tenant/data type/{DATA_TYPE_ID}
Parámetro
Descripción
{DATA_TYPE_ID}
La codificación URL $id URI o meta:altId del tipo de datos que desea actualizar.

Solicitud

La solicitud de ejemplo siguiente actualiza el description de un tipo de datos existente y añade un nuevo floorSize field.

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), en qué campo se debe realizar la operación (path) y qué información debe incluirse en esa operación (value).

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -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 'content-type: application/json' \
  -d '[
        {
          "op": "replace",
          "path": "/description",
          "value": "Construction-related information for a company-operated property."
        },
        {
          "op": "add",
          "path": "/properties/floorSize",
          "value": {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      ]'

Respuesta

La respuesta muestra que ambas operaciones se realizaron correctamente. El description se ha actualizado, y floorSize se ha añadido en definitions.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:altId": "_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:resourceType": "datatypes",
  "version": "1.2",
  "title": "Property Details",
  "type": "object",
  "description": "Details relating to a property operated by the company.",
  "definitions": {
    "property": {
      "properties": {
        "_{TENANT_ID}": {
        "type": "object",
        "properties": {
            "propertyName": {
              "type": "string",
              "title": "Property Name",
              "description": "Name of the property"
            },
            "propertyCity": {
              "title": "Property City",
              "description": "City where the property is located.",
              "type": "string"
            },
            "propertyCountry": {
              "title": "Property Country",
              "description": "Country where the property is located.",
              "type": "string"
            },
            "phoneNumber": {
              "title": "Phone Number",
              "description": "Primary phone number for the property.",
              "type": "string"
            },
            "propertyType": {
              "type": "string",
              "title": "Property Type",
              "description": "Type and primary use of property.",
              "enum": [
                  "retail",
                  "yoga",
                  "fitness"
              ],
              "meta:enum": {
                  "retail": "Retail Store",
                  "yoga": "Yoga Studio",
                  "fitness": "Fitness Center"
              }
            },
            "propertyConstruction": {
              "$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
            }
          }
        }
      }
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields",
      "type": "object",
      "meta:xdmType": "object"
    }
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:intendedToExtend": [
    "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1594941263588,
    "repo:lastModifiedDate": 1594941538433,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Eliminación de un tipo de datos delete

En ocasiones puede ser necesario quitar un tipo de datos del Registro de esquemas. Para ello, realice una solicitud de DELETE con el ID de tipo de datos proporcionado en la ruta.

Formato de API

DELETE /tenant/datatypes/{DATA_TYPE_ID}
Parámetro
Descripción
{DATA_TYPE_ID}
La codificación URL $id URI o meta:altId del tipo de datos que desea eliminar.

Solicitud

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.d5cc04eb8d50190001287e4c869ebe67 \
  -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.

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

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07