Définissez une relation entre deux schémas à l’aide de la propriété 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. 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.
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.
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'
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
.
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
.
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"
}
}
$id
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}
{SCHEMA_ID}
$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"
}
}
]'
op
add
.path
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 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"
}'
@type
xdm:descriptorReferenceIdentity
.xdm:sourceSchema
$id
du schéma source.xdm:sourceVersion
sourceProperty
xdm:identityNamespace
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"
}'
@type
@type
des descripteurs de relation est xdm:descriptorOneToOne
.xdm:sourceSchema
$id
du schéma source.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
URL du schéma de référence.xdm:destinationVersion
xdm:destinationProperty
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.