Definire una relazione tra due schemi utilizzando Schema Registry API
La capacità di comprendere le relazioni tra i clienti e le loro interazioni con il brand attraverso vari canali è una parte importante di Adobe Experience Platform. Definizione di queste relazioni all'interno della struttura Experience Data Model Gli schemi (XDM) consentono di ottenere informazioni complesse sui dati dei clienti.
Anche se le relazioni tra schemi possono essere dedotte tramite l’utilizzo dello schema di unione e Real-Time Customer Profile, applicabile solo agli schemi che condividono la stessa classe. Per stabilire una relazione tra due schemi appartenenti a classi diverse, è necessario aggiungere un campo relazione dedicato a schema di origine, che indica l'identità di un schema di riferimento.
Questo documento fornisce un tutorial per definire una relazione uno-a-uno tra due schemi definiti dalla tua organizzazione utilizzando Schema Registry API.
Introduzione
Questo tutorial richiede una buona conoscenza di Experience Data Model (XDM) XDM System. Prima di iniziare questo tutorial, consulta la seguente documentazione:
- Sistema XDM in Experience Platform: panoramica di XDM e della relativa implementazione in Experience Platform.
- Nozioni di base sulla composizione dello schema: introduzione dei blocchi predefiniti degli schemi XDM.
- Real-Time Customer Profile: fornisce un profilo consumer unificato e in tempo reale basato su dati aggregati provenienti da più origini.
- Sandbox: Experience Platform fornisce sandbox virtuali che permettono di suddividere un singolo Platform in ambienti virtuali separati, per facilitare lo sviluppo e l’evoluzione delle applicazioni di esperienza digitale.
Prima di iniziare questo tutorial, controlla guida per sviluppatori per informazioni importanti che è necessario conoscere per effettuare correttamente chiamate al Schema Registry API. Ciò include {TENANT_ID}
, il concetto di "contenitori" e le intestazioni necessarie per effettuare le richieste (con particolare attenzione al Accept e i possibili valori).
Definire uno schema di origine e di riferimento define-schemas
È previsto che tu abbia già creato i due schemi che verranno definiti nella relazione. Questa esercitazione crea una relazione tra i membri del programma fedeltà corrente di un’organizzazione (definito in un’ "Loyalty Members") e i loro hotel preferiti (definiti in una "Hotels").
Le relazioni tra schemi sono rappresentate da un schema di origine con un campo che fa riferimento a un altro campo all’interno di un schema di riferimento. Nei passaggi successivi, "Loyalty Members" sarà lo schema di origine, mentre "Hotels" fungerà da schema di riferimento.
Per definire una relazione tra due schemi, devi prima acquisire il $id
per entrambi gli schemi. Se si conoscono i nomi visualizzati (title
) degli schemi, puoi trovare le loro $id
effettuando una richiesta GET al /tenant/schemas
endpoint nella Schema Registry API.
Formato API
GET /tenant/schemas
Richiesta
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
restituisce solo i titoli, gli ID e le versioni degli schemi risultanti.Risposta
In caso di esito positivo, la risposta restituisce un elenco di schemi definiti dall’organizzazione, inclusi 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"
}
}
}
Registra il $id
valori dei due schemi tra cui si desidera definire una relazione. Questi valori verranno utilizzati nei passaggi successivi.
Definisci un campo di riferimento per lo schema di origine
All'interno del Schema Registry, i descrittori di relazione funzionano in modo simile alle chiavi esterne nelle tabelle del database relazionale: un campo nello schema di origine funge da riferimento al campo di identità primaria di uno schema di riferimento. Se lo schema di origine non dispone di un campo per questo scopo, potrebbe essere necessario creare un gruppo di campi schema con il nuovo campo e aggiungerlo allo schema. Questo nuovo campo deve avere type
valore di string
.
In questa esercitazione, lo schema di riferimento "Hotels" contiene un hotelId
che funge da identità primaria dello schema. Tuttavia, lo schema di origine "Loyalty Members" non dispone di un campo dedicato da utilizzare come riferimento a hotelId
, pertanto è necessario creare un gruppo di campi personalizzato per aggiungere un nuovo campo allo schema: favoriteHotel
.
Crea un nuovo gruppo di campi
Per aggiungere un nuovo campo a uno schema, è necessario innanzitutto definirlo in un gruppo di campi. È possibile creare un nuovo gruppo di campi effettuando una richiesta POST al /tenant/fieldgroups
endpoint.
Formato API
POST /tenant/fieldgroups
Richiesta
La richiesta seguente crea un nuovo gruppo di campi che aggiunge favoriteHotel
campo sotto _{TENANT_ID}
dello spazio dei nomi di qualsiasi schema a cui viene aggiunto.
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"
}
]
}'
Risposta
In caso di esito positivo, la risposta restituisce i dettagli del gruppo di campi appena creato.
{
"$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
Registra il $id
URI del gruppo di campi, da utilizzare nel passaggio successivo per aggiungere il gruppo di campi allo schema di origine.
Aggiungere il gruppo di campi allo schema di origine
Dopo aver creato un gruppo di campi, puoi aggiungerlo allo schema di origine effettuando una richiesta PATCH al /tenant/schemas/{SCHEMA_ID}
endpoint.
Formato API
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
URI o meta:altId
dello schema di origine.Richiesta
La richiesta seguente aggiunge "Favorite Hotel" al gruppo di campi "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: {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
operazione.path
value.$ref
$id
del gruppo di campi da aggiungere.Risposta
In caso di esito positivo, la risposta restituisce i dettagli dello schema aggiornato, che ora include il $ref
valore del gruppo di campi aggiunto sotto i relativi allOf
array.
{
"$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="
}
}
Creare un descrittore di identità di riferimento reference-identity
Ai campi schema deve essere applicato un descrittore di identità di riferimento se vengono utilizzati come riferimento a un altro schema in una relazione. Poiché il favoriteHotel
campo in "Loyalty Members" farà riferimento al hotelId
campo in "Hotels", favoriteHotel
deve essere fornito un descrittore di identità di riferimento.
Creare un descrittore di riferimento per lo schema di origine effettuando una richiesta POST al /tenant/descriptors
endpoint.
Formato API
POST /tenant/descriptors
Richiesta
La richiesta seguente crea un descrittore di riferimento per favoriteHotel
campo nello schema di origine "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 dello schema di origine.xdm:sourceVersion
sourceProperty
xdm:identityNamespace
Risposta
In caso di esito positivo, la risposta restituisce i dettagli del descrittore di riferimento appena creato per il campo sorgente.
{
"@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"
}
Creare un descrittore di relazione create-descriptor
I descrittori di relazione stabiliscono una relazione uno-a-uno tra uno schema di origine e uno schema di riferimento. Dopo aver definito un descrittore di identità di riferimento per il campo appropriato nello schema di origine, puoi creare un nuovo descrittore di relazione effettuando una richiesta POST al /tenant/descriptors
endpoint.
Formato API
POST /tenant/descriptors
Richiesta
La richiesta seguente crea un nuovo descrittore di relazione, con "Loyalty Members" come schema di origine e "Hotels" come schema di riferimento.
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
il valore per i descrittori di relazione è xdm:descriptorOneToOne
.xdm:sourceSchema
$id
URL dello schema di origine.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
URL dello schema di riferimento.xdm:destinationVersion
xdm:destinationProperty
Risposta
In caso di esito positivo, la risposta restituisce i dettagli del descrittore di relazione appena creato.
{
"@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"
}
Passaggi successivi
Seguendo questa esercitazione, hai creato correttamente una relazione uno-a-uno tra due schemi. Per ulteriori informazioni sull'utilizzo dei descrittori tramite Schema Registry API, consulta Guida per gli sviluppatori del registro dello schema. Per informazioni su come definire le relazioni tra schemi nell’interfaccia utente, consulta l’esercitazione su definizione delle relazioni tra schemi tramite l’Editor di schema.