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

Définissez une relation entre deux schémas à l’aide de la propriété Schema Registry API

Last update: Wed May 10 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Rubriques :
Schemas

Créé pour :

Developer

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

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.

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 Jeux de mappage de la préparation de données ou schémas pour connexions aux destinations.

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

Prise en main

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 son implémentation 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 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 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éfini dans un "Loyalty Members") et leurs hôtels préférés (définis dans un "Hotels").

Les relations de schéma sont représentées par une schéma source avoir un champ qui fait référence à un autre champ dans un schéma de référence. Dans les étapes suivantes, "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 Real-Time Customer Profile. Voir la section sur 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 trouver leurs valeurs $id en envoyant 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 Accept header 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 le 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 fait office de 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 comporter un type valeur 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 une 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, et 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 suivante 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 adressant une requête de POST à la fonction /tenant/fieldgroups point de terminaison .

Format d’API

POST /tenant/fieldgroups

Requête

La requête suivante crée un groupe de champs qui ajoute un favoriteHotel sous le champ _{TENANT_ID} l’espace de noms 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 la variable $id URI 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 /tenant/schemas/{SCHEMA_ID} point de terminaison .

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 caractère "Favorite Hotel" au groupe de champs "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

Le $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 variable $ref valeur du groupe de champs ajouté sous sa allOf tableau.

{
    "$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. Depuis la variable favoriteHotel champ dans "Loyalty Members" fait référence à la variable hotelId champ 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 adressant une requête de POST à la fonction /tenant/descriptors point de terminaison .

Format d’API

POST /tenant/descriptors

Requête

La requête suivante crée un descripteur de référence pour la variable favoriteHotel champ du 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 adressant une requête de POST au /tenant/descriptors point de terminaison .

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

Le $id URL 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 la variable Schema Registry API, voir 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