Show Menu
SUJETS×

Define a relationship between two schemas using the Schema Registry API

Comprendre les relations entre vos clients et leurs interactions avec votre marque sur divers canaux est un aspect important d’Adobe Experience Platform. Defining these relationships within the structure of your Experience Data Model (XDM) schemas allows you to gain complex insights into your customer data.
Bien que les relations de schéma puissent être déduites par l'utilisation du schéma et Real-time Customer Profilede l'union, cela ne s'applique qu'aux schémas qui partagent la même classe. Pour établir une relation entre deux schémas appartenant à des classes différentes, un champ de relation dédié doit être ajouté à un schéma source, qui fait référence à l'identité d'un schéma de destination.
This document provides a tutorial for defining a one-to-one relationship between two schemas defined by your organization using the Schema Registry API .

Prise en main

Ce didacticiel nécessite une bonne compréhension de Experience Data Model (XDM) et XDM System. Avant de commencer ce tutoriel, consultez la documentation suivante :
  • Système XDM en Experience Platform : Présentation de XDM et de sa mise en oeuvre dans Experience Platform.
  • Profil client en temps réel : Fournit un profil de consommation unifié en temps réel basé sur des données agrégées provenant de plusieurs sources.
  • Sandbox : Experience Platform fournit des sandbox virtuels qui partitionnent une Platform instance unique en environnements virtuels distincts pour aider à développer et développer des applications d'expérience numérique.
Avant de commencer ce tutoriel, veuillez consulter le guide de développement pour trouver les informations importantes à connaître afin d’effectuer avec succès des appels vers l’API Schema Registry Cela inclut votre {TENANT_ID} , le concept de « conteneurs » et les en-têtes requis pour effectuer des requêtes (avec une attention particulière à l’en-tête et à ses valeurs possibles).Accept

Définition d’un schéma source et de destination

Vous devez avoir déjà créé les deux schémas qui seront définis dans la relation. This tutorial creates a relationship between members of an organization's current loyalty program (defined in a "Loyalty Members" schema) and their favorite hotels (defined in a "Hotels" schema).
Les relations de schémas sont représentées par un schéma source disposant d’un champ qui fait référence à un autre champ dans un schéma de destination . In the steps that follow, "Loyalty Members" will be the source schema, while "Hotels" will act as the destination schema.
Pour établir une relation, les deux schémas doivent avoir défini des identités Principales et être autorisés à Real-time Customer Profileétablir une relation. Reportez-vous à la section relative à l’ activation d’un schéma pour une utilisation en Profil dans le didacticiel de création de schéma si vous avez besoin de conseils sur la manière de configurer vos schémas en conséquence.
Pour définir une relation entre deux schémas, vous devez d’abord acquérir les valeurs $id des deux schémas. Si vous connaissez les noms d’affichage ( title ) des schémas, vous pouvez trouver leurs valeurs $id en envoyant une requête GET au point de terminaison /tenant/schemas dans l’API Schema Registry
Format d’API
GET /tenant/schemas

Requête
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'

The Accept header application/vnd.adobe.xed-id+json returns only the titles, IDs, and versions of the resulting schemas.
Réponse
Une réponse réussie renvoie une liste de schémas définis par votre organisation, y compris les name , $id , meta:altId et 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"
        }
    }
}

Enregistrez les valeurs $id des deux schémas entre lesquels que vous souhaitez définir une relation. Ces valeurs seront utilisées ultérieurement.

Définir un champ de référence pour le schéma source

Within the Schema Registry, relationship descriptors work similarly to foreign keys in relational database tables: a field in the source schema acts as a reference to the primary identity field of a destination schema. Si votre schéma source n’a pas de champ à cette fin, vous devrez peut-être créer un mixin avec le nouveau champ et l’ajouter au schéma. This new field must have a type value of "string".
Contrairement au schéma de destination, l'schéma source ne peut pas utiliser son Principale identité comme champ de référence.
Dans ce didacticiel, le schéma de destination "Hotels" contient un email champ qui sert d'identité Principale du schéma et servira donc également de champ de référence. Cependant, le schéma source "Loyalty Members" ne dispose pas d’un champ dédié à utiliser comme référence et doit recevoir un nouveau mixin qui ajoute un nouveau champ au schéma : favoriteHotel .
Si votre schéma source comporte déjà un champ dédié que vous prévoyez d’utiliser comme champ de référence, vous pouvez passer à l’étape suivante lors de la création d’un descripteur de référence.

Création d’un nouveau mixin

Pour ajouter un nouveau champ à un schéma, ce champ doit d’abord être défini dans un mixin. Vous pouvez créer un mixin en envoyant une requête POST au point de terminaison /tenant/mixins .
Format d’API
POST /tenant/mixins

Requête
La requête suivante crée un mixin ajoutant un champ favoriteHotel sous l’espace de noms _{TENANT_ID} de tout schéma auquel il est ajouté.
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"
            }
        ]
      }'

Réponse
Une réponse réussie renvoie les détails du nouveau mixin.
{
    "$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"
    }
}

Propriété
Description
$id
L’identifiant unique, généré par le système et en lecture seule du nouveau mixin. Il prend la forme d’un URI.
Enregistrez l’URI $id du mixin à utiliser dans l’étape suivante de l’ajout du mixin au schéma source.

Ajout du mixin au schéma source

Une fois que vous avez créé un mixin, vous pouvez l’ajouter au schéma source en envoyant une requête PATCH au point de terminaison /tenant/schemas/{SCHEMA_ID} .
Format d’API
PATCH /tenant/schemas/{SCHEMA_ID}

Paramètre
Description
{SCHEMA_ID}
L’URI $id encodé URL ou meta:altId du schéma source.
Requête
The following request adds the "Favorite Hotel" mixin to the "Loyalty Members" schema.
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"
      }
    }
  ]'

Propriété
Description
op
Opération PATCH à effectuer. Cette requête utilise l’opération add .
path
Le chemin d’accès au champ de schéma où la nouvelle ressource sera ajoutée. Lors de l’ajout de mixins aux schémas, la valeur doit être "/allOf/-".
value.$ref
Le $id du mixin à ajouter.
Réponse
Une réponse réussie renvoie les détails du schéma mis à jour, qui inclut désormais la valeur $ref du mixin ajouté sous son tableau 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="
    }
}

Création d’un descripteur d’identité de référence

Un descripteur d’identité de référence doit être appliqué aux champs du schéma s’ils sont utilisés comme référence par d’autres schémas dans une relation. Since the favoriteHotel field in "Loyalty Members" will refer to the email field in "Hotels", email must be given a reference identity descriptor.
Créez un descripteur de référence pour le schéma de destination en envoyant une requête POST au point de terminaison /tenant/descriptors .
Format d’API
POST /tenant/descriptors

Requête
The following request creates a reference descriptor for the email field in the destination schema "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}/email",
    "xdm:identityNamespace": "Email"
  }'

Paramètre
Description
@type
Le type de descripteur en cours de définition. Pour les descripteurs de référence, la valeur doit être "xdm:descriptorReferenceIdentity".
xdm:sourceSchema
L’URL $id du schéma de destination.
xdm:sourceVersion
Le numéro de version du schéma de destination.
sourceProperty
Le chemin d’accès au champ d’identité principale du schéma de destination.
xdm:identityNamespace
L’espace de noms d’identité du champ de référence. Il doit s’agir du même espace de nommage utilisé lors de la définition du champ que l’identité Principale du schéma. Pour plus d’informations, voir Présentation des espaces de noms d’identité .
Réponse
Une réponse réussie renvoie les détails du descripteur d’identité que vous venez de créer pour le schéma de destination.
{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/email",
    "xdm:identityNamespace": "Email",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

Création d’un descripteur de relation

Les descripteurs de relation établissent une relation un-à-un entre un schéma source et un schéma de destination. Une fois que vous avez défini un descripteur de référence pour le schéma de destination, vous pouvez créer un nouveau descripteur de relation en envoyant une requête de POST au point de /tenant/descriptors terminaison.
Format d’API
POST /tenant/descriptors

Requête
The following request creates a new relationship descriptor, with "Loyalty Members" as the source schema and "Legacy Loyalty Members" as the destination schema.
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}/email"
  }'

Paramètre
Description
@type
Le type de descripteur à créer. The @type value for relationship descriptors is "xdm:descriptorOneToOne".
xdm:sourceSchema
L’URL $id du schéma source.
xdm:sourceVersion
Le numéro de version du schéma source.
xdm:sourceProperty
Chemin d’accès au champ de référence dans le schéma source.
xdm:destinationSchema
L’URL $id du schéma de destination.
xdm:destinationVersion
Le numéro de version du schéma de destination.
xdm:destinationProperty
Chemin d’accès au champ de référence dans le schéma de destination.

Réponse

Une réponse réussie renvoie les détails du descripteur de relation que vous venez de créer.
{
    "@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"
}

Étapes suivantes

En suivant ce tutoriel, vous avez réussi à créer une relation un-à-un entre deux schémas. For more information on working with descriptors using the Schema Registry API, see the Schema Registry developer guide . Pour savoir comment définir des relations de schémas dans l’interface utilisateur, consultez le tutoriel sur la définition de relations de schémas à l’aide de l’éditeur de schémas .