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 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.

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 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.

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 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.

Composição

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.

Adicionar valores sugeridos a um campo padrão

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.

OBSERVAÇÃO

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

AVISO

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

Próximas etapas

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.

Nesta página