Para qualquer campo de string no Experience Data Model (XDM), é possível definir um enum que restringe os valores que o campo pode assimilar em um conjunto predefinido. Se você tentar assimilar dados em um campo enum e o valor não corresponder a nenhum dos definidos em sua configuração, a assimilação será negada.
Ao contrário de enumerações, adicionar valores sugeridos a um campo de string não restringe os valores que ele pode assimilar. Em vez disso, os valores sugeridos afetam quais valores predefinidos estão disponíveis no Interface de segmentação ao incluir o campo de string como um atributo.
Há um atraso de aproximadamente cinco minutos para que os valores sugeridos atualizados de um campo sejam refletidos na interface do usuário de segmentação.
Este guia aborda como gerenciar valores sugeridos usando o API do registro de esquema. Para obter etapas sobre como fazer isso na interface do usuário do Adobe Experience Platform, consulte a Guia da interface do usuário sobre enumerações e valores sugeridos.
Este guia supõe que você esteja familiarizado com os elementos da composição do esquema no XDM e como usar a API do Registro de esquema para criar e editar recursos do XDM. Consulte a documentação a seguir se precisar de uma introdução:
Também é altamente recomendável que você revise a regras de evolução para enumerações e valores sugeridos se estiver atualizando campos existentes. Se você estiver gerenciando valores sugeridos para esquemas que participam de uma união, consulte regras para mesclar enumerações e valores sugeridos.
Na API, os valores restritos de um enum são representados por um enum
, enquanto uma meta:enum
O objeto fornece nomes de exibição amigáveis para esses valores:
"exampleStringField": {
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
Para campos enum, o Registro de esquema não permite meta:enum
para além dos valores fornecidos em enum
, já que tentar assimilar valores de string fora dessas restrições não passaria na validação.
Como alternativa, você pode definir um campo de string que não contenha um enum
e usa somente o meta:enum
objeto a ser denotado valores sugeridos:
"exampleStringField": {
"type": "string",
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
Como a cadeia de caracteres não tem um enum
matriz para definir restrições, suas meta:enum
pode ser estendida para incluir novos valores.
Para estender o meta:enum
de um campo de sequência padrão, é possível criar uma descritor de nome amigável para o campo em questão em um esquema específico.
Os valores sugeridos para campos de string só podem ser adicionados no nível do esquema. Por outras palavras, a extensão do meta:enum
de um campo padrão em um esquema não afeta outros esquemas que empregam o mesmo campo padrão.
A solicitação a seguir adiciona os valores sugeridos ao padrão eventType
campo (fornecido pela variável Classe XDM ExperienceEvent) para o esquema identificado em 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"
}
}
}'
Após aplicar o descritor, o Registro de esquema responde com o seguinte ao recuperar o esquema (resposta truncada por espaço):
{
"$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"
}
}
}
}
Se o campo padrão já contiver valores em meta:enum
, os novos valores do descritor não substituem os campos existentes e são adicionados em:
"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"
}
}
Para gerenciar o meta:enum
de um campo personalizado, você pode atualizar a classe pai, o grupo de campos ou o tipo de dados do campo por meio de uma solicitação PATCH.
Ao contrário dos campos padrão, a atualização da variável meta:enum
de um campo personalizado afeta todos os outros esquemas que empregam esse campo. Se você não quiser que as alterações se propaguem nos esquemas, considere criar um novo recurso personalizado:
A solicitação a seguir atualiza o meta:enum
de um campo "nível de fidelidade" fornecido por um tipo de dados 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"
}
}
]'
Depois de aplicar a alteração, o Registro de esquema responde com o seguinte ao recuperar o esquema (resposta truncada por espaço):
{
"$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"
}
}
}
}
Este guia abordou como gerenciar valores sugeridos para campos de string na API do registro de esquema. Consulte o guia sobre definição de campos personalizados na API para obter mais informações sobre como criar tipos de campo diferentes.