Administrar valores sugeridos en la API

Para cualquier campo de cadena en el Modelo de datos de experiencia (XDM), puede definir un enum que restringe los valores que el campo puede introducir a un conjunto predefinido. Si intenta introducir datos en un campo de enumeración y el valor no coincide con ninguno de los definidos en su configuración, se denegará la ingesta.

A diferencia de las enumeraciones, agregar valores sugeridos a un campo de cadena no restringe los valores que puede introducir. En su lugar, los valores sugeridos afectan a los valores predefinidos disponibles en la variable IU de segmentación al incluir el campo de cadena como atributo.

NOTE
Los valores sugeridos actualizados de un campo tienen un retraso aproximado de cinco minutos que se reflejará en la interfaz de usuario de la segmentación.

Esta guía explica cómo administrar los valores sugeridos mediante API de Registro de esquemas. Para ver los pasos necesarios en la interfaz de usuario de Adobe Experience Platform, consulte la Guía de la IU sobre enumeraciones y valores sugeridos.

Requisitos previos

En esta guía se da por hecho que está familiarizado con los elementos de la composición de esquemas en XDM y con cómo utilizar la API de Registro de esquemas para crear y editar recursos XDM. Consulte la siguiente documentación si necesita una introducción:

También se recomienda encarecidamente que revise la reglas de evolución para enumeraciones y valores sugeridos si está actualizando campos existentes. Si está administrando valores sugeridos para esquemas que participan en una unión, consulte la reglas para combinar enumeraciones y valores sugeridos.

Composición

En la API, los valores restringidos para un enum Los campos se representan mediante una enum matriz, mientras que un meta:enum proporciona nombres descriptivos para mostrar para esos valores:

"exampleStringField": {
  "type": "string",
  "enum": [
    "value1",
    "value2",
    "value3"
  ],
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

Para los campos enum, el Registro de esquemas no permite meta:enum se amplíe más allá de los valores previstos en enum, ya que intentar introducir valores de cadena fuera de esas restricciones no pasaría la validación.

Como alternativa, puede definir un campo de cadena que no contenga un enum matriz y solo utiliza el meta:enum objeto que denotar valores sugeridos:

"exampleStringField": {
  "type": "string",
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

Dado que la cadena no tiene un enum matriz para definir restricciones, su meta:enum La propiedad se puede ampliar para incluir nuevos valores.

Añadir valores sugeridos a un campo estándar add-suggested-standard

Para ampliar el meta:enum de un campo de cadena estándar, puede crear un descriptor de nombre descriptivo para el campo en cuestión en un esquema determinado.

NOTE
Los valores sugeridos para campos de cadena solo se pueden agregar en el nivel de esquema. En otras palabras, ampliar el meta:enum de un campo estándar en un esquema no afecta a otros esquemas que emplean el mismo campo estándar.

La siguiente solicitud agrega valores sugeridos al estándar eventType campo (proporcionado por el clase XDM ExperienceEvent) para el esquema identificado en sourceSchema:

curl -X POST \
  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 'Content-Type: application/json' \
  -d '{
        "@type": "xdm:alternateDisplayInfo",
        "sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "sourceProperty": "/eventType",
        "title": {
            "en_us": "Enum Event Type"
        },
        "description": {
            "en_us": "Event type field with soft enum values"
        },
        "meta:enum": {
          "eventA": {
            "en_us": "Event Type A"
          },
          "eventB": {
            "en_us": "Event Type B"
          }
        }
      }'

Después de aplicar el descriptor, el Registro de esquemas responde con lo siguiente al recuperar el esquema (respuesta truncada para el espacio):

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "eventType": {
      "type":"string",
      "title": "Enum Event Type",
      "description": "Event type field with soft enum values.",
      "meta:enum": {
        "customEventA": "Custom Event Type A",
        "customEventB": "Custom Event Type B"
      }
    }
  }
}
NOTE
Si el campo estándar ya contiene valores en meta:enumSin embargo, los nuevos valores del descriptor no sobrescriben los campos existentes y se añaden en su lugar:
code language-json
"standardField": {
   "type":"string",
   "title": "Example standard enum field",
   "description": "Standard field with existing enum values.",
   "meta:enum": {
       "standardEventA": "Standard Event Type A",
       "standardEventB": "Standard Event Type B",
       "customEventA": "Custom Event Type A",
       "customEventB": "Custom Event Type B"
   }
}

Administrar los valores sugeridos para un campo personalizado suggested-custom

Para administrar el meta:enum En un campo personalizado, se puede actualizar la clase principal, el grupo de campos o el tipo de datos del campo mediante una solicitud de PATCH.

WARNING
A diferencia de los campos estándar, actualizar la variable meta:enum La selección de un campo personalizado afecta a todos los demás esquemas que emplean ese campo. Si no desea que los cambios se propaguen entre esquemas, considere la posibilidad de crear un nuevo recurso personalizado:

La siguiente solicitud actualiza el meta:enum de un campo de "nivel de lealtad" proporcionado por un tipo de datos personalizado:

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": "/loyaltyLevel/meta:enum",
          "value": {
            "ultra-platinum": "Ultra Platinum",
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          }
        }
      ]'

Después de aplicar el cambio, el Registro de esquemas responde con lo siguiente al recuperar el esquema (respuesta truncada para el espacio):

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "loyaltyLevel": {
      "type":"string",
      "title": "Loyalty Level",
      "description": "The loyalty program tier that this customer qualifies for.",
      "meta:enum": {
        "ultra-platinum": "Ultra Platinum",
        "platinum": "Platinum",
        "gold": "Gold",
        "silver": "Silver",
        "bronze": "Bronze"
      }
    }
  }
}

Pasos siguientes

En esta guía se explica cómo administrar los valores sugeridos para campos de cadena en la API del Registro de esquemas. Consulte la guía de definición de campos personalizados en la API para obtener más información sobre cómo crear diferentes tipos de campo.

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