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

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

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

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 au sein de 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 ensembles de mappages de préparation de données ou les schémas pour les connexions de destination.

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

Commencer

Ce tutoriel nécessite une compréhension pratique 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.
- 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 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 des 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 define-schemas

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éfinis 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 ayant un champ qui 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" servira de schéma de référence.

IMPORTANT

Pour établir une relation, les deux schémas doivent avoir défini des identités primaires et être activés pour Real-Time Customer Profile. Consultez la section Activation d’un schéma à utiliser dans Profile dans le tutoriel de création de schéma 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 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

NOTE

L'en-tête Accept application/vnd.adobe.xed-id+json renvoie uniquement les titres, les identifiants et les versions des schémas obtenus.

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 Schema Registry, les descripteurs de relation fonctionnent de la même manière que les clés étrangères dans les tables de base de données relationnelle : un champ du schéma source agit comme une référence au champ d’identité principal d’un schéma de référence. Si votre schéma source n’a pas de champ prévu à 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 du schéma. Cependant, le schéma source "Loyalty Members" ne possède pas de 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 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 envoyant une requête de POST au point de terminaison /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 nouveau groupe de champs 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 à utiliser à 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 de 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

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 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 reference-identity

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. Puisque le champ favoriteHotel dans "Loyalty Members" fait référence au champ hotelId dans "Hotels", favoriteHotel doit recevoir un descripteur d’identité de référence.

Créez un descripteur de référence pour le schéma source en envoyant une requête de POST au point de terminaison /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

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

xdm:sourceVersion

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

sourceProperty

Le 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 nouveau descripteur de référence 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éation d’un descripteur de relation create-descriptor

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 descripteur de relation en envoyant une requête de POST au point de terminaison /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

Le 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

Le chemin d’accès au champ d’identité principal 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

62e9ffd9-1c74-4cef-8f47-0d00af32fc07