Documentation Experience Platform Guide de modèle de données d’expérience (XDM)

Définir une relation entre deux schémas à l’aide de l’API Schema Registry

5 mai 2025

Rubriques :

Créé pour :

Développeur

Comprendre les relations entre vos clients et leurs interactions avec votre marque sur divers canaux est un aspect important d’Adobe Experience Platform. La définition de ces relations dans la structure de vos schémas Experience Data Model (XDM) vous permet d’obtenir des informations complexes sur vos données client.

Bien que les relations de schéma puissent être déduites par l’utilisation du schéma d’union et Real-Time Customer Profile, cela s’applique uniquement aux schémas partageant 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 indique l’identité d’un schéma de référence distinct.

NOTE

L’API Schema Registry fait référence aux schémas de référence en tant que « schémas de destination ». Ils ne doivent pas être confondus avec les schémas de destination dans les jeux de mappages de la préparation des données ou les schémas pour les connexions de destination.

Ce document fournit un tutoriel expliquant comment définir une relation un-à-un entre deux schémas définis par votre organisation à l’aide de l’Schema Registry API .

Commencer

Ce tutoriel nécessite une compréhension pratique de Experience Data Model (XDM) et de XDM System. Avant de commencer ce tutoriel, consultez la documentation suivante :

Système XDM dans Experience Platform : présentation de XDM et de sa mise en œuvre dans Experience Platform.
- Principes de base de composition des schémas : une présentation des blocs de création de schémas XDM.
Real-Time Customer Profile : fournit un profil client en temps réel unifié basé sur des données agrégées issues de plusieurs sources.
Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance Experience Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.

Avant de commencer ce tutoriel, consultez le guide de développement pour obtenir 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 Accept et à ses valeurs possibles).

Définition d’un schéma source et de référence

Vous devez avoir déjà créé les deux schémas qui seront définis dans la relation. Ce tutoriel crée une relation entre les membres du programme de fidélité actuel d’une organisation (défini dans un schéma « Loyalty Members ») et leurs hôtels préférés (définis dans un schéma « Hotels »).

Les relations de schéma sont représentées par un schéma source dont un champ fait référence à un autre champ dans un schéma de référence. Dans les étapes qui suivent, « Loyalty Members » sera le schéma source, tandis que « Hotels » agira comme schéma de référence.

IMPORTANT

Pour établir une relation, les deux schémas doivent avoir défini des identités principales et être activés pour la Real-Time Customer Profile. Consultez la section relative à l’activation d’un schéma à utiliser dans Profile dans le tutoriel sur la création de schémas si vous avez besoin de conseils sur la configuration de 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 rechercher leurs valeurs $id en adressant une requête GET au point d’entrée /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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

NOTE

Le application/vnd.adobe.xed-id+json d’en-tête Accept renvoie uniquement les titres, les identifiants et les versions des schémas résultants.

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éfinition d’un champ de référence pour le schéma source

Dans le Schema Registry, les descripteurs de relation fonctionnent de la même manière que les clés étrangères dans les tables de la base de données relationnelle : un champ du schéma source fait office de référence au champ d’identité principale d’un schéma de référence. Si votre schéma source ne comporte pas de champ à cet effet, vous devrez peut-être créer un groupe de champs de schéma avec le nouveau champ et l’ajouter au schéma. Ce nouveau champ doit avoir une valeur type de string.

IMPORTANT

Le schéma source ne peut pas utiliser son identité principale comme champ de référence.

Dans ce tutoriel, le schéma de référence « Hotels » contient un champ hotelId qui sert d’identité principale au schéma. Cependant, le schéma source « Loyalty Members » ne dispose pas d’un champ dédié à utiliser comme référence à hotelId. Par conséquent, un groupe de champs personnalisé doit être créé pour ajouter un nouveau champ au schéma : favoriteHotel.

NOTE

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 de création d’un descripteur de référence.

Créer un groupe de champs

Pour ajouter un nouveau champ à un schéma, il doit d’abord être défini dans un groupe de champs. Vous pouvez créer un groupe de champs en effectuant une requête POST vers le point d’entrée /tenant/fieldgroups.

Format d’API

POST /tenant/fieldgroups

Requête

La requête suivante crée un groupe de champs qui ajoute 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/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"
            }
        ]
      }'

Réponse

Une réponse réussie renvoie les détails du groupe de champs nouvellement créé.

{
    "$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"
    }
}

Propriété

Description

$id

Identifiant unique, généré par le système et en lecture seule, du nouveau groupe de champs. Il prend la forme d’un URI.

Enregistrez l’URI $id du groupe de champs, qui sera utilisé à l’étape suivante de l’ajout du groupe de champs au schéma source.

Ajouter le groupe de champs au schéma source

Une fois que vous avez créé un groupe de champs, vous pouvez l’ajouter au schéma source en envoyant une requête PATCH au point d’entrée /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

La requête suivante ajoute le groupe de champs « Favorite Hotel » au schéma « 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"
      }
    }
  ]'

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 groupes de champs aux schémas, la valeur doit être « /allOf/- ».

value.$ref

$id du groupe de champs à 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 groupe de champs ajouté sous son tableau de 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": "{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="
    }
}

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

Un descripteur d’identité de référence doit être appliqué aux champs de schéma s’ils sont utilisés comme référence à un autre schéma dans une relation. Étant donné que le champ favoriteHotel dans « Loyalty Members » fait référence au champ hotelId dans « Hotels », favoriteHotel doit se voir attribuer un descripteur d’identité de référence.

Créez un descripteur de référence pour le schéma source en effectuant une requête POST vers le point d’entrée /tenant/descriptors.

Format d’API

POST /tenant/descriptors

Requête

La requête suivante crée un descripteur de référence pour le champ favoriteHotel dans le schéma source « 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"
  }'

Paramètre

Description

@type

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 source.

xdm:sourceVersion

Le numéro de version du schéma source.

sourceProperty

Chemin d’accès au champ dans le schéma source qui sera utilisé pour faire référence à l’identité principale du schéma de référence.

xdm:identityNamespace

L’espace de noms d’identité du champ de référence. Il doit s’agir du même espace de noms que l’identité principale du schéma de référence. 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 de référence nouvellement créé pour le champ source.

{
    "@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"
}

Créer un descripteur de relation

Les descripteurs de relation établissent une relation un-à-un entre un schéma source et un schéma de référence. Une fois que vous avez défini un descripteur d’identité de référence pour le champ approprié dans le schéma source, vous pouvez créer un nouveau descripteur de relation en effectuant une requête POST au point d’entrée /tenant/descriptors.

Format d’API

POST /tenant/descriptors

Requête

La requête suivante crée un descripteur de relation, avec « Loyalty Members » comme schéma source et « Hotels » comme schéma de référence.

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"
  }'

Paramètre

Description

@type

Le type de descripteur à créer. La valeur @type des descripteurs de relation est 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

URL $id du schéma de référence.

xdm:destinationVersion

Numéro de version du schéma de référence.

xdm:destinationProperty

Chemin d’accès au champ Identité principale dans le schéma de référence.

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. Pour plus d’informations sur l’utilisation des descripteurs à l’aide de l’API Schema Registry, consultez le guide de développement du registre des schémas 🔗. 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.

recommendation-more-help