Definire una relazione tra due schemi utilizzando l’API Schema Registry

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 Experience Data Model (XDM) consente di ottenere informazioni complesse sui dati dei clienti.

Mentre le relazioni dello schema possono essere dedotte mediante l'uso dello schema di unione e di Real-time Customer Profile, questo vale solo per gli schemi che condividono la stessa classe. Per stabilire una relazione tra due schemi appartenenti a classi diverse, è necessario aggiungere un campo di relazione dedicato a uno schema di origine che fa riferimento all'identità di uno schema di destinazione.

Questo documento fornisce un'esercitazione per definire una relazione uno-a-uno tra due schemi definiti dall'organizzazione utilizzando il percorso Schema Registry API.

Introduzione

Questa esercitazione richiede una buona comprensione di Experience Data Model (XDM) e XDM System. Prima di iniziare questa esercitazione, consulta la seguente documentazione:

  • Sistema XDM in Experience Platform: Panoramica di XDM e della sua implementazione in Experience Platform.
  • Real-time Customer Profile: Fornisce un profilo di consumatore unificato e in tempo reale basato su dati aggregati provenienti da più origini.
  • Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola Platform istanza in ambienti virtuali separati per sviluppare e sviluppare applicazioni di esperienza digitale.

Prima di avviare questa esercitazione, controlla la guida per gli sviluppatori per informazioni importanti che devi conoscere per effettuare correttamente le chiamate all’ API Schema Registry. Questo include il tuo {TENANT_ID}, il concetto di "contenitori" e le intestazioni richieste per effettuare richieste (con particolare attenzione all'intestazione Accept 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 "Loyalty Members") e i loro alberghi preferiti (definito in uno schema "Hotels").

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 seguenti, "Loyalty Members" sarà lo schema di origine, mentre "Hotels" fungerà da schema di destinazione.

IMPORTANTE

Per stabilire una relazione, entrambi gli schemi devono avere identità principali definite ed essere abilitati per Real-time Customer Profile. Per informazioni su come configurare di conseguenza gli schemi, consulta la sezione relativa all’ abilitazione di uno schema da utilizzare in Profile nell’esercitazione sulla creazione dello schema.

Per definire una relazione tra due schemi, è innanzitutto necessario acquisire i valori $id di entrambi gli schemi. Se conosci i nomi visualizzati (title) degli schemi, puoi trovare i loro valori $id effettuando una richiesta di GET all’endpoint /tenant/schemas nell’API Schema Registry.

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'
NOTA

L'intestazione Accept 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 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 i valori $id dei due schemi che desideri definire una relazione tra di essi. Questi valori verranno utilizzati nei passaggi successivi.

Definire un campo di riferimento per lo schema di origine

All'interno di Schema Registry, i descrittori di relazione funzionano in modo simile alle chiavi esterne nelle tabelle di database relazionali: un campo nello schema di origine funge da riferimento al campo di identità principale di uno schema di destinazione. Se lo schema di origine non dispone di un campo per questo scopo, potrebbe essere necessario creare un gruppo di campi dello schema con il nuovo campo e aggiungerlo allo schema. Questo nuovo campo deve avere un valore type di "string".

IMPORTANTE

A differenza dello schema di destinazione, lo schema di origine non può utilizzare la propria identità primaria come campo di riferimento.

In questa esercitazione, lo schema di destinazione "Hotels" contiene un campo hotelId che funge da identità principale dello schema e agisce quindi anche come campo di riferimento. Tuttavia, lo schema di origine "Loyalty Members" non dispone di un campo dedicato da utilizzare come riferimento e deve essere assegnato un nuovo gruppo di campi che aggiunge un nuovo campo allo schema: favoriteHotel.

NOTA

Se lo schema di origine dispone già di un campo dedicato che si intende utilizzare come campo di riferimento, è possibile passare al passaggio creazione di un descrittore di riferimento.

Crea un nuovo gruppo di campi

Per aggiungere un nuovo campo a uno schema, è innanzitutto necessario definirlo in un gruppo di campi. È possibile creare un nuovo gruppo di campi effettuando una richiesta POST all'endpoint /tenant/fieldgroups.

Formato API

POST /tenant/fieldgroups

Richiesta

La richiesta seguente crea un nuovo gruppo di campi che aggiunge un campo favoriteHotel nello spazio dei nomi _{TENANT_ID} 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: {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"
            }
        ]
      }'

Risposta

Una risposta corretta 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"
    }
}
Proprietà Descrizione
$id Identificatore univoco del nuovo gruppo di campi generato dal sistema di sola lettura. Si presenta sotto forma di URI.

Registra l' URI $id del gruppo di campi, da utilizzare nel passaggio successivo dell'aggiunta del gruppo di campi allo schema di origine.

Aggiungi il gruppo di campi allo schema di origine

Dopo aver creato un gruppo di campi, è possibile aggiungerlo allo schema di origine effettuando una richiesta PATCH all'endpoint /tenant/schemas/{SCHEMA_ID}.

Formato API

PATCH /tenant/schemas/{SCHEMA_ID}
Parametro Descrizione
{SCHEMA_ID} URI con codifica URL $id o meta:altId dello schema di origine.

Richiesta

La richiesta seguente aggiunge il gruppo di campi "Favorite Hotel" allo 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"
      }
    }
  ]'
Proprietà Descrizione
op Operazione PATCH da eseguire. Questa richiesta utilizza l'operazione add .
path Percorso del campo schema in cui verrà aggiunta la nuova risorsa. Quando si aggiungono gruppi di campi agli schemi, il valore deve essere "/allOf/-".
value.$ref Il $id del gruppo di campi da aggiungere.

Risposta

Una risposta corretta restituisce i dettagli dello schema aggiornato, che ora include il valore $ref del gruppo di campi aggiunti sotto la relativa matrice 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="
    }
}

Creare un descrittore di identità di riferimento

Ai campi dello schema deve essere applicato un descrittore di identità di riferimento se vengono utilizzati come riferimento da altri schemi in una relazione. Poiché il campo favoriteHotel in "Loyalty Members" fa riferimento al campo hotelId in "Hotels", hotelId deve avere un descrittore di identità di riferimento.

Crea un descrittore di riferimento per lo schema di destinazione effettuando una richiesta POST all'endpoint /tenant/descriptors.

Formato API

POST /tenant/descriptors

Richiesta

La richiesta seguente crea un descrittore di riferimento per il campo hotelId 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": "Hotel ID"
  }'
Parametro Descrizione
@type Il tipo di descrittore da definire. Per i descrittori di riferimento il valore deve essere "xdm:descriptorReferenceIdentity".
xdm:sourceSchema URL $id dello schema di destinazione.
xdm:sourceVersion Numero di versione dello schema di destinazione.
sourceProperty Percorso del campo di identità principale dello schema di destinazione.
xdm:identityNamespace Spazio dei nomi identità del campo di riferimento. Deve essere lo stesso namespace utilizzato quando si definisce il campo come identità principale dello schema. Per ulteriori informazioni, consulta la panoramica dello spazio dei nomi di 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": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

Creare un descrittore di relazione

I descrittori di relazione stabiliscono una relazione uno-a-uno tra uno schema di origine e uno schema di destinazione. Una volta definito un descrittore di riferimento per lo schema di destinazione, puoi creare un nuovo descrittore di relazione effettuando una richiesta POST all'endpoint /tenant/descriptors.

Formato API

POST /tenant/descriptors

Richiesta

La richiesta seguente crea un nuovo descrittore di relazione, con "Loyalty Members" come schema di origine e "Legacy Loyalty Members" 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 valore @type per i descrittori di relazione è "xdm:descriptorOneToOne".
xdm:sourceSchema URL $id dello schema di origine.
xdm:sourceVersion Numero di versione dello schema di origine.
xdm:sourceProperty Percorso del campo di riferimento nello schema di origine.
xdm:destinationSchema URL $id dello schema di destinazione.
xdm:destinationVersion Numero di versione dello schema di destinazione.
xdm:destinationProperty Percorso del campo di riferimento nello schema di destinazione.

Risposta

Una risposta corretta 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, è stata creata una relazione uno-a-uno tra due schemi. Per ulteriori informazioni sull'utilizzo dei descrittori tramite l'API Schema Registry, consulta la Guida per gli sviluppatori del Registro di sistema dello schema. Per i passaggi su come definire le relazioni di schema nell'interfaccia utente, consulta l'esercitazione su definizione delle relazioni di schema utilizzando l'Editor di schema.

In questa pagina