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, d. h. sie sind für Ihre 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.
Die /descriptors
-Endpunkt im Schema Registry Mit der API können Sie Deskriptoren in Ihrer Erlebnisanwendung programmgesteuert verwalten.
Der in diesem Handbuch verwendete Endpunkt ist Teil der Schema Registry API. Bevor Sie fortfahren, lesen Sie das Handbuch Erste Schritte mit Links zur zugehörigen Dokumentation, einer Anleitung zum Lesen der API-Beispielaufrufe in diesem Dokument und wichtigen Informationen zu den erforderlichen Kopfzeilen, die für die erfolgreiche Ausführung von Aufrufen an eine Experience Platform-API erforderlich sind.
Sie können alle von Ihrem Unternehmen definierten Deskriptoren auflisten, indem Sie eine GET-Anfrage an /tenant/descriptors
.
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xdm-link+json'
Das Antwortformat hängt von der Accept
-Kopfzeile, die in der Anfrage gesendet wird. Beachten Sie, dass /descriptors
Endpunktverwendungen Accept
Kopfzeilen, die sich von allen anderen Endpunkten im Schema Registry API.
Deskriptoren erfordern eindeutige Accept
Header, die xed
mit xdm
, und bieten auch eine link
-Option, die für Deskriptoren eindeutig ist. Die Accept
-Kopfzeilen wurden in den Beispielaufrufen unten aufgeführt. Achten Sie jedoch besonders darauf, sicherzustellen, dass beim Arbeiten mit Deskriptoren die richtigen Kopfzeilen 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 |
Diese Accept -Kopfzeile muss verwendet werden, um Paging-Funktionen nutzen zu können. |
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 von link
Accept
-Kopfzeile wird jeder Deskriptor als Array-Element im Format angezeigt /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
{
"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
Mit der folgenden Anfrage wird ein Deskriptor durch seine @id
-Wert. Deskriptoren sind nicht versioniert, daher keine Accept
-Kopfzeile ist in der Suchanfrage 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: {ORG_ID}' \
-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": "{ORG_ID}",
"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-Anfrage an die /tenant/descriptors
-Endpunkt.
Die Schema Registry ermöglicht die Definition verschiedener Deskriptortypen. Jeder Deskriptortyp erfordert eigene spezifische Felder, die im Anfragetext gesendet werden. Siehe Anhang für eine vollständige Liste der Deskriptoren und der für ihre Definition erforderlichen Felder.
API-Format
POST /tenant/descriptors
Anfrage
Die folgende Anfrage definiert einen Identitätsdeskriptor für ein Feld „E-Mail-Adresse“ in einem Beispielschema. Diese Funktion Experience Platform , um die E-Mail-Adresse als Kennung 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: {ORG_ID}' \
-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
. Die @id
ist ein schreibgeschütztes Feld, das von der Schema Registry und verwendet, um auf den Deskriptor in der API zu verweisen.
{
"@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
im Pfad einer PUT-Anfrage.
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: Die Anfrage-Payload zum Aktualisieren (PUT) eines Deskriptors entspricht der Payload zu Erstellen (POST) eines Deskriptors denselben Typ aufweisen.
Wie beim Erstellen von Deskriptoren mithilfe von POST-Anfragen erfordert jeder Deskriptortyp, dass eigene spezifische Felder in PUT-Anfrage-Payloads gesendet werden. Siehe Anhang für eine vollständige Liste der Deskriptoren und der für ihre Definition erforderlichen Felder.
Im folgenden Beispiel wird ein Identitätsdeskriptor aktualisiert, um auf eine andere xdm:sourceProperty
(mobile phone
) und ändern Sie die xdm:namespace
nach Phone
.
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: {ORG_ID}' \
-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"
}
Führen Sie eine Anfrage zum Nachschlagen (GET) um den Deskriptor anzuzeigen, wird angezeigt, dass die Felder jetzt aktualisiert wurden, um die in der PUT-Anfrage gesendeten Änderungen widerzuspiegeln.
Gelegentlich müssen Sie möglicherweise einen von Ihnen definierten Deskriptor aus der Schema Registry. 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: {ORG_ID}' \
-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
. Die Antwort gibt den HTTP-Status 404 (Nicht gefunden) zurück, da der Deskriptor aus der Schema Registry.
Im folgenden Abschnitt finden Sie zusätzliche Informationen zum Arbeiten mit Deskriptoren im 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 dersourceProperty" der "sourceSchema" ist ein Identity -Feld, beschrieben durch Adobe Experience Platform Identity Service.
{
"@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. Für einen Identitätsdeskriptor muss dieser Wert auf xdm:descriptorIdentity . |
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 Namespaces finden Sie unter Verwendung der Variablen 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 Anzeigenamendeskriptoren können Benutzer die title
, description
und meta:enum
-Werte der Schemafelder der Hauptbibliothek. 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"
},
"xdm:excludeMetaEnum": {
"web.formFilledOut": "Web Form Filled Out",
"media.ping": "Media ping"
}
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des zu definierenden Deskriptors. Bei einem Anzeigenamendeskriptor muss dieser Wert auf xdm:alternateDisplayInfo . |
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, deren Details Sie ändern möchten. Der Pfad sollte mit einem Schrägstrich (/ ) und nicht mit einer enden. Nicht einschließen properties im Pfad (verwenden Sie beispielsweise /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 |
Wenn das Feld durch xdm:sourceProperty ein Zeichenfolgenfeld ist, meta:enum kann verwendet werden, um empfohlene Werte für das Feld in der Segmentierungsbenutzeroberfläche hinzuzufügen. Es ist wichtig festzustellen, dass meta:enum deklariert keine Auflistung oder stellt keine Datenvalidierung für das XDM-Feld bereit.Dies sollte nur für von Adobe definierte Core-XDM-Felder verwendet werden. Wenn die Quelleigenschaft ein von Ihrer Organisation definiertes benutzerdefiniertes Feld ist, sollten Sie stattdessen die meta:enum -Eigenschaft direkt über eine PATCH-Anfrage an die übergeordnete Ressource des Felds. |
meta:excludeMetaEnum |
Wenn das Feld durch xdm:sourceProperty ist ein Zeichenfolgenfeld, in dem vorhandene empfohlene Werte unter einem meta:enum -Feld können Sie dieses Objekt in einen Anzeigenamendeskriptor einschließen, um einige oder alle dieser Werte aus der Segmentierung auszuschließen. Schlüssel und Wert für jeden Eintrag müssen mit denen im Original übereinstimmen meta:enum des Felds, damit der Eintrag ausgeschlossen wird. |
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. Für einen Beziehungsdeskriptor muss dieser Wert auf xdm:descriptorOneToOne . |
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 |
Die $id URI des Referenzschemas, mit dem dieser Deskriptor eine Beziehung definiert. |
xdm:destinationVersion |
Die Hauptversion des Referenzschemas. |
xdm:destinationProperty |
Optionaler Pfad zu einem Zielfeld im Referenzschema. Wenn diese Eigenschaft weggelassen wird, wird das Zielfeld von allen Feldern mit einem entsprechenden Referenzidentitätsdeskriptor abgeleitet (siehe unten). |
Referenzidentitätsdeskriptoren stellen einen Referenzkontext für die primäre Identität eines Schemafelds bereit, der es ermöglicht, von Feldern in anderen Schemas darauf zu verweisen. Das Referenzschema muss bereits über ein primäres Identitätsfeld verfügen, bevor über diesen Deskriptor andere Schemas auf dieses Feld verweisen können.
{
"@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. Für einen Referenzidentitätsdeskriptor muss dieser Wert auf xdm:descriptorReferenceIdentity . |
xdm:sourceSchema |
Der $id -URI des Schemas, wo der Deskriptor definiert wird. |
xdm:sourceVersion |
Die Hauptversion des Quellschemas. |
xdm:sourceProperty |
Pfad zum Feld im Quellschema, das zum Verweis auf das Referenzschema verwendet 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. |
Sie können Verwerfen eines Felds in einer benutzerdefinierten XDM-Ressource durch Hinzufügen eines meta:status
-Attribut auf deprecated
auf das entsprechende Feld. Wenn Sie Felder, die von standardmäßigen XDM-Ressourcen in Ihren Schemas bereitgestellt werden, veraltet sein möchten, können Sie dem betreffenden Schema jedoch einen veralteten Felddeskriptor zuweisen, um denselben Effekt zu erzielen. Verwenden der korrekt Accept
headerkönnen Sie dann anzeigen, welche Standardfelder für ein Schema nicht mehr unterstützt werden, wenn Sie es in der API nachschlagen.
{
"@type": "xdm:descriptorDeprecated",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/faxPhone"
}
Eigenschaft | Beschreibung |
---|---|
@type |
Der Typ des Deskriptors. Für einen Deskriptor zum Verwerfen von Feldern muss dieser Wert auf xdm:descriptorDeprecated gesetzt werden. |
xdm:sourceSchema |
Der URI $id des Schemas, auf das Sie den Deskriptor anwenden. |
xdm:sourceVersion |
Die Version des Schemas, auf das Sie den Deskriptor anwenden. Sollte auf 1 gesetzt werden. |
xdm:sourceProperty |
Der Pfad zur Eigenschaft innerhalb des Schemas, auf das Sie den Deskriptor anwenden. Wenn Sie den Deskriptor auf mehrere Eigenschaften anwenden möchten, können Sie eine Liste von Pfaden in Form eines Arrays bereitstellen (z. B. ["/firstName", "/lastName"] ). |