Descriptors-Endpunkt
Erstellt für:
- Entwickler
Schemata definieren eine statische Ansicht von Datenentitäten, geben jedoch nicht spezifisch an, wie sich Daten, die auf diesen Schemata 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.
Mit dem /descriptors-Endpunkt in der Schema Registry-API können Sie Deskriptoren in Ihrem Erlebnisprogramm programmgesteuert verwalten.
Erste Schritte
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.
Abrufen einer Liste von Deskriptoren
Sie können alle Deskriptoren auflisten, die von Ihrem Unternehmen definiert wurden, indem Sie eine GET-Anfrage an /tenant/descriptors stellen.
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 Format der Antwort hängt von der in der Anfrage gesendeten Accept-Kopfzeile ab. Beachten Sie, dass der /descriptors-Endpunkt Accept Kopfzeilen verwendet, die sich von allen anderen Endpunkten in der Schema Registry-API unterscheiden.
IMPORTANTAccept, die xed durch xdm ersetzen, und bieten außerdem eine für Deskriptoren eindeutige link. Die richtigen Accept-Kopfzeilen wurden in die folgenden Beispielaufrufe aufgenommen, Sie müssen jedoch besonders vorsichtig sein, um sicherzustellen, dass beim Arbeiten mit Deskriptoren die richtigen Kopfzeilen verwendet werden.Accept-Kopfzeileapplication/vnd.adobe.xdm-id+jsonapplication/vnd.adobe.xdm-link+jsonapplication/vnd.adobe.xdm+jsonapplication/vnd.adobe.xdm-v2+jsonAccept-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 link Accept-Kopfzeile 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"
]
}
Deskriptor nachschlagen
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}
{DESCRIPTOR_ID}@id des Deskriptors, den Sie suchen möchten.Anfrage
Die folgende Anfrage ruft einen Deskriptor anhand seines @id ab. Deskriptoren sind nicht versioniert, daher ist in der Suchanfrage keine Accept-Kopfzeile 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"
}
Erstellen eines Deskriptors
Sie können einen neuen Deskriptor erstellen, indem Sie eine POST-Anfrage an den /tenant/descriptors-Endpunkt senden.
IMPORTANTAPI-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 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. Der @id ist ein schreibgeschütztes Feld, das vom Schema Registry zugewiesen wird und für die Referenzierung des Deskriptors 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"
}
Aktualisieren eines Deskriptors
Sie können einen Deskriptor aktualisieren, indem Sie seinen @id im Pfad einer PUT-Anfrage angeben.
API-Format
PUT /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}@id des Deskriptors, den Sie aktualisieren möchten.Anfrage
Diese Anfrage schreibt den Deskriptor im Wesentlichen neu. Daher muss der Anfragetext alle Felder enthalten, die zum Definieren eines Deskriptors dieses Typs erforderlich sind. Mit anderen Worten, die Anfrage-Payload zum Aktualisieren (PUT) eines Deskriptors ist identisch mit der Payload zum (POST) eines Deskriptors desselben Typs.
IMPORTANTIm folgenden Beispiel wird ein Identitätsdeskriptor aktualisiert, um auf einen anderen xdm:sourceProperty (mobile phone) zu verweisen und die 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: {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"
}
Wenn Sie eine Suchanfrage (GET), um den Deskriptor anzuzeigen, werden die Felder jetzt aktualisiert, damit die in der PUT-Anfrage gesendeten Änderungen widergespiegelt werden.
Löschen eines Deskriptors
Gelegentlich müssen Sie möglicherweise einen Deskriptor entfernen, den Sie aus der Schema Registry definiert haben. Dies geschieht, indem Sie eine DELETE-Anfrage stellen, die auf die @id des Deskriptors verweist, den Sie entfernen möchten.
API-Format
DELETE /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}@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 für den @id durchführen. Die Antwort gibt den HTTP-Status 404 (Nicht gefunden) zurück, da der Deskriptor aus der Schema Registry entfernt wurde.
Anhang
Der folgende Abschnitt enthält zusätzliche Informationen zum Arbeiten mit Deskriptoren in der Schema Registry-API.
Deskriptoren definieren
NOTEDie folgenden Abschnitte bieten eine Übersicht über die verfügbaren Deskriptortypen, einschließlich der erforderlichen Felder zum Definieren eines Deskriptors für die einzelnen Typen.
IMPORTANTIdentitätsdeskriptor
Ein Identitätsdeskriptor signalisiert, dass "sourceProperty" von "sourceSchema" ein Identity ist, wie vom 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
}
@typexdm:descriptorIdentity gesetzt werden.xdm:sourceSchema$id-URI des Schemas, wo der Deskriptor definiert wird.xdm:sourceVersionxdm:sourcePropertyxdm:namespaceid- oder code-Wert des Identitäts-Namespace. Eine Liste der Namespaces finden Sie unter Verwendung des Identity Service API .xdm:propertyxdm:id oder xdm:code, je nach verwendetem xdm:namespace.xdm:isPrimaryAnzeigenamendeskriptor
Mit Deskriptoren für benutzerfreundliche Namen können Benutzende die title-, description- und meta:enum der Schemafelder der Hauptbibliothek ä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"
},
"xdm:excludeMetaEnum": {
"web.formFilledOut": "Web Form Filled Out",
"media.ping": "Media ping"
}
}
@typexdm:alternateDisplayInfo gesetzt werden.xdm:sourceSchema$id-URI des Schemas, wo der Deskriptor definiert wird.xdm:sourceVersionxdm:sourceProperty/) beginnen und nicht mit einem Schrägstrich enden. Fügen Sie keine properties in den Pfad ein (verwenden Sie beispielsweise /personalEmail/address statt /properties/personalEmail/properties/address).xdm:titlexdm:descriptionmeta:enumxdm:sourceProperty angegebene Feld ein Zeichenfolgenfeld ist, kann meta:enum verwendet werden, um in der Segmentierungs-Benutzeroberfläche vorgeschlagene Werte für das Feld hinzuzufügen. Beachten Sie, dass meta:enum keine Auflistung deklariert und keine Datenvalidierung für das XDM-Feld bereitstellt.Dies sollte nur für von Adobe definierte XDM-Kernfelder verwendet werden. Wenn die Quelleigenschaft ein benutzerdefiniertes Feld ist, das von Ihrer Organisation definiert wurde, sollten Sie stattdessen die
meta:enum-Eigenschaft des Felds direkt über eine PATCH-Anfrage an die übergeordnete Ressource des Felds bearbeiten.meta:excludeMetaEnumxdm:sourceProperty angegebene Feld ein Zeichenfolgenfeld ist, das vorhandene vorgeschlagene Werte unter einem meta:enum Feld bereitgestellt hat, können Sie dieses Objekt in einen Deskriptor für benutzerfreundliche Namen aufnehmen, um einige oder alle diese Werte aus der Segmentierung auszuschließen. Schlüssel und Wert jedes Eintrags müssen mit denen übereinstimmen, die in der ursprünglichen meta:enum des Felds enthalten sind, damit der Eintrag ausgeschlossen wird.Beziehungsdeskriptor
Beziehungsdeskriptoren beschreiben eine Beziehung zwischen zwei verschiedenen Schemata. 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 Schemata.
{
"@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"
}
@typexdm:descriptorOneToOne festgelegt werden, es sei denn, Sie haben Zugriff auf Real-Time CDP B2B edition. Mit B2B edition haben Sie die Möglichkeit, xdm:descriptorOneToOne oder xdm:descriptorRelationship zu verwenden.xdm:sourceSchema$id-URI des Schemas, wo der Deskriptor definiert wird.xdm:sourceVersionxdm:sourcePropertyxdm:destinationSchema$id-URI des Referenzschemas, mit dem dieser Deskriptor eine Beziehung definiert.xdm:destinationVersionxdm:destinationPropertyB2B-Beziehungsdeskriptor
Real-Time CDP B2B edition führt eine alternative Methode zur Definition von Beziehungen zwischen Schemata ein, die Viele-zu-Eins-Beziehungen ermöglicht. Diese neue Beziehung muss den @type: xdm:descriptorRelationship aufweisen, und die Payload muss mehr Felder als die @type: xdm:descriptorOneToOne enthalten. Weitere Informationen finden Sie im Tutorial Definieren einer Schemabeziehung fürB2B edition".
{
"@type": "xdm:descriptorRelationship",
"xdm:sourceSchema" : "https://ns.adobe.com/{TENANT_ID}/schemas/9f2b2f225ac642570a110d8fd70800ac0c0573d52974fa9a",
"xdm:sourceVersion" : 1,
"xdm:sourceProperty" : "/person-ref",
"xdm:destinationSchema" : "https://ns.adobe.com/{TENANT_ID/schemas/628427680e6b09f1f5a8f63ba302ee5ce12afba8de31acd7",
"xdm:destinationVersion" : 1,
"xdm:destinationProperty": "/personId",
"xdm:destinationNamespace" : "People",
"xdm:destinationToSourceTitle" : "Opportunity Roles",
"xdm:sourceToDestinationTitle" : "People",
"xdm:cardinality": "M:1"
}
@typexdm:descriptorRelationship gesetzt werden. Weitere Informationen zu zusätzlichen Typen finden Sie AbschnittBeziehungsdeskriptoren“.xdm:sourceSchema$id-URI des Schemas, wo der Deskriptor definiert wird.xdm:sourceVersionxdm:sourcePropertyxdm:destinationSchema$id-URI des Referenzschemas, mit dem dieser Deskriptor eine Beziehung definiert.xdm:destinationVersionxdm:destinationPropertyxdm:destinationNamespacexdm:destinationToSourceTitlexdm:sourceToDestinationTitlexdm:cardinalityM:1 gesetzt werden und sich auf eine Viele-zu-eins-Beziehung beziehen.Referenzidentitätsdeskriptor
Referenz-Identitätsdeskriptoren bieten einen Referenzkontext für die primäre Identität eines Schemafelds, sodass diese von Feldern in anderen Schemata referenziert werden kann. Für das Referenzschema muss bereits ein primäres Identitätsfeld definiert sein, bevor es von anderen Schemata über diesen Deskriptor referenziert 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"
}
@typexdm:descriptorReferenceIdentity gesetzt werden.xdm:sourceSchema$id-URI des Schemas, wo der Deskriptor definiert wird.xdm:sourceVersionxdm:sourceProperty/personalEmail/address statt /properties/personalEmail/properties/address).xdm:identityNamespaceVeralteter Felddeskriptor
Sie können ein Feld in einer benutzerdefinierten XDM-Ressource verwerfen indem Sie dem betreffenden Feld ein meta:status-Attribut hinzufügen, das auf deprecated gesetzt ist. Wenn Sie Felder verwerfen möchten, die von standardmäßigen XDM-Ressourcen in Ihren Schemata bereitgestellt werden, können Sie dem betreffenden Schema jedoch einen verworfenen Felddeskriptor zuweisen, um dieselbe Wirkung zu erzielen. Mithilfe der korrekten Accept-Kopfzeile können Sie dann in der API anzeigen, welche Standardfelder für ein Schema veraltet sind.
{
"@type": "xdm:descriptorDeprecated",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/faxPhone"
}
@typexdm:descriptorDeprecated gesetzt werden.xdm:sourceSchema$id des Schemas, auf das Sie den Deskriptor anwenden.xdm:sourceVersion1 gesetzt werden.xdm:sourceProperty["/firstName", "/lastName"]).