Ponto de extremidade de descritores

Os esquemas definem a estrutura das entidades de dados, mas não especificam como os conjuntos de dados criados a partir desses esquemas se relacionam entre si. No Adobe Experience Platform, você pode usar descritores para descrever esses relacionamentos e adicionar metadados interpretativos a um esquema.

Os descritores são objetos de metadados em nível de locatário aplicados a esquemas no Adobe Experience Platform. Eles definem relações estruturais, chaves e campos comportamentais (como carimbos de data e hora ou controle de versão) que influenciam como os dados são validados, unidos ou interpretados downstream.

Um esquema pode ter um ou mais descritores. Cada descritor define um @type e o sourceSchema ao qual ele se aplica. O descritor se aplica automaticamente a todos os conjuntos de dados criados a partir desse esquema.

No Adobe Experience Platform, um descritor são metadados que adicionam regras comportamentais ou significado estrutural a um esquema.
Há vários tipos de descritores, incluindo:

O ponto de extremidade /descriptors na API Schema Registry permite gerenciar de forma programática os descritores no aplicativo de experiência.

Introdução

O ponto de extremidade usado neste guia faz parte da Schema Registry API. Antes de continuar, consulte o guia de introdução para obter links para a documentação relacionada, um guia para ler as chamadas de API de exemplo neste documento e informações importantes sobre os cabeçalhos necessários para fazer chamadas com êxito para qualquer API do Experience Platform.

Além dos descritores padrão, o Schema Registry dá suporte a tipos de descritores para esquemas baseados em modelo, como chave primária, versão e carimbo de data/hora. Eles impõem exclusividade, controlam versão e definem campos de série temporal no nível do esquema. Se você não estiver familiarizado com esquemas baseados em modelo, revise a visão geral do Data Mirror e a referência técnica de esquemas baseados em modelo antes de continuar.

Recuperar uma lista de descritores list

Você pode listar todos os descritores que foram definidos pela sua organização fazendo uma solicitação GET para /tenant/descriptors.

Formato da API

GET /tenant/descriptors

Solicitação

curl -X GET \
  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 'Accept: application/vnd.adobe.xdm-link+json'

O formato da resposta depende do cabeçalho Accept enviado na solicitação. Observe que o ponto de extremidade /descriptors usa Accept cabeçalhos que são diferentes de todos os outros pontos de extremidade na API Schema Registry.

Resposta

A resposta inclui uma matriz para cada tipo de descritor que tem descritores definidos. Em outras palavras, se não houver descritores de um determinado @type definido, o registro não retornará uma matriz vazia para esse tipo de descritor.

Ao usar o cabeçalho link Accept, cada descritor é mostrado como um item de matriz no formato /{CONTAINER}/descriptors/{DESCRIPTOR_ID}

{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

Pesquisar um descritor lookup

Para exibir os detalhes de um descritor específico, envie uma solicitação GET usando seu @id.

Formato da API

GET /tenant/descriptors/{DESCRIPTOR_ID}

Solicitação

A solicitação a seguir recupera um descritor por seu valor @id. Os descritores não têm controle de versão, portanto, nenhum cabeçalho Accept é necessário na solicitação de pesquisa.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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}'

Resposta

Uma resposta bem-sucedida retorna os detalhes do descritor, incluindo seus @type e sourceSchema, bem como informações adicionais que variam dependendo do tipo de descritor. O @id retornado deve corresponder ao descritor @id fornecido na solicitação.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{ORG_ID}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Criar um descritor create

Você pode criar um novo descritor fazendo uma solicitação POST para o ponto de extremidade /tenant/descriptors.

Formato da API

POST /tenant/descriptors

Solicitação

A solicitação a seguir define um descritor de identidade em um campo "endereço de email" em um esquema de amostra. Isso instrui Experience Platform a usar o endereço de email como um identificador para ajudar a compilar as informações sobre o indivíduo.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 201 (Criado) e os detalhes do descritor recém-criado, incluindo seu @id. @id é um campo somente leitura atribuído por Schema Registry e usado para fazer referência ao descritor na API.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Atualizar um descritor put

Você pode atualizar um descritor incluindo seu @id no caminho de uma solicitação PUT.

Formato da API

PUT /tenant/descriptors/{DESCRIPTOR_ID}

Solicitação

Essa solicitação reescreve essencialmente o descritor, de modo que o corpo da solicitação deve incluir todos os campos necessários para definir um descritor desse tipo. Em outras palavras, a carga da solicitação para atualizar (PUT) um descritor é a mesma que a carga para criar (POST) um descritor do mesmo tipo.

O exemplo a seguir atualiza um descritor de identidade para fazer referência a um xdm:sourceProperty (mobile phone) diferente e alterar o xdm:namespace para Phone.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 201 (Criado) e o @id do descritor atualizado (que deve corresponder ao @id enviado na solicitação).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Executar uma solicitação de pesquisa (GET) para exibir o descritor mostra que os campos foram atualizados para refletir as alterações enviadas na solicitação PUT.

Excluir um descritor delete

Ocasionalmente, talvez seja necessário remover um descritor definido de Schema Registry. Isso é feito fazendo uma solicitação DELETE referenciando o @id do descritor que você deseja remover.

Formato da API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}

Solicitação

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -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}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 204 (Sem conteúdo) e um corpo em branco.

Para confirmar se o descritor foi excluído, você pode executar uma solicitação de pesquisa em relação ao descritor @id. A resposta retorna o status HTTP 404 (Não Encontrado) porque o descritor foi removido de Schema Registry.

Apêndice appendix

A seção a seguir fornece informações adicionais sobre como trabalhar com descritores na API Schema Registry.

Definição de descritores defining-descriptors

As seções a seguir fornecem uma visão geral dos tipos de descritores disponíveis, incluindo os campos obrigatórios para definir um descritor de cada tipo.

Descritor de identidade identity-descriptor

Um descritor de identidade indica que "sourceProperty" de "sourceSchema" é um campo Identity, conforme descrito pelo Serviço de Identidade da Experience Platform.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}

Descritor de nome amigável friendly-name

Descritores de nome amigável permitem que um usuário modifique os valores title, description e meta:enum dos campos de esquema da biblioteca principal. Especialmente úteis ao trabalhar com "eVars" e outros campos "genéricos" que você deseja rotular como contendo informações específicas da organização. A interface pode usá-los para mostrar um nome mais amigável ou para mostrar apenas campos que tenham um nome amigável.

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  },
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out",
    "media.ping": "Media ping"
  }
}

Descritor de relacionamento relationship-descriptor

Os descritores de relacionamento descrevem uma relação entre dois esquemas diferentes, digitados nas propriedades descritas em xdm:sourceProperty e xdm:destinationProperty. Consulte o tutorial em definindo uma relação entre dois esquemas para obter mais informações.

Use estas propriedades para declarar como um campo de origem (chave estrangeira) se relaciona a um campo de destino (chave primária ou chave candidata).

A API oferece suporte a dois padrões:

Relação um para um (esquemas padrão)

Use isso ao manter integrações de esquema padrão existentes que já dependem de xdm:descriptorOneToOne.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

A tabela a seguir descreve os campos necessários para definir um descritor de relacionamento um para um.

Relação geral (esquemas baseados em modelo e recomendados para novos projetos)

Use esse descritor para todas as novas implementações e para esquemas baseados em modelo. Ela permite definir a cardinalidade da relação (como um para um ou muitos para um), especificar nomes de relação e vincular a um campo de destino que não seja a chave primária (chave não primária).

Os exemplos a seguir mostram como definir um descritor de relacionamento geral.

Exemplo mínimo:

Este exemplo mínimo inclui apenas os campos necessários para definir uma relação muitos para um entre dois schemas.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceProperty": "/customer_ref",
  "xdm:sourceVersion": 1,
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:cardinality": "M:1"
}

Exemplo com todos os campos opcionais:

Este exemplo inclui todos os campos opcionais, como nomes de relacionamento, títulos de exibição e um campo de destino de chave não primária explícito.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/customer_ref",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationProperty": "/customer_id",
  "xdm:sourceToDestinationName": "CampaignToCustomer",
  "xdm:destinationToSourceName": "CustomerToCampaign",
  "xdm:sourceToDestinationTitle": "Customer campaigns",
  "xdm:destinationToSourceTitle": "Campaign customers",
  "xdm:cardinality": "M:1"
}

Escolha de um descritor de relacionamento

Use as diretrizes a seguir para decidir qual descritor de relacionamento aplicar:

Comparação de recursos

A tabela a seguir compara os recursos dos dois tipos de descritor:

Restrições e validação

Siga estes requisitos e recomendações ao definir um descritor de relacionamento geral:

Descritor de chave primária primary-key-descriptor

O descritor de chave primária (xdm:descriptorPrimaryKey) impõe restrições de exclusividade e não nulas em um ou mais campos em um esquema.

{
  "@type": "xdm:descriptorPrimaryKey",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": ["/orderId", "/orderLineId"]
}

Descritor de versão version-descriptor

O descritor de versão (xdm:descriptorVersion) designa um campo para detectar e evitar conflitos de eventos de alteração fora de ordem.

{
  "@type": "xdm:descriptorVersion",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/versionNumber"
}

Descritor de carimbo de data e hora timestamp-descriptor

O descritor de carimbo de data/hora (xdm:descriptorTimestamp) designa um campo de data/hora como carimbo de data/hora para esquemas com "meta:behaviorType": "time-series".

{
  "@type": "xdm:descriptorTimestamp",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/eventTime"
}

Descritor de relacionamento B2B B2B-relationship-descriptor

O Real-Time CDP B2B edition apresenta uma maneira alternativa de definir relações entre esquemas, o que permite relações muitos para um. Esta nova relação deve ter o tipo @type: xdm:descriptorRelationship e a carga deve incluir mais campos do que a relação @type: xdm:descriptorOneToOne. Consulte o tutorial sobre definição de uma relação de esquema para o B2B edition para obter mais informações.

{
   "@type": "xdm:descriptorRelationship",
   "xdm:sourceSchema" : "https://ns.adobe.com/{TENANT_ID}/schemas/9f2b2f225ac642570a110d8fd70800ac0c0573d52974fa9a",
   "xdm:sourceVersion" : 1,
   "xdm:sourceProperty" : "/person-ref",
   "xdm:destinationSchema" : "https://ns.adobe.com/{TENANT_ID/schemas/628427680e6b09f1f5a8f63ba302ee5ce12afba8de31acd7",
   "xdm:destinationVersion" : 1,
   "xdm:destinationProperty": "/personId",
   "xdm:destinationNamespace" : "People",
   "xdm:destinationToSourceTitle" : "Opportunity Roles",
   "xdm:sourceToDestinationTitle" : "People",
   "xdm:cardinality": "M:1"
}

Descritor de identidade de referência

Os descritores de identidade de referência fornecem um contexto de referência para a identidade principal de um campo de esquema, permitindo que ele seja referenciado por campos em outros esquemas. O esquema de referência já deve ter um campo de identidade primário definido para que possa ser referenciado por outros esquemas por meio desse descritor.

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

Descritor de campo obsoleto

Você pode descontinuar um campo em um recurso XDM personalizado adicionando um atributo meta:status definido como deprecated ao campo em questão. No entanto, se você quiser descontinuar os campos fornecidos pelos recursos XDM padrão em seus esquemas, poderá atribuir um descritor de campo descontinuado ao esquema em questão para obter o mesmo efeito. Usando o cabeçalho Accept correto, você pode visualizar quais campos padrão foram descontinuados para um esquema ao pesquisá-lo na API.

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}