Definir uma relação entre dois schemas usando a API Schema Registry

A capacidade de entender os relacionamentos entre seus clientes e suas interações com a marca em vários canais é uma parte importante do Adobe Experience Platform. Definir esses relacionamentos dentro da estrutura de seus esquemas Experience Data Model (XDM) permite que você obtenha insights complexos sobre os dados do cliente.

Embora os relacionamentos de esquema possam ser inferidos por meio do uso do schema de união e Real-time Customer Profile, isso se aplica somente a esquemas que compartilham a mesma classe. Para estabelecer uma relação entre dois schemas pertencentes a classes diferentes, um campo de relacionamento dedicado deve ser adicionado a um schema de origem, que faz referência à identidade de um schema de destino.

Este documento fornece um tutorial para definir uma relação um para um entre dois schemas definidos pela organização usando o Schema Registry API.

Introdução

Este tutorial requer uma compreensão funcional de Experience Data Model (XDM) e XDM System. Antes de iniciar este tutorial, reveja a seguinte documentação:

  • Sistema XDM no Experience Platform: Uma visão geral do XDM e sua implementação no Experience Platform.
  • Real-time Customer Profile: Fornece um perfil de consumidor unificado e em tempo real com base em dados agregados de várias fontes.
  • Sandboxes: Experience Platform O fornece sandboxes virtuais que particionam uma única Platform instância em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.

Antes de iniciar este tutorial, revise o guia do desenvolvedor para obter informações importantes que você precisa saber para fazer chamadas com êxito para a API Schema Registry. Isso inclui seu {TENANT_ID}, o conceito de "contêineres" e os cabeçalhos necessários para fazer solicitações (com especial atenção ao cabeçalho Accept e seus possíveis valores).

Definir um esquema de origem e de destino

Espera-se que você já tenha criado os dois schemas que serão definidos na relação. Este tutorial cria uma relação entre membros do programa de fidelidade atual de uma organização (definido em um schema "Loyalty Members") e seus hotéis favoritos (definido em um schema "Hotels").

As relações de esquema são representadas por um schema de origem tendo um campo que se refere a outro campo dentro de um schema de destino. Nas etapas a seguir, "Loyalty Members" será o schema de origem, enquanto "Hotels" atuará como o schema de destino.

IMPORTANTE

Para estabelecer uma relação, ambos os esquemas devem ter identidades primárias definidas e devem ser habilitados para Real-time Customer Profile. Consulte a seção ativando um schema para uso em Profile no tutorial de criação de schema se precisar de orientação sobre como configurar seus schemas de acordo.

Para definir uma relação entre dois schemas, primeiro você deve adquirir os valores $id para ambos os schemas. Se você souber os nomes de exibição (title) dos schemas, poderá encontrar seus valores $id fazendo uma solicitação GET para o endpoint /tenant/schemas na API Schema Registry.

Formato da API

GET /tenant/schemas

Solicitação

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'
OBSERVAÇÃO

O cabeçalho Accept application/vnd.adobe.xed-id+json retorna somente os títulos, IDs e versões dos esquemas resultantes.

Resposta

Uma resposta bem-sucedida retorna uma lista de schemas definidos pela organização, incluindo seus name, $id, meta:altId e version.

{
    "results": [
        {
            "title": "Newsletter Subscriptions",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/192a66930afad02408429174c311ae73",
            "meta:altId": "_{TENANT_ID}.schemas.192a66930afad02408429174c311ae73",
            "version": "1.2"
        },
        {
            "title": "Loyalty Members",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
            "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
            "version": "1.5"
        },
        {
            "title": "Hotels",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
            "meta:altId": "_{TENANT_ID}.schemas.d4ad4b8463a67f6755f2aabbeb9e02c7",
            "version": "1.0"
        }
    ],
    "_page": {
        "orderby": "updated",
        "next": null,
        "count": 3
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform-stage.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

Registre os valores $id dos dois esquemas que deseja definir uma relação entre eles. Esses valores serão usados em etapas posteriores.

Definir um campo de referência para o schema de origem

Dentro do Schema Registry, os descritores de relacionamento funcionam de forma semelhante às chaves estrangeiras nas tabelas de banco de dados relacional: um campo no schema de origem atua como uma referência para o campo de identidade primário de um schema de destino. Se o schema de origem não tiver um campo para essa finalidade, talvez seja necessário criar um grupo de campos de esquema com o novo campo e adicioná-lo ao schema. Este novo campo deve ter um valor type de "string".

IMPORTANTE

Diferente do schema de destino, o schema de origem não pode usar sua identidade primária como um campo de referência.

Neste tutorial, o schema de destino "Hotels" contém um campo hotelId que serve como a identidade primária do schema e, portanto, também atuará como seu campo de referência. No entanto, o schema de origem "Loyalty Members" não tem um campo dedicado para ser usado como referência e deve receber um novo grupo de campos que adicione um novo campo ao schema: favoriteHotel.

OBSERVAÇÃO

Se o schema de origem já tiver um campo dedicado que você planeja usar como um campo de referência, você pode pular para a etapa em criar um descritor de referência.

Criar um novo grupo de campos

Para adicionar um novo campo a um schema, ele deve primeiro ser definido em um grupo de campos. Você pode criar um novo grupo de campos fazendo uma solicitação de POST ao endpoint /tenant/fieldgroups.

Formato da API

POST /tenant/fieldgroups

Solicitação

A solicitação a seguir cria um novo grupo de campos que adiciona um campo favoriteHotel no namespace _{TENANT_ID} de qualquer schema ao qual ele for adicionado.

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '{
        "type": "object",
        "title": "Favorite Hotel",
        "meta:intendedToExtend": ["https://ns.adobe.com/xdm/context/profile"],
        "description": "Favorite hotel field group for the Loyalty Members schema.",
        "definitions": {
            "favoriteHotel": {
              "properties": {
                "_{TENANT_ID}": {
                  "type":"object",
                  "properties": {
                    "favoriteHotel": {
                      "title": "Favorite Hotel",
                      "type": "string",
                      "description": "Favorite hotel for a Loyalty Member."
                    }
                  }
                }
              }
            }
        },
        "allOf": [
            {
              "$ref": "#/definitions/favoriteHotel"
            }
        ]
      }'

Resposta

Uma resposta bem-sucedida retorna os detalhes do grupo de campos recém-criado.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220",
    "meta:altId": "_{TENANT_ID}.mixins.3387945212ad76ee59b6d2b964afb220",
    "meta:resourceType": "mixins",
    "version": "1.0",
    "type": "object",
    "title": "Favorite Hotel",
    "meta:intendedToExtend": [
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "description": "Favorite hotel field group for the Loyalty Members schema.",
    "definitions": {
        "favoriteHotel": {
            "properties": {
                "_{TENANT_ID}": {
                    "type": "object",
                    "properties": {
                        "favoriteHotel": {
                            "title": "Favorite Hotel",
                            "type": "string",
                            "description": "Favorite hotel for a Loyalty Member.",
                            "meta:xdmType": "string"
                        }
                    },
                    "meta:xdmType": "object"
                }
            },
            "type": "object",
            "meta:xdmType": "object"
        }
    },
    "allOf": [
        {
            "$ref": "#/definitions/favoriteHotel"
        }
    ],
    "meta:xdmType": "object",
    "meta:abstract": true,
    "meta:extensible": true,
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}",
    "meta:registryMetadata": {
        "eTag": "quM2aMPyb2NkkEiZHNCs/MG34E4=",
        "palm:sandboxName": "prod"
    }
}
Propriedade Descrição
$id O identificador exclusivo gerado pelo sistema, somente leitura, do novo grupo de campos. Assume a forma de um URI.

Registre o URI $id do grupo de campos, que será usado na próxima etapa de adicionar o grupo de campos ao schema de origem.

Adicionar o grupo de campos ao schema de origem

Depois de criar um grupo de campos, você pode adicioná-lo ao schema de origem fazendo uma solicitação de PATCH para o endpoint /tenant/schemas/{SCHEMA_ID}.

Formato da API

PATCH /tenant/schemas/{SCHEMA_ID}
Parâmetro Descrição
{SCHEMA_ID} O URL codificado $id URI ou meta:altId do schema de origem.

Solicitação

A solicitação a seguir adiciona o grupo de campo "Favorite Hotel" ao schema "Loyalty Members".

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
    { 
      "op": "add", 
      "path": "/allOf/-", 
      "value":  {
        "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
      }
    }
  ]'
Propriedade Descrição
op A operação PATCH a ser executada. Essa solicitação usa a operação add.
path O caminho para o campo de esquema onde o novo recurso será adicionado. Ao adicionar grupos de campos a schemas, o valor deve ser "/allOf/-".
value.$ref O $id do grupo de campos a ser adicionado.

Resposta

Uma resposta bem-sucedida retorna os detalhes do schema atualizado, que agora inclui o valor $ref do grupo de campos adicionados em sua matriz allOf.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
    "meta:resourceType": "schemas",
    "version": "1.1",
    "type": "object",
    "title": "Loyalty Members",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
        }
    ],
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:tenantNamespace": "_{TENANT_ID}",
    "imsOrg": "{IMS_ORG}",
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3",
        "https://ns.adobe.com/{TENANT_ID}/mixins/61969bc646b66a6230a7e8840f4a4d33"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557525483804,
        "repo:lastModifiedDate": 1566419670915,
        "xdm:createdClientId": "{API_KEY}",
        "xdm:lastModifiedClientId": "{CLIENT_ID}",
        "eTag": "ITNzu8BVTO5pw9wfCtTTpk6U4WY="
    }
}

Criar um descritor de identidade de referência

Os campos de esquema devem ter um descritor de identidade de referência aplicado a eles se estiverem sendo usados como referência de outros esquemas em um relacionamento. Como o campo favoriteHotel em "Loyalty Members" fará referência ao campo hotelId em "Hotels", hotelId deve receber um descritor de identidade de referência.

Crie um descritor de referência para o schema de destino fazendo uma solicitação de POST para o endpoint /tenant/descriptors .

Formato da API

POST /tenant/descriptors

Solicitação

A solicitação a seguir cria um descritor de referência para o campo hotelId no schema de destino "Hotels".

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID"
  }'
Parâmetro Descrição
@type O tipo de descritor que está sendo definido. Para descritores de referência, o valor deve ser "xdm:descriptorReferenceIdentity".
xdm:sourceSchema O URL $id do schema de destino.
xdm:sourceVersion O número da versão do schema de destino.
sourceProperty O caminho para o campo de identidade principal do esquema de destino.
xdm:identityNamespace O namespace de identidade do campo de referência. Deve ser o mesmo namespace usado ao definir o campo como a identidade primária do schema. Consulte a visão geral do namespace de identidade para obter mais informações.

Resposta

Uma resposta bem-sucedida retorna os detalhes do descritor de referência recém-criado para o esquema de destino.

{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

Criar um descritor de relacionamento

Os descritores de relacionamento estabelecem uma relação um para um entre um schema de origem e um schema de destino. Depois de definir um descritor de referência para o schema de destino, você pode criar um novo descritor de relacionamento fazendo uma solicitação de POST para o endpoint /tenant/descriptors.

Formato da API

POST /tenant/descriptors

Solicitação

A solicitação a seguir cria um novo descritor de relação, com "Loyalty Members" como o schema de origem e "Legacy Loyalty Members" como o schema de destino.

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId"
  }'
Parâmetro Descrição
@type O tipo de descritor a ser criado. O valor @type para descritores de relação é "xdm:descriptorOneToOne".
xdm:sourceSchema O URL $id do schema de origem.
xdm:sourceVersion O número da versão do schema de origem.
xdm:sourceProperty O caminho para o campo de referência no schema de origem.
xdm:destinationSchema O URL $id do schema de destino.
xdm:destinationVersion O número da versão do schema de destino.
xdm:destinationProperty O caminho para o campo de referência no schema de destino.

Resposta

Uma resposta bem-sucedida retorna os detalhes do descritor de relacionamento recém-criado.

{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId",
    "meta:containerId": "tenant",
    "@id": "76f6cc7105f4eaab7eb4a5e1cb4804cadc741669"
}

Próximas etapas

Ao seguir este tutorial, você criou com êxito uma relação um para um entre dois schemas. Para obter mais informações sobre como trabalhar com descritores usando a API Schema Registry, consulte o Guia do desenvolvedor do Registro de Schema. Para obter etapas sobre como definir relações de esquema na interface do usuário, consulte o tutorial em definição de relações de esquema usando o Editor de esquema.

Nesta página