Show Menu
ARGOMENTI×

Definire una relazione tra due schemi utilizzando l'API del Registro di sistema dello schema

La capacità di comprendere le relazioni tra i clienti e le loro interazioni con il tuo marchio attraverso vari canali è una parte importante di Adobe Experience Platform. La definizione di queste relazioni all'interno della struttura degli schemi del modello dati esperienza (XDM) consente di acquisire informazioni complesse sui dati dei clienti.
Questo documento fornisce un'esercitazione per definire una relazione uno-a-uno tra due schemi definiti dall'organizzazione mediante l'API del Registro di schema.

Introduzione

Questa esercitazione richiede una buona conoscenza di Experience Data Model (XDM) e XDM System. Prima di iniziare questa esercitazione, consulta la seguente documentazione:
  • XDM System in Experience Platform : Panoramica di XDM e della relativa implementazione in Experience Platform.
  • Profilo cliente in tempo reale: Fornisce un profilo di consumo unificato e in tempo reale basato su dati aggregati provenienti da più origini.
  • Sandbox : Experience Platform fornisce sandbox virtuali che dividono una singola istanza della piattaforma in ambienti virtuali separati per sviluppare e sviluppare applicazioni per esperienze digitali.
Prima di avviare questa esercitazione, consultare la guida allo sviluppatore per informazioni importanti che è necessario conoscere per eseguire correttamente le chiamate all'API del Registro di sistema dello schema. Ciò include il vostro {TENANT_ID} , il concetto di "contenitori" e le intestazioni necessarie per effettuare le richieste (con particolare attenzione all’intestazione Accetta e ai suoi possibili valori).

Definire uno schema di origine e di destinazione

È previsto che siano già stati creati 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 uno schema "Membri fedeltà") e i loro alberghi preferiti (definiti in uno schema "Hotel").
Le relazioni dello schema sono rappresentate da uno schema di origine con un campo che fa riferimento a un altro campo all'interno di uno schema di destinazione. Nei passaggi successivi, "Membri fedeltà" sarà lo schema di origine, mentre "Alberghi" fungerà da schema di destinazione.
Per definire una relazione tra due schemi, è innanzitutto necessario acquisire i $id valori per entrambi gli schemi. Se si conoscono i nomi visualizzati ( title ) degli schemi, è possibile trovare $id i relativi valori eseguendo una richiesta GET all' /tenant/schemas endpoint nell'API del Registro di sistema dello schema.
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

L’intestazione Accetta application/vnd.adobe.xed-id+json restituisce solo i titoli, gli ID e le versioni degli schemi risultanti.
Risposta
Una risposta corretta restituisce un elenco di schemi definiti dall’organizzazione, inclusi i relativi schemi 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"
        }
    }
}

Registrare i $id valori dei due schemi tra cui si desidera definire una relazione. Questi valori verranno utilizzati nei passaggi successivi.

Definire i campi di riferimento per entrambi gli schemi

Nel Registro di sistema dello schema, i descrittori delle relazioni funzionano in modo simile alle chiavi esterne nelle tabelle SQL: un campo nello schema di origine funge da riferimento a un campo di uno schema di destinazione. Quando si definisce una relazione, ogni schema deve avere un campo dedicato da utilizzare come riferimento all'altro schema.
Se gli schemi devono essere attivati per l'uso in Real-time Customer Profile (Profilo cliente in tempo reale), il campo di riferimento per lo schema di destinazione deve essere la sua identità principale. Questo è spiegato più in dettaglio in questa esercitazione.
Se uno schema non dispone di un campo a questo scopo, potrebbe essere necessario creare un mixin con il nuovo campo e aggiungerlo allo schema. Il nuovo campo deve avere un type valore "string".
Ai fini di questa esercitazione, lo schema di destinazione "Hotels" contiene già un campo a tal fine: hotelId . Tuttavia, lo schema di origine "Membri fedeltà" non dispone di tale campo e deve essere dotato di un nuovo mixin che aggiunga un nuovo campo, favoriteHotel sotto il relativo TENANT_ID spazio nomi.

Creare un nuovo mixin

Per aggiungere un nuovo campo a uno schema, è innanzitutto necessario definirlo in un mixin. Per creare un nuovo mixin, effettuate una richiesta POST all’ /tenant/mixins endpoint.
Formato API
POST /tenant/mixins

Richiesta
La richiesta seguente crea un nuovo mixin che aggiunge un favoriteHotel campo nello TENANT_ID spazio dei nomi di qualsiasi schema a cui viene aggiunto.
curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/mixins \
  -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 mixin 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
Una risposta corretta restituisce i dettagli del mixin 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 mixin 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"
    }
}

Proprietà
Descrizione
$id
Identificatore univoco del nuovo mixin generato dal sistema di sola lettura. Ha la forma di un URI.
Registra l’ $id URI del mixin, da utilizzare nel passaggio successivo per aggiungere il mixin allo schema di origine.

Aggiungere il mixin allo schema di origine

Dopo aver creato un mixin, potete aggiungerlo allo schema di origine effettuando una richiesta PATCH all' /tenant/schemas/{SCHEMA_ID} endpoint.
Formato API
PATCH /tenant/schemas/{SCHEMA_ID}

Parametro
Descrizione
{SCHEMA_ID}
L' $id URI con codifica URL o meta:altId dello schema di origine.
Richiesta
La richiesta seguente aggiunge il mixin "Favorite Hotel" allo schema "Fedeltà Membri".
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"
      }
    }
  ]'

Proprietà
Descrizione
op
L’operazione PATCH da eseguire. Questa richiesta utilizza l' add operazione.
path
Percorso del campo dello schema in cui verrà aggiunta la nuova risorsa. Quando si aggiungono mixin agli schemi, il valore deve essere /allOf/- .
value.$ref
Il $id valore del mixin da aggiungere.
Risposta
Una risposta corretta restituisce i dettagli dello schema aggiornato, che ora include il $ref valore del mixin aggiunto sotto la sua allOf matrice.
{
    "$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="
    }
}

Definire i campi identità primari per entrambi gli schemi

Questo passaggio è richiesto solo per gli schemi che saranno attivati per l'uso nel profilo cliente in tempo reale. Se non si desidera che uno schema partecipi a un'unione o se gli schemi dispongono già di identità primarie definite, è possibile passare alla fase successiva della creazione di un descrittore di identità di riferimento per lo schema di destinazione.
Affinché gli schemi possano essere attivati per l'uso in Real-time Customer Profile, è necessario che abbiano definito un'identità primaria. Inoltre, lo schema di destinazione di una relazione deve utilizzare la propria identità primaria come campo di riferimento.
Ai fini di questa esercitazione, lo schema di origine ha già un'identità primaria definita, ma non lo schema di destinazione. È possibile contrassegnare un campo dello schema come campo di identità principale creando un descrittore di identità. Questa operazione viene eseguita eseguendo una richiesta POST all' /tenant/descriptors endpoint.
Formato API
POST /tenant/descriptors

Richiesta
La richiesta seguente crea un nuovo descrittore di identità che definisce il hotelId campo dello schema di destinazione "Hotels" come campo di identità principale.
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:descriptorIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:namespace": "ECID",
    "xdm:property": "xdm:code",
    "xdm:isPrimary": true
  }'

Parametro
Descrizione
@type
Il tipo di descrittore da creare. Il @type valore dei descrittori di identità è xdm:descriptorIdentity .
xdm:sourceSchema
Il $id valore dello schema di destinazione, ottenuto nel passaggio Definire uno schema di origine e di destinazione precedente.
xdm:sourceVersion
Numero di versione dello schema.
sourceProperty
Percorso del campo specifico che fungerà da identità principale dello schema. Questo percorso deve iniziare con "/" e non terminare con uno, escludendo anche eventuali spazi dei nomi "proprietà". Ad esempio, la richiesta di cui sopra utilizza /_{TENANT_ID}/hotelId invece di /properties/_{TENANT_ID}/properties/hotelId .
xdm:namespace
Spazio dei nomi identità per il campo identità. hotelId è un valore ECID in questo esempio, pertanto viene utilizzato lo spazio dei nomi "ECID". Per un elenco degli spazi dei nomi disponibili, consultate la panoramica dello spazio dei nomi identità.
xdm:isPrimary
Proprietà booleana che determina se il campo identità sarà l'identità principale per lo schema. Poiché questa richiesta definisce un'identità primaria, il valore è impostato su true.
Risposta
Una risposta corretta restituisce i dettagli del descrittore di identità appena creato.
{
    "@type": "xdm:descriptorIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:namespace": "ECID",
    "xdm:property": "xdm:code",
    "xdm:isPrimary": true,
    "meta:containerId": "tenant",
    "@id": "e3cfa302d06dc27080e6b54663511a02dd61316f"
}

Creare un descrittore di identità di riferimento

Ai campi dello schema deve essere applicato un descrittore di identità di riferimento se questi vengono utilizzati come riferimento da altri schemi in una relazione. Poiché il favoriteHotel campo in "Membri fedeltà" farà riferimento al hotelId campo in "Hotel", hotelId deve essere fornito un descrittore di identità di riferimento.
Create un descrittore di riferimento per lo schema di destinazione effettuando una richiesta POST all' /tenant/descriptors endpoint.
Formato API
POST /tenant/descriptors

Richiesta
La richiesta seguente crea un descrittore di riferimento per il hotelId campo nello schema di destinazione "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": "ECID"
  }'

Parametro
Descrizione
xdm:sourceSchema
L' $id URL dello schema di destinazione.
xdm:sourceVersion
Il numero di versione dello schema di destinazione.
sourceProperty
Percorso del campo identità principale dello schema di destinazione.
xdm:identityNamespace
Lo spazio dei nomi identità del campo di riferimento. hotelId è un valore ECID in questo esempio, pertanto viene utilizzato lo spazio dei nomi "ECID". Per un elenco degli spazi dei nomi disponibili, consultate la panoramica dello spazio dei nomi identità.
Risposta
Una risposta corretta restituisce i dettagli del descrittore di riferimento appena creato per lo schema di destinazione.
{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "ECID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

Creare un descrittore di relazione

I descrittori delle relazioni stabiliscono una relazione uno-a-uno tra uno schema di origine e uno schema di destinazione. Potete creare un nuovo descrittore di relazione facendo una richiesta POST all' /tenant/descriptors endpoint.
Formato API
POST /tenant/descriptors

Richiesta
La richiesta seguente crea un nuovo descrittore di relazione, con "Membri fedeltà" come schema di origine e "Membri fedeltà legacy" come schema di destinazione.
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"
  }'

Parametro
Descrizione
@type
Il tipo di descrittore da creare. Il @type valore dei descrittori di relazione è xdm:descriptorOneToOne .
xdm:sourceSchema
L' $id URL dello schema di origine.
xdm:sourceVersion
Il numero di versione dello schema di origine.
sourceProperty :
Percorso del campo di riferimento nello schema di origine.
xdm:destinationSchema
L' $id URL dello schema di destinazione.
xdm:destinationVersion
Il numero di versione dello schema di destinazione.
destinationProperty :
Percorso del campo di riferimento nello schema di destinazione.

Risposta

Una risposta corretta restituisce i dettagli del descrittore della 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, è stata creata una relazione uno-a-uno tra due schemi. Per ulteriori informazioni sull'utilizzo dei descrittori tramite l'API del Registro di sistema dello schema, vedere la guida per gli sviluppatori del Registro di schema. Per informazioni sulla definizione delle relazioni tra schemi nell'interfaccia utente, vedere l'esercitazione sulla definizione delle relazioni tra schemi utilizzando l'Editor di schema.