Schemas definieren eine statische Ansicht von Datenentitäten, geben jedoch nicht spezifisch an, wie sich Daten, die auf diesen Schemas basieren (z. B. Datensätze), zueinander verhalten. Mit Adobe Experience Platform können Sie diese Beziehungen und andere interpretative Metadaten über ein Schema mithilfe von Deskriptoren beschreiben.
Schemadeskriptoren sind Metadaten auf Mandantenebene, das heißt, sie sind für Ihre IMS-Organisation eindeutig und alle Deskriptorvorgänge finden im Mandanten-Container statt.
Auf jedes Schema können eine oder mehrere Schemadeskriptorentitäten angewendet werden. Jede Schemadeskriptorentität enthält einen Deskriptor @type
und das sourceSchema
, auf das er angewendet wird. Nach der Anwendung gelten diese Deskriptoren für alle mit dem Schema erstellten Datensätze.
Mit dem /descriptors
-Endpunkt in der Schema Registry-API können Sie Deskriptoren in Ihrer Experience-Anwendung programmgesteuert verwalten.
Der in diesem Handbuch verwendete Endpunkt ist Teil der Schema Registry API. Bevor Sie fortfahren, lesen Sie bitte im Handbuch Erste Schritte nach Links zu entsprechenden Dokumentationen, einem Leitfaden zum Lesen der Beispiel-API-Aufrufe in diesem Dokument und wichtigen Informationen zu erforderlichen Kopfzeilen, die zum erfolgreichen Aufrufen einer Experience Platformen-API benötigt werden.
Sie können alle Deskriptoren, die von Ihrem Unternehmen definiert wurden, durch eine GET an /tenant/descriptors
Liste haben.
API-Format
GET /tenant/descriptors
Anfrage
curl -X GET \
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xdm-link+json'
Das Antwortformat hängt von der Accept
-Kopfzeile ab, die in der Anforderung gesendet wird. Beachten Sie, dass der /descriptors
-Endpunkt Accept
-Kopfzeilen verwendet, die sich von allen anderen Endpunkten in der Schema Registry-API unterscheiden.
Für Deskriptoren sind eindeutige Accept
-Kopfzeilen erforderlich, die xed
durch xdm
ersetzen, sowie eine link
-Option, die für Deskriptoren eindeutig ist, Angebot. Die korrekten Accept
-Header wurden in den Beispielaufrufen unten aufgeführt. Achten Sie jedoch besonders darauf, dass beim Arbeiten mit Deskriptoren die richtigen Header verwendet werden.
Accept -Kopfzeile |
Beschreibung |
---|---|
application/vnd.adobe.xdm-id+json |
Gibt ein Array mit Deskriptorkennungen zurück |
application/vnd.adobe.xdm-link+json |
Gibt ein Array mit Deskriptor-API-Pfaden zurück |
application/vnd.adobe.xdm+json |
Gibt ein Array mit erweiterten Deskriptorobjekten zurück |
application/vnd.adobe.xdm-v2+json |
Dieser Accept -Header muss verwendet werden, um Paging-Funktionen zu nutzen. |
Antwort
Die Antwort enthält ein Array für jeden Deskriptortyp, der über definierte Deskriptoren verfügt. Wenn keine Deskriptoren eines bestimmten @type
definiert sind, gibt die Registrierung also kein leeres Array für diesen Deskriptortyp zurück.
Bei Verwendung der Überschrift link
Accept
wird jeder Deskriptor als Array-Element im Format /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
angezeigt
{
"xdm:alternateDisplayInfo": [
"/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
"/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
"/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
],
"xdm:descriptorIdentity": [
"/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
],
"xdm:descriptorOneToOne": [
"/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
]
}
Wenn Sie die Details eines bestimmten Deskriptors anzeigen möchten, können Sie einen einzelnen Deskriptor mit dessen @id
nachschlagen (GET).
API-Format
GET /tenant/descriptors/{DESCRIPTOR_ID}
Parameter | Beschreibung |
---|---|
{DESCRIPTOR_ID} |
Die @id des Deskriptors, den Sie nachschlagen möchten. |
Anfrage
Die folgende Anforderung ruft einen Deskriptor mit dem Wert @id
ab. Deskriptoren sind nicht versioniert. Daher ist in der Suchanfrage kein Accept
-Header erforderlich.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt die Details des Deskriptors zurück, einschließlich des zugehörigen @type
und sourceSchema
sowie zusätzlicher Informationen, die je nach Deskriptortyp variieren. Die zurückgegebene @id
sollte mit der in der Anfrage angegebenen @id
des Deskriptors übereinstimmen.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"createdUser": "{CREATED_USER}",
"imsOrg": "{IMS_ORG}",
"createdClient": "{CREATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"created": 1548899346989,
"updated": 1548899346989,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Sie können einen neuen Deskriptor erstellen, indem Sie eine POST an den /tenant/descriptors
-Endpunkt anfordern.
Mit Schema Registry können Sie verschiedene Deskriptortypen definieren. Jeder Deskriptortyp erfordert, dass seine eigenen spezifischen Felder im Anforderungstext gesendet werden. Eine vollständige Liste der Deskriptoren und der zu ihrer Definition erforderlichen Felder finden Sie im Anhang Anhang.
API-Format
POST /tenant/descriptors
Anfrage
Die folgende Anfrage definiert einen Identitätsdeskriptor für ein Feld „E-Mail-Adresse“ in einem Beispielschema. Dadurch wird Experience Platform angewiesen, die E-Mail-Adresse als ID zu verwenden, um Informationen über die Person zusammenzufügen.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 201 (Erstellt) und die Details des neu erstellten Deskriptors zurück, einschließlich dessen @id
. Das @id
ist ein schreibgeschütztes Feld, das vom Schema Registry zugewiesen wird und zum Verweisen auf den Deskriptor in der API verwendet wird.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Sie können einen Deskriptor aktualisieren, indem Sie dessen @id
in den Pfad einer PUT-Anforderung einschließen.
API-Format
PUT /tenant/descriptors/{DESCRIPTOR_ID}
Parameter | Beschreibung |
---|---|
{DESCRIPTOR_ID} |
Die @id des Deskriptors, den Sie aktualisieren möchten. |
Anfrage
Bei dieser Anfrage wird der Deskriptor im Grunde neu geschrieben, sodass der Anfragetext alle Felder enthalten muss, die zur Definition eines Deskriptors dieses Typs erforderlich sind. Anders ausgedrückt, ist die Anforderungs-Nutzlast zum Aktualisieren (PUT) eines Deskriptors mit der Nutzlast von create (POST) a descriptor desselben Typs identisch.
Ebenso wie beim Erstellen von Deskriptoren mithilfe von POST-Anforderungen erfordert jeder Deskriptortyp, dass seine eigenen spezifischen Felder in PUT-Anforderungs-Nutzlasten gesendet werden. Eine vollständige Liste der Deskriptoren und der zu ihrer Definition erforderlichen Felder finden Sie im Anhang Anhang.
Im folgenden Beispiel wird ein Identitätsdeskriptor aktualisiert, um auf ein anderes xdm:sourceProperty
(mobile phone
) zu verweisen und das xdm:namespace
in Phone
zu ändern.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/mobilePhone/number",
"xdm:namespace": "Phone",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Antwort
Bei einer erfolgreichen Antwort werden der HTTP-Status 201 (Erstellt) und die @id
des aktualisierten Deskriptors zurückgegeben (sie sollte mit der in der Anfrage gesendeten @id
übereinstimmen).
{
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Gelegentlich müssen Sie möglicherweise einen von Ihnen definierten Deskriptor aus dem Schema Registry entfernen. Dies erfolgt durch eine DELETE-Anfrage, die auf die @id
des zu entfernenden Deskriptors verweist.
API-Format
DELETE /tenant/descriptors/{DESCRIPTOR_ID}
Parameter | Beschreibung |
---|---|
{DESCRIPTOR_ID} |
Die @id des Deskriptors, den Sie löschen möchten. |
Anfrage
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 204 (Kein Inhalt) und leeren Text zurück.
Um zu bestätigen, dass der Deskriptor gelöscht wurde, können Sie eine Suchanfrage gegen den Deskriptor @id
durchführen. Die Antwort gibt den HTTP-Status 404 (Nicht gefunden) zurück, da der Deskriptor aus dem Schema Registry entfernt wurde.
Im folgenden Abschnitt finden Sie weitere Informationen zum Arbeiten mit Deskriptoren in der Schema Registry-API.
Die folgenden Abschnitte bieten eine Übersicht über die verfügbaren Deskriptortypen, einschließlich der erforderlichen Felder zum Definieren eines Deskriptors für die einzelnen Typen.
Ein Identitätsdeskriptor signalisiert, dass das Feld "sourceProperty"von "sourceSchema"ein Identity-Feld ist, wie unter Adobe Experience Platform Identity Service beschrieben.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des zu definierenden Deskriptors. |
xdm:sourceSchema |
Der $id -URI des Schemas, wo der Deskriptor definiert wird. |
xdm:sourceVersion |
Die Hauptversion des Quellschemas. |
xdm:sourceProperty |
Der Pfad zur spezifischen Eigenschaft, die die Identität sein wird. Der Pfad sollte mit einem „/“ beginnen und nicht mit einem enden. Schließen Sie „properties“ nicht in den Pfad ein (verwenden Sie z. B. „/personalEmail/address“ anstelle von „/properties/personalEmail/properties/address“). |
xdm:namespace |
Der id - oder code -Wert des Identitäts-Namespace. Eine Liste von Namensräumen finden Sie mit Identity Service API. |
xdm:property |
Entweder xdm:id oder xdm:code , je nach verwendetem xdm:namespace . |
xdm:isPrimary |
Ein optionaler boolescher Wert. Wenn „true“, wird das Feld als primäre Identität angezeigt. Schemas dürfen nur eine primäre Identität enthalten. |
Mit benutzerfreundlichen Namensdeskriptoren können Sie die Werte title
, description
und meta:enum
der Core Library Schema-Felder ändern. Besonders nützlich sind sie bei der Arbeit mit „eVars“ und anderen „generischen“ Feldern, um Felder zu kennzeichnen, die organisationsspezifische Daten enthalten. Die Benutzeroberfläche kann so einen benutzerfreundlicheren Namen anzeigen oder nur Felder mit einem Anzeigenamen anzeigen.
{
"@type": "xdm:alternateDisplayInfo",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/xdm:eventType",
"xdm:title": {
"en_us": "Event Type"
},
"xdm:description": {
"en_us": "The type of experience event detected by the system."
},
"meta:enum": {
"click": "Mouse Click",
"addCart": "Add to Cart",
"checkout": "Cart Checkout"
}
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des zu definierenden Deskriptors. |
xdm:sourceSchema |
Der $id -URI des Schemas, wo der Deskriptor definiert wird. |
xdm:sourceVersion |
Die Hauptversion des Quellschemas. |
xdm:sourceProperty |
Der Pfad zur spezifischen Eigenschaft, die die Identität sein wird. Der Pfad sollte mit einem „/“ beginnen und nicht mit einem enden. Schließen Sie „properties“ nicht in den Pfad ein (verwenden Sie z. B. „/personalEmail/address“ anstelle von „/properties/personalEmail/properties/address“). |
xdm:title |
Der neue Titel, den Sie für dieses Feld anzeigen möchten, geschrieben mit großem Anfangsbuchstaben. |
xdm:description |
Zusammen mit dem Titel kann eine optionale Beschreibung hinzugefügt werden. |
meta:enum |
Ist das von xdm:sourceProperty angegebene Feld ein Zeichenfolgenfeld, bestimmt meta:enum die Liste der vorgeschlagenen Werte für das Feld in der Benutzeroberfläche Experience Platform. Beachten Sie, dass meta:enum keine Auflistung deklariert oder eine Datenvalidierung für das XDM-Feld bereitstellt.Dies sollte nur für Kern-XDM-Felder verwendet werden, die von der Adobe definiert werden. Wenn die source-Eigenschaft ein benutzerdefiniertes Feld ist, das von Ihrem Unternehmen definiert wird, sollten Sie stattdessen die meta:enum -Eigenschaft des Felds direkt über eine PATCH-Anforderung an die übergeordnete Ressource des Felds bearbeiten. |
Beziehungsdeskriptoren beschreiben eine Beziehung zwischen zwei verschiedenen Schemas. Sie werden in die Eigenschaften eingegeben, die in sourceProperty
und destinationProperty
beschrieben werden. Weiterführende Informationen finden Sie in der Anleitung zum Definieren einer Beziehung zwischen zwei Schemas.
{
"@type": "xdm:descriptorOneToOne",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:destinationSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:destinationVersion": 1,
"xdm:destinationProperty": "/parentField/subField"
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des zu definierenden Deskriptors. |
xdm:sourceSchema |
Der $id -URI des Schemas, wo der Deskriptor definiert wird. |
xdm:sourceVersion |
Die Hauptversion des Quellschemas. |
xdm:sourceProperty |
Der Pfad zum Feld im Quellschema, in dem die Beziehung definiert wird. Sollte mit einem „/“ beginnen und nicht mit einem solchen enden. Schließen Sie „properties“ nicht in den Pfad ein (z. B. „/personalEmail/address“ anstelle von „/properties/personalEmail/properties/address“). |
xdm:destinationSchema |
Der $id -URI des Zielschemas, mit dem dieser Deskriptor eine Beziehung definiert. |
xdm:destinationVersion |
Die Hauptversion des Zielschemas. |
xdm:destinationProperty |
Optionaler Pfad zu einem Zielfeld im Zielschema. Wenn diese Eigenschaft weggelassen wird, wird das Zielfeld von allen Feldern mit einem entsprechenden Referenzidentitätsdeskriptor abgeleitet (siehe unten). |
Referenz-Identitätsdeskriptoren stellen einen Referenzkontext zur primären Identität eines Schema-Felds bereit, sodass auf dieses durch Felder in anderen Schemas verwiesen werden kann. Felder müssen bereits mit einem Identitätsdeskriptor gekennzeichnet sein, bevor ein Referenzdeskriptor auf sie angewendet werden kann.
{
"@type": "xdm:descriptorReferenceIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:identityNamespace": "Email"
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des zu definierenden Deskriptors. |
xdm:sourceSchema |
Der $id -URI des Schemas, wo der Deskriptor definiert wird. |
xdm:sourceVersion |
Die Hauptversion des Quellschemas. |
xdm:sourceProperty |
Der Pfad zum Feld im Quellschema, in dem der Deskriptor definiert wird. Sollte mit einem „/“ beginnen und nicht mit einem solchen enden. Schließen Sie „properties“ nicht in den Pfad ein (z. B. „/personalEmail/address“ anstelle von „/properties/personalEmail/properties/address“). |
xdm:identityNamespace |
Der Identitäts-Namespace-Code für die Quelleigenschaft. |