Erste Schritte mit der Schema Registry-API

Mit der API Schema Registry können Sie verschiedene XDM-Ressourcen (Experience-Datenmodell) erstellen und verwalten. In diesem Dokument erhalten Sie eine Einführung in die wichtigsten Konzepte, die Sie kennen sollten, bevor Sie Aufrufe an die Schema Registry-API durchführen.

Voraussetzungen

Die Verwendung des Entwicklerhandbuchs setzt ein Verständnis der folgenden Komponenten von Adobe Experience Platform voraus:

XDM verwendet die JSON-Schema-Formatierung, um die Struktur der erfassten Kundenerlebnisdaten zu beschreiben und zu validieren. Es wird daher dringend empfohlen, die offizielle JSON-Schema-Dokumentation zu lesen, um ein besseres Verständnis dieser zugrunde liegenden Technologie zu erhalten.

Lesen von Beispiel-API-Aufrufen

In der Dokumentation der Schema Registry-API wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Handbuch zur Fehlerbehebung für Experience Platform.

Sammeln von Werten für erforderliche Kopfzeilen

Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Alle Ressourcen in Experience Platform, einschließlich der Ressourcen, die zu Schema Registry gehören, werden in bestimmte virtuelle Sandboxes isoliert. Bei allen Anfragen an Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

Für alle Nachschlageanfragen (GET) an Schema Registry ist eine zusätzliche Accept -Kopfzeile erforderlich, deren Wert das Format der von der API zurückgegebenen Informationen bestimmt. Weitere Informationen finden Sie unten im Abschnitt Accept-Kopfzeile.

Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile erforderlich:

Ihre TENANT_ID kennen know-your-tenant_id

In den API-Handbüchern finden Sie Verweise auf eine TENANT_ID. Diese ID wird verwendet, um sicherzustellen, dass von Ihnen erstellte Ressourcen ordnungsgemäß benannt werden und in Ihrem Unternehmen enthalten sind. Wenn Sie Ihre ID nicht kennen, können Sie sie mit der folgenden GET-Anfrage abrufen:

API-Format

GET /stats

Anfrage

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/stats \
  -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

Bei einer erfolgreichen Antwort werden Informationen zur Verwendung des Schema Registry durch Ihr Unternehmen zurückgegeben. Dies beinhaltet ein tenantId-Attribut, dessen Wert Ihre TENANT_ID ist.

{
  "imsOrg":"{ORG_ID}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
      "title": "Tenant Class",
      "description": "Tenant Defined Class",
      "meta:resourceType": "classes",
      "meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
      "version": "1.0"
    }
  ],
  "recentlyUpdatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "title": "Data Schema",
      "description": "Schema for Data Information",
      "meta:resourceType": "schemas",
      "meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
      "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
      "meta:classTitle": "Sample Class",
      "version": "1.1"
    }
 ],
 "classUsage": {
    "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "title": "Tenant Data Schema",
        "description": "Schema for tenant-specific data."
      }
    ],
    "https://ns.adobe.com/xdm/context/profile": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
        "title": "Simple Profile",
        "description": "A simple profile schema."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "title": "Program Schema",
        "description": "Schema for program-related data."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
        "title": "Sample Schema",
        "description": "A sample schema."
      }
    ]
  }
 }

Erläuterung der CONTAINER_ID container

Für Aufrufe der Schema Registry -API muss ein CONTAINER_ID verwendet werden. Es gibt zwei Container, für die API-Aufrufe durchgeführt werden können: den global -Container und den tenant -Container.

Globaler Container

Der global -Container enthält alle vom Partner bereitgestellten Standardklassen, Schemafeldgruppen, Datentypen und Schemas, die vom Adobe und von Experience Platform -Partner bereitgestellt werden. Sie dürfen nur Listen- und Suchanfragen (GET) für den global -Container ausführen.

Ein Beispiel für einen Aufruf, der den global -Container verwendet, würde wie folgt aussehen:

GET /global/classes

Mandanten-Container

Der tenant -Container ist nicht mit Ihrem eindeutigen TENANT_ID zu verwechseln. Er enthält alle Klassen, Feldgruppen, Datentypen, Schemas und Deskriptoren, die von einer Organisation definiert wurden. Diese sind für jede Organisation eindeutig, d. h. sie sind für andere Organisationen nicht sichtbar oder verwaltbar. Sie können alle CRUD-Vorgänge (GET, POST, PUT, PATCH, DELETE) für Ressourcen ausführen, die Sie im tenant -Container erstellen.

Ein Beispiel für einen Aufruf, der den tenant -Container verwendet, würde wie folgt aussehen:

POST /tenant/fieldgroups

Wenn Sie eine Klasse, Feldergruppe, ein Schema oder einen Datentyp im tenant -Container erstellen, wird diese® im Schema Registry-Container gespeichert und ihr $id -URI zugewiesen, der Ihre TENANT_ID enthält. Diese $id wird in der gesamten API verwendet, um auf bestimmte Ressourcen zu verweisen. Beispiele für Werte der $id finden Sie im nächsten Abschnitt.

Ressourcenidentifizierung resource-identification

XDM-Ressourcen werden mit einem $id -Attribut in Form eines URI identifiziert, z. B. die folgenden Beispiele:

Um den URI REST-freundlicher zu gestalten, verfügen Schemata auch über eine Punktnotationskodierung des URI in einer Eigenschaft mit der Bezeichnung meta:altId:

Aufrufe der API Schema Registry unterstützen entweder den URL-kodierten URI $id oder den URI meta:altId (Punktnotationsformat). Es empfiehlt sich, den URL-kodierten $id-URI zu verwenden, wenn Sie einen REST-Aufruf an die API ausführen, wie z. B.:

Accept-Kopfzeile accept

Bei der Ausführung von Listen- und Lookup-Vorgängen (GET) in der Schema Registry-API ist ein Accept -Header erforderlich, um das Format der von der API zurückgegebenen Daten zu bestimmen. Bei der Suche nach bestimmten Ressourcen muss auch eine Versionsnummer in der Kopfzeile Accept enthalten sein.

In der folgenden Tabelle sind kompatible Accept -Kopfzeilenwerte aufgeführt, einschließlich solcher mit Versionsnummern, sowie Beschreibungen dessen, was die API zurückgibt, wenn sie verwendet werden.

Schemaversionierung versioning

Schemaversionen werden durch Accept -Kopfzeilen in der Schema Registry-API und in den schemaRef.contentType -Eigenschaften in nachgelagerten Platform-Dienst-API-Payloads referenziert.

Derzeit unterstützt Platform nur eine einzelne Hauptversion (1) für jedes Schema. Gemäß den Regeln der Schemaentwicklung muss jede Aktualisierung eines Schemas zerstörungsfrei sein, d. h. neue Nebenversionen eines Schemas (1.2, 1.3 usw.) sind immer abwärtskompatibel mit früheren Nebenversionen. Daher gibt die Schema Registry bei Angabe von version=1 immer die neueste Hauptversion 1 eines Schemas zurück, was bedeutet, dass frühere Nebenversionen nicht zurückgegeben werden.

XDM-Feldbeschränkungen und Best Practices

Die Felder eines Schemas werden innerhalb seines properties-Objekts aufgelistet. Jedes Feld ist selbst ein Objekt, das Attribute zur Beschreibung und Einschränkung der Daten enthält, die das Feld enthalten kann. Codebeispiele und optionale Einschränkungen für die am häufigsten verwendeten Datentypen finden Sie im Handbuch Definieren benutzerdefinierter Felder in der API .

Das folgende Beispielfeld veranschaulicht ein korrekt formatiertes XDM-Feld, wobei weitere Einzelheiten zu den Benennungsbeschränkungen und Best Practices weiter unten aufgeführt sind. Diese Verfahren können auch bei der Definition anderer Ressourcen angewendet werden, die ähnliche Attribute enthalten.

"fieldName": {
    "title": "Field Name",
    "type": "string",
    "format": "date-time",
    "examples": [
        "2004-10-23T12:00:00-06:00"
    ],
    "description": "Full sentence describing the field, using proper grammar and punctuation.",
}

Nächste Schritte

Um mit dem Aufrufen der Schema Registry-API zu beginnen, wählen Sie eines der verfügbaren Handbücher zu Endpunkten.