Defina una relación entre dos esquemas utilizando la variable Schema Registry API
La capacidad de comprender las relaciones entre sus clientes y sus interacciones con su marca en varios canales es una parte importante de Adobe Experience Platform. Definición de estas relaciones dentro de la estructura de su Experience Data Model Los esquemas (XDM) le permiten obtener perspectivas complejas sobre los datos de los clientes.
Mientras que las relaciones de esquema se pueden inferir mediante el uso del esquema de unión y Real-Time Customer Profile, esto solo se aplica a los esquemas que comparten la misma clase. Para establecer una relación entre dos esquemas que pertenecen a clases diferentes, se debe agregar un campo de relación dedicado a una esquema de origen, que indica la identidad de un esquema de referencia.
Este documento proporciona un tutorial para definir una relación uno a uno entre dos esquemas definidos por su organización mediante Schema Registry API.
Primeros pasos
Este tutorial requiere una comprensión práctica de Experience Data Model (XDM) y XDM System. Antes de comenzar este tutorial, revise la siguiente documentación:
- Sistema XDM en Experience Platform: Información general sobre XDM y su implementación en Experience Platform.
- Conceptos básicos de composición de esquemas: Introducción a los componentes básicos de los esquemas XDM.
- Real-Time Customer Profile: Proporciona un perfil de consumidor unificado y en tiempo real basado en los datos agregados de varias fuentes.
- Zonas protegidas: Experience Platform proporciona zonas protegidas virtuales que dividen una sola Platform en entornos virtuales independientes para ayudar a desarrollar y evolucionar aplicaciones de experiencia digital.
Antes de iniciar este tutorial, consulte la guía para desarrolladores para obtener información importante que necesita conocer para poder realizar llamadas correctamente a Schema Registry API. Esto incluye su {TENANT_ID}
, el concepto de "contenedores" y los encabezados necesarios para realizar solicitudes (con especial atención a la variable Accept y sus posibles valores).
Definir un esquema de origen y de referencia define-schemas
Se espera que ya haya creado los dos esquemas que se definirán en la relación. Este tutorial crea una relación entre los miembros del programa de fidelidad actual de una organización (definido en un "Loyalty Members" esquema) y sus hoteles favoritos (definidos en un "Hotels" esquema).
Las relaciones de esquema se representan mediante una variable esquema de origen tener un campo que haga referencia a otro campo dentro de una esquema de referencia. En los pasos siguientes, "Loyalty Members" será el esquema de origen, mientras que "Hotels" actuará como esquema de referencia.
Para definir una relación entre dos esquemas, primero debe adquirir la variable $id
valores para ambos esquemas. Si conoce los nombres para mostrar (title
) de los esquemas, puede encontrar su $id
al realizar una solicitud de GET a /tenant/schemas
punto final en la Schema Registry API.
Formato de API
GET /tenant/schemas
Solicitud
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xed-id+json'
application/vnd.adobe.xed-id+json
devuelve solo los títulos, ID y versiones de los esquemas resultantes.Respuesta
Una respuesta correcta devuelve una lista de esquemas definidos por la organización, incluidos sus name
, $id
, meta:altId
, y 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 el $id
valores de los dos esquemas entre los que desea definir una relación. Estos valores se utilizarán en pasos posteriores.
Definir un campo de referencia para el esquema de origen
Dentro de Schema RegistrySin embargo, los descriptores de relación funcionan de manera similar a las claves externas en las tablas de bases de datos relacionales: un campo del esquema de origen actúa como referencia al campo de identidad principal de un esquema de referencia. Si el esquema de origen no tiene un campo para este fin, es posible que tenga que crear un grupo de campos de esquema con el nuevo campo y añadirlo al esquema. Este nuevo campo debe tener un type
valor de string
.
En este tutorial, el esquema de referencia "Hotels" contiene un hotelId
que sirve como identidad principal del esquema. Sin embargo, el esquema de origen "Loyalty Members" no tiene un campo específico para utilizarse como referencia a hotelId
y, por lo tanto, se debe crear un grupo de campos personalizados para agregar un nuevo campo al esquema: favoriteHotel
.
Crear un nuevo grupo de campos
Para agregar un nuevo campo a un esquema, primero debe definirse en un grupo de campos. Puede crear un nuevo grupo de campos realizando una solicitud de POST a /tenant/fieldgroups
punto final.
Formato de API
POST /tenant/fieldgroups
Solicitud
La siguiente solicitud crea un nuevo grupo de campos que agrega un campo favoriteHotel
en el campo _{TENANT_ID}
área de nombres de cualquier esquema al que se agregue.
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: {ORG_ID}' \
-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"
}
]
}'
Respuesta
Una respuesta correcta devuelve los detalles del grupo de campos recién creado.
{
"$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"
}
}
$id
Registre el $id
URI del grupo de campos que se utilizará en el siguiente paso para añadir el grupo de campos al esquema de origen.
Añadir el grupo de campos al esquema de origen
Una vez creado un grupo de campos, puede agregarlo al esquema de origen realizando una solicitud de PATCH a /tenant/schemas/{SCHEMA_ID}
punto final.
Formato de API
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
URI o meta:altId
del esquema de origen.Solicitud
La siguiente solicitud agrega el "Favorite Hotel" grupo de campos a "Loyalty MembersEsquema ".
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '[
{
"op": "add",
"path": "/allOf/-",
"value": {
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
}
}
]'
op
add
operación.path
value.$ref
$id
del grupo de campos que se va a agregar.Respuesta
Una respuesta correcta devuelve los detalles del esquema actualizado, que ahora incluye la variable $ref
valor del grupo de campos agregado en su allOf
matriz.
{
"$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": "{ORG_ID}",
"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="
}
}
Creación de un descriptor de identidad de referencia reference-identity
Los campos de esquema deben tener un descriptor de identidad de referencia aplicado si se utilizan como referencia a otro esquema en una relación. Dado que la variable favoriteHotel
campo en "Loyalty Members" hará referencia a la variable hotelId
campo en "Hotels", favoriteHotel
debe recibir un descriptor de identidad de referencia.
Cree un descriptor de referencia para el esquema de origen realizando una solicitud de POST al /tenant/descriptors
punto final.
Formato de API
POST /tenant/descriptors
Solicitud
La siguiente solicitud crea un descriptor de referencia para el favoriteHotel
en el esquema de origen "Loyalty Members".
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:descriptorReferenceIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
"xdm:identityNamespace": "Hotel ID"
}'
@type
xdm:descriptorReferenceIdentity
.xdm:sourceSchema
$id
URL del esquema de origen.xdm:sourceVersion
sourceProperty
xdm:identityNamespace
Respuesta
Una respuesta correcta devuelve los detalles del descriptor de referencia recién creado para el campo de origen.
{
"@type": "xdm:descriptorReferenceIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
"xdm:identityNamespace": "Hotel ID",
"meta:containerId": "tenant",
"@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}
Creación de un descriptor de relación create-descriptor
Los descriptores de relación establecen una relación uno a uno entre un esquema de origen y un esquema de referencia. Una vez definido un descriptor de identidad de referencia para el campo correspondiente en el esquema de origen, se puede crear un nuevo descriptor de relación realizando una solicitud del POST a la variable /tenant/descriptors
punto final.
Formato de API
POST /tenant/descriptors
Solicitud
La siguiente solicitud crea un nuevo descriptor de relación, con "Loyalty Members" como esquema de origen y "Hotels" como esquema de referencia.
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: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"
}'
@type
@type
el valor de los descriptores de relación es xdm:descriptorOneToOne
.xdm:sourceSchema
$id
URL del esquema de origen.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
URL del esquema de referencia.xdm:destinationVersion
xdm:destinationProperty
Respuesta
Una respuesta correcta devuelve los detalles del descriptor de relación recién creado.
{
"@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"
}
Pasos siguientes
Al seguir este tutorial, ha creado correctamente una relación uno a uno entre dos esquemas. Para obtener más información sobre cómo trabajar con descriptores mediante Schema Registry API, consulte la Guía para desarrolladores de Schema Registry. Para ver los pasos sobre cómo definir relaciones de esquema en la interfaz de usuario, consulte el tutorial sobre definición de relaciones de esquema con el Editor de esquemas.