Descriptors-Endpunkt

Schemata definieren die Struktur von Datenentitäten, aber geben nicht an, wie sich Datensätze, die aus diesen Schemata erstellt wurden, zueinander verhalten. In Adobe Experience Platform können Sie Deskriptoren verwenden, um diese Beziehungen zu beschreiben und einem Schema interpretierende Metadaten hinzuzufügen.

Deskriptoren sind Metadatenobjekte auf Mandantenebene, die auf Schemata in Adobe Experience Platform angewendet werden. Sie definieren strukturelle Beziehungen, Schlüssel und Verhaltensfelder (wie Zeitstempel oder Versionierung), die beeinflussen, wie Daten nachgelagert validiert, verbunden oder interpretiert werden.

Ein Schema kann einen oder mehrere Deskriptoren aufweisen. Jeder Deskriptor definiert einen @type und die sourceSchema, für die er gilt. Der Deskriptor gilt automatisch für alle Datensätze, die aus diesem Schema erstellt wurden.

In Adobe Experience Platform ist ein Deskriptor Metadaten, die einem Schema Verhaltensregeln oder eine strukturelle Bedeutung hinzufügen.
Es gibt verschiedene Arten von Deskriptoren, darunter:

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.

Zusätzlich zu Standarddeskriptoren unterstützt der Schema Registry Deskriptortypen für modellbasierte Schemata wie Primärschlüssel, Version und Zeitstempel. Diese erzwingen Eindeutigkeit, steuern die Versionierung und definieren Zeitreihenfelder auf Schemaebene. Wenn Sie nicht mit modellbasierten Schemata vertraut sind, lesen Sie die technische Referenz zu Data Mirror und modellbasierten Schemata bevor Sie fortfahren.

Abrufen einer Liste von Deskriptoren list

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.

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 lookup

Um die Details eines bestimmten Deskriptors anzuzeigen, senden Sie eine GET-Anfrage über die @id .

API-Format

GET /tenant/descriptors/{DESCRIPTOR_ID}

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 create

Sie können einen neuen Deskriptor erstellen, indem Sie eine POST-Anfrage an den /tenant/descriptors-Endpunkt senden.

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 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 put

Sie können einen Deskriptor aktualisieren, indem Sie seinen @id im Pfad einer PUT-Anfrage angeben.

API-Format

PUT /tenant/descriptors/{DESCRIPTOR_ID}

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.

Im 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 delete

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}

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 appendix

Der folgende Abschnitt enthält zusätzliche Informationen zum Arbeiten mit Deskriptoren in der Schema Registry-API.

Deskriptoren definieren defining-descriptors

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.

Identitätsdeskriptor identity-descriptor

Ein Identitätsdeskriptor signalisiert, dass "sourceProperty" von "sourceSchema" ein Identity ist, wie vom 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
}

Anzeigenamendeskriptor friendly-name

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"
  }
}

Beziehungsdeskriptor relationship-descriptor

Beziehungsdeskriptoren beschreiben eine Beziehung zwischen zwei verschiedenen Schemata. Sie werden in die Eigenschaften eingegeben, die in xdm:sourceProperty und xdm:destinationProperty beschrieben werden. Weiterführende Informationen finden Sie in der Anleitung zum Definieren einer Beziehung zwischen zwei Schemata.

Verwenden Sie diese Eigenschaften, um zu deklarieren, wie sich ein Quellfeld (Fremdschlüssel) auf ein Zielfeld (Primärschlüssel oder Kandidatenschlüssel) bezieht.

Die -API unterstützt zwei Muster:

Eins-zu-eins-Beziehung (Standardschemata)

Verwenden Sie diese Option, wenn Sie vorhandene Standardschemaintegrationen beibehalten möchten, die bereits auf xdm:descriptorOneToOne basieren.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

In der folgenden Tabelle werden die Felder beschrieben, die zum Definieren eines Eins-zu-eins-Beziehungsdeskriptors erforderlich sind.

Allgemeine Beziehung (modellbasierte Schemata und empfohlen für neue Projekte)

Verwenden Sie diesen Deskriptor für alle neuen Implementierungen und für modellbasierte Schemata. Damit können Sie die Kardinalität der Beziehung definieren (z. B. Eins-zu-eins oder Viele-zu-eins), Beziehungsnamen angeben und eine Verknüpfung zu einem Zielfeld erstellen, das nicht der Primärschlüssel ist (Nicht-Primärschlüssel).

Die folgenden Beispiele zeigen, wie Sie einen allgemeinen Beziehungsdeskriptor definieren.

Minimales Beispiel:

Dieses minimale Beispiel enthält nur die erforderlichen Felder, um eine Viele-zu-eins-Beziehung zwischen zwei Schemata zu definieren.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceProperty": "/customer_ref",
  "xdm:sourceVersion": 1,
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:cardinality": "M:1"
}

Beispiel mit allen optionalen Feldern:

Dieses Beispiel enthält alle optionalen Felder, z. B. Beziehungsnamen, Anzeigetitel und ein explizites Zielfeld für einen nicht-Primärschlüssel.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/customer_ref",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationProperty": "/customer_id",
  "xdm:sourceToDestinationName": "CampaignToCustomer",
  "xdm:destinationToSourceName": "CustomerToCampaign",
  "xdm:sourceToDestinationTitle": "Customer campaigns",
  "xdm:destinationToSourceTitle": "Campaign customers",
  "xdm:cardinality": "M:1"
}

Auswahl eines Beziehungsdeskriptors

Verwenden Sie die folgenden Richtlinien, um zu entscheiden, welcher Beziehungsdeskriptor angewendet werden soll:

Vergleich der Funktionen

In der folgenden Tabelle werden die Funktionen der beiden Deskriptortypen verglichen:

Einschränkungen und Validierung

Befolgen Sie beim Definieren eines allgemeinen Beziehungsdeskriptors diese Anforderungen und Empfehlungen:

Primärer Schlüsseldeskriptor primary-key-descriptor

Der Primärschlüsseldeskriptor (xdm:descriptorPrimaryKey) erzwingt Einschränkungen hinsichtlich Eindeutigkeit und Nicht-Null für ein oder mehrere Felder in einem Schema.

{
  "@type": "xdm:descriptorPrimaryKey",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": ["/orderId", "/orderLineId"]
}

Versionsdeskriptor version-descriptor

Der Versionsdeskriptor (xdm:descriptorVersion) bezeichnet ein Feld, um Konflikte durch Änderungsereignisse zu erkennen und zu verhindern, die nicht in der richtigen Reihenfolge auftreten.

{
  "@type": "xdm:descriptorVersion",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/versionNumber"
}

Zeitstempel-Deskriptor timestamp-descriptor

Der Zeitstempeldeskriptor (xdm:descriptorTimestamp) bezeichnet ein Datums-/Uhrzeitfeld als Zeitstempel für Schemata mit "meta:behaviorType": "time-series".

{
  "@type": "xdm:descriptorTimestamp",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/eventTime"
}

B2B-Beziehungsdeskriptor B2B-relationship-descriptor

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"
}

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"
}

Veralteter 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"
}