Definieren einer Beziehung zwischen zwei Schemas mithilfe der Schema Registry-API
Die Möglichkeit, Beziehungen zwischen Ihren Kunden und deren Interaktionen mit Ihrer Marke kanalübergreifend zu analysieren, ist ein wichtiger Bestandteil von Adobe Experience Platform. Durch die Definition dieser Beziehungen innerhalb der Struktur Ihrer Experience Data Model (XDM)-Schemas können Sie komplexe Einblicke in Ihre Kundendaten gewinnen.
Während Schemabeziehungen durch die Verwendung des Vereinigungsschemas und Real-Time Customer Profile abgeleitet werden können, gilt dies nur für Schemata einer gemeinsamen Klasse. Um eine Beziehung zwischen zwei Schemas herzustellen, die zu verschiedenen Klassen gehören, muss einem Quellschema ein dediziertes Beziehungsfeld hinzugefügt werden, das die Identität eines separaten Referenzschemas angibt.
Dieses Dokument enthält eine Anleitung zum Definieren einer Eins-zu-Eins-Beziehung zwischen zwei Schemas, die von Ihrer Organisation mithilfe von Schema Registry API definiert wurden.
Erste Schritte
Dieses Tutorial setzt ein Verständnis von Experience Data Model (XDM) und XDM System voraus. Bevor Sie mit dem Tutorial beginnen, lesen Sie die folgenden Dokumente:
- XDM-System in Experience Platform: Eine Übersicht über XDM und dessen Implementierung in Experience Platform.
- Grundlagen der Schemakomposition: Eine Einführung in die Bausteine von XDM-Schemata.
- Real-Time Customer Profile: Bietet ein einheitliches Echtzeit-Kundenprofil, das auf aggregierten Daten aus verschiedenen Quellen basiert.
- Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform-Instanz in separate virtuelle Umgebungen unterteilen, damit Sie Programme für digitale Erlebnisse entwickeln und weiterentwickeln können.
Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte das Entwicklerhandbuch , um wichtige Informationen zu erhalten, die Sie benötigen, um die Schema Registry -API erfolgreich aufrufen zu können. Dazu gehören Ihre {TENANT_ID}
, das Konzept der „Container“ und die erforderlichen Header für Anfragen (mit besonderem Augenmerk auf den Accept-Header und seine möglichen Werte).
Quell- und Referenzschema definieren define-schemas
Wir gehen davon aus, dass Sie die beiden Schemata, die in der Beziehung definiert werden sollen, bereits erstellt haben. In diesem Tutorial wird eine Beziehung zwischen Mitgliedern des aktuellen Treueprogramms einer Organisation (definiert in einem "Loyalty Members"-Schema) und ihren Lieblingshotels (definiert in einem "Hotels"-Schema) hergestellt.
Schemabeziehungen werden durch ein Quellschema dargestellt, das über ein Feld verfügt, das auf ein anderes Feld innerhalb eines Referenzschemas verweist. In den folgenden Schritten ist "Loyalty Members" das Quellschema, während "Hotels" als Referenzschema fungiert.
Um eine Beziehung zwischen zwei Schemata festzulegen, müssen Sie sich zunächst die $id
-Werte für beide Schemata verschaffen. Wenn Sie die Anzeigenamen (title
) der Schemas kennen, können Sie deren $id
-Werte finden, indem Sie eine GET-Anfrage an den /tenant/schemas
-Endpunkt in der Schema Registry-API richten.
API-Format
GET /tenant/schemas
Anfrage
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
gibt nur die Titel, IDs und Versionen der resultierenden Schemas zurück.Antwort
Bei einer erfolgreichen Antwort wird eine Liste der von Ihrer Organisation definierten Schemata zurückgegeben, einschließlich der Werte für name
, $id
, meta:altId
und 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"
}
}
}
Notieren Sie sich die $id
-Werte der beiden Schemata, für die Sie eine Beziehung definieren möchten. Diese Werte werden in späteren Schritten verwendet.
Referenzfeld für das Quellschema definieren
Innerhalb des Schema Registry funktionieren Beziehungsdeskriptoren ähnlich wie Fremdschlüssel in relationalen Datenbanktabellen: Ein Feld im Quellschema dient als Verweis auf das primäre Identitätsfeld eines Referenzschemas. Wenn Ihr Quellschema über kein Feld zu diesem Zweck verfügt, müssen Sie möglicherweise eine Schemafeldergruppe mit dem neuen Feld erstellen und zum Schema hinzufügen. Dieses neue Feld muss den type
-Wert string
aufweisen.
In diesem Tutorial enthält das Referenzschema "Hotels" ein Feld hotelId
, das als primäre Identität des Schemas dient. Das Quellschema "Loyalty Members" verfügt jedoch nicht über ein dediziertes Feld, das als Verweis auf hotelId
verwendet werden soll. Daher muss eine benutzerdefinierte Feldergruppe erstellt werden, um dem Schema ein neues Feld hinzuzufügen: favoriteHotel
.
Neue Feldergruppe erstellen
Um einem Schema ein neues Feld hinzuzufügen, muss es zunächst in einer Feldergruppe definiert werden. Sie können eine neue Feldergruppe erstellen, indem Sie eine POST-Anfrage an den /tenant/fieldgroups
-Endpunkt senden.
API-Format
POST /tenant/fieldgroups
Anfrage
Mit der folgenden Anfrage wird eine neue Feldergruppe erstellt, die ein favoriteHotel
-Feld unter dem Namespace _{TENANT_ID}
eines beliebigen Schemas hinzufügt, dem es hinzugefügt wird.
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"
}
]
}'
Antwort
Eine erfolgreiche Antwort gibt die Details der neu erstellten Feldergruppe zurück.
{
"$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
Notieren Sie den URI $id
der Feldergruppe, der im nächsten Schritt beim Hinzufügen der Feldergruppe zum Quellschema verwendet werden soll.
Hinzufügen der Feldergruppe zum Quellschema
Nachdem Sie eine Feldergruppe erstellt haben, können Sie sie dem Quellschema hinzufügen, indem Sie eine PATCH-Anfrage an den Endpunkt /tenant/schemas/{SCHEMA_ID}
senden.
API-Format
PATCH /tenant/schemas/{SCHEMA_ID}
{SCHEMA_ID}
$id
-URI oder meta:altId
des Quellschemas.Anfrage
Mit der folgenden Anfrage wird die Feldergruppe "Favorite Hotel" zum Schema "Loyalty Members" hinzugefügt.
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
-Vorgang.path
value.$ref
$id
der Feldergruppe, die hinzugefügt werden soll.Antwort
Eine erfolgreiche Antwort gibt die Details des aktualisierten Schemas zurück, das jetzt den $ref
-Wert der hinzugefügten Feldergruppe unter ihrem allOf
-Array enthält.
{
"$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="
}
}
Referenzidentitätsdeskriptor erstellen reference-identity
Auf Schemafelder muss ein Referenzidentitätsdeskriptor angewendet werden, wenn sie als Verweis auf ein anderes Schema in einer Beziehung verwendet werden. Da das Feld favoriteHotel
in "Loyalty Members"auf das Feld hotelId
in "Hotels" verweist, muss favoriteHotel
einen Referenzidentitätsdeskriptor erhalten.
Erstellen Sie einen Referenzdeskriptor für das Quellschema, indem Sie eine POST-Anfrage an den Endpunkt /tenant/descriptors
senden.
API-Format
POST /tenant/descriptors
Anfrage
Die folgende Anfrage erstellt einen Referenzdeskriptor für das Feld favoriteHotel
im Quellschema "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
sein.xdm:sourceSchema
$id
-URL des Quellschemas.xdm:sourceVersion
sourceProperty
xdm:identityNamespace
Antwort
Eine erfolgreiche Antwort gibt die Details des neu erstellten Referenzdeskriptors für das Quellfeld zurück.
{
"@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"
}
Beziehungsdeskriptor erstellen create-descriptor
Beziehungsdeskriptoren stellen eine Eins-zu-Eins-Beziehung zwischen einem Quellschema und einem Referenzschema her. Nachdem Sie einen Referenzidentitätsdeskriptor für das entsprechende Feld im Quellschema definiert haben, können Sie einen neuen Beziehungsdeskriptor erstellen, indem Sie eine POST-Anfrage an den /tenant/descriptors
-Endpunkt senden.
API-Format
POST /tenant/descriptors
Anfrage
Die folgende Anfrage erstellt einen neuen Beziehungsdeskriptor mit "Loyalty Members"als Quellschema und "Hotels"als Referenzschema.
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
-Wert für Beziehungsdeskriptoren lautet xdm:descriptorOneToOne
.xdm:sourceSchema
$id
-URL des Quellschemas.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
-URL des Referenzschemas.xdm:destinationVersion
xdm:destinationProperty
Antwort
Eine erfolgreiche Antwort gibt die Details des neu erstellten Beziehungsdeskriptors zurück.
{
"@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"
}
Nächste Schritte
Durch Befolgung dieses Tutorials haben Sie erfolgreich eine Eins-zu-Eins-Beziehung zwischen zwei Schemata erstellt. Weitere Informationen zum Arbeiten mit Deskriptoren mithilfe der Schema Registry-API finden Sie im Entwicklerhandbuch zur Schema Registry. Anweisungen zum Definieren von Schemabeziehungen in der Benutzeroberfläche finden Sie im Tutorial zum Definieren von Schemabeziehungen mit dem Schema-Editor.