Gerenciar valores sugeridos na API

Para qualquer campo de cadeia de caracteres no Experience Data Model (XDM), é possível definir um enum que restrinja 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 das enumerações, adicionar valores sugeridos a um campo de cadeia de caracteres não restringe os valores que ele pode assimilar. Em vez disso, os valores sugeridos afetam quais valores predefinidos estão disponíveis na Interface de segmentação ao incluir o campo de sequência como um atributo.

Este guia aborda como gerenciar valores sugeridos usando a API do Registro de Esquema. Para obter etapas sobre como fazer isso na interface do usuário do Adobe Experience Platform, consulte o guia da interface sobre enumerações e valores sugeridos.

Pré-requisitos

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 as 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 as regras para mesclar enumerações e valores sugeridos.

Composição

Na API, os valores restritos de um campo enum são representados por uma matriz enum, enquanto um objeto meta:enum 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 que meta:enum seja estendido além dos valores fornecidos em enum, pois tentar assimilar valores de cadeia de caracteres fora dessas restrições não passaria na validação.

Como alternativa, você pode definir um campo de cadeia de caracteres que não contenha uma matriz enum e use apenas o objeto meta:enum para 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 uma matriz enum para definir restrições, sua propriedade meta:enum pode ser estendida para incluir novos valores.

Adicionar valores sugeridos a um campo padrão add-suggested-standard

Para estender o meta:enum de um campo de cadeia de caracteres padrão, você pode criar um descritor de nome amigável para o campo em questão em um esquema específico.

A solicitação a seguir adiciona valores sugeridos ao campo padrão eventType (fornecido pela 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"
      }
    }
  }
}

"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 suggested-custom

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.

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

Próximas etapas

Este guia abordou como gerenciar valores sugeridos para campos de string na API do registro de esquema. Consulte o manual sobre definição de campos personalizados na API para obter mais informações sobre como criar tipos de campos diferentes.