Administrar valores sugeridos en la API
Para cualquier campo de cadena en el modelo de datos de experiencia (XDM), puede definir un enum que restrinja los valores que el campo puede introducir en 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 ingerir. En su lugar, los valores sugeridos afectan a los valores predefinidos disponibles en la IU de segmentación al incluir el campo de cadena como atributo.
Esta guía explica cómo administrar los valores sugeridos mediante la API de Registro de esquemas. Para ver los pasos de cómo hacerlo en la interfaz de usuario de Adobe Experience Platform, consulte la guía de 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 es muy recomendable que revise las 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, vea las reglas para combinar enumeraciones y valores sugeridos.
Composición
En la API, los valores restringidos para un campo enum se representan mediante una matriz enum, mientras que un objeto 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 de enumeración, el Registro de esquemas no permite que meta:enum se extienda más allá de los valores proporcionados en enum, ya que al intentar introducir valores de cadena fuera de esas restricciones no se pasaría la validación.
Como alternativa, puede definir un campo de cadena que no contenga una matriz enum y que solo utilice el objeto meta:enum para 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 una matriz enum para definir restricciones, su propiedad meta:enum se puede ampliar para incluir nuevos valores.
Añadir valores sugeridos a un campo estándar add-suggested-standard
Para ampliar 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 particular.
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 campo eventType estándar (proporcionado por la 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"
}
}
}
}
meta:enum, los nuevos valores del descriptor no sobrescriben los campos existentes y se agregan en su lugar:| code language-json |
|---|
|
Administrar los valores sugeridos para un campo personalizado suggested-custom
Para administrar meta:enum de un campo personalizado, puede actualizar la clase primaria, el grupo de campos o el tipo de datos del campo mediante una solicitud de PATCH.
meta:enum 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 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 definición de campos personalizados en la API para obtener más información sobre cómo crear diferentes tipos de campos.