Gerenciar valores sugeridos na API

Para qualquer campo de string no Experience Data Model (XDM), é possível definir um enum que restringe os valores que o campo pode assimilar a um conjunto predefinido. Se você tentar assimilar dados para um campo enum e o valor não corresponder a nenhum daqueles definidos em sua configuração, a assimilação será negada.

Em contraste com enumerações, adicionar valores sugeridos para 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 na variável Interface do usuário de segmentação ao incluir o campo de string como um atributo.

OBSERVAÇÃO

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 os valores sugeridos usando o API do Registro de Schema. Para obter etapas sobre como fazer isso na interface do usuário do Adobe Experience Platform, consulte o Guia de interface do usuário sobre enumerações e valores sugeridos.

Pré-requisitos

Este guia pressupõe que você esteja familiarizado com os elementos da composição do esquema no XDM e como usar a API do Registro de Schema para criar e editar recursos do XDM. Consulte a seguinte documentação se você precisar de uma introdução:

Também é altamente recomendável revisar a variável regras de evolução para enumerações e valores sugeridos se estiver atualizando campos existentes. Se você estiver gerenciando valores sugeridos para schemas que participam de uma união, consulte o regras para mesclar enumerações e valores sugeridos.

Composição

Na API, os valores restritos de um enum são representadas por um enum array, enquanto um 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 previstos no enum, pois tentar assimilar valores de string fora dessas restrições não passaria pela 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 denotar 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, sua meta:enum pode ser estendida para incluir novos valores.

Adicionar valores sugeridos a um campo padrão

Para estender o meta:enum de um campo de string padrão, é possível criar um descritor de nome amigável para o campo em questão em um schema específico.

OBSERVAÇÃO

Os valores sugeridos para campos de cadeia de caracteres só podem ser adicionados no nível do esquema. Por outras palavras, estender a meta:enum de um campo padrão em um schema não afeta outros schemas que usam o mesmo campo padrão.

A solicitação a seguir adiciona valores sugeridos ao padrão eventType (fornecido pelo Classe XDM ExperienceEvent) para o schema 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"
          }
        }
      }'

Depois de aplicar o descritor, o Registro de Esquema responde com o seguinte ao recuperar o esquema (resposta truncada para 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"
      }
    }
  }
}
OBSERVAÇÃO

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"
   }
}

Gerenciar valores sugeridos para um campo personalizado

Para gerenciar a meta:enum de um campo personalizado, é possível atualizar a classe pai, o grupo de campos ou o tipo de dados do campo por meio de uma solicitação de PATCH.

AVISO

Em contraste com os campos padrão, atualize o meta:enum de um campo personalizado afeta todos os outros schemas que empregam esse campo. Se você não quiser que as alterações se propaguem entre esquemas, considere criar um novo recurso personalizado:

A solicitação a seguir atualiza o meta:enum de um campo de "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 para 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"
      }
    }
  }
}

Próximas etapas

Este guia cobriu como gerenciar valores sugeridos para campos de sequência na API do Registro de Schema. Consulte o guia sobre definição de campos personalizados na API para obter mais informações sobre como criar tipos de campos diferentes.

Nesta página