Erste Schritte mit Adobe Experience Platform-APIs

Adobe Experience Platform wird im Rahmen einer „API First“-Philosophie entwickelt. Mithilfe von Platform-APIs können Sie programmgesteuert grundlegende CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren, Löschen) für Daten durchführen, z. B. die Konfiguration berechneter Attribute, den Zugriff auf Daten/Entitäten, den Export von Daten, das Löschen nicht benötigter Daten oder Batches und mehr.

Die APIs für jeden Experience Platform-Service verwenden alle denselben Satz an Authentifizierungs-Headern und verwenden ähnliche Syntaxen für ihre CRUD-Vorgänge. Im folgenden Handbuch werden die erforderlichen Schritte für die ersten Schritte mit Platform-APIs beschrieben.

Authentifizierung und Header

Um Platform-Endpunkte erfolgreich aufzurufen, müssen Sie das Authentifizierungs-Tutorial“. Im Rahmen des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Kopfzeilen in Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Sandbox-Kopfzeile

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Für Anfragen an Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

Weitere Informationen zu Sandboxes in Platform finden Sie in der Sandbox-Übersichtsdokumentation.

Inhaltstyp-Kopfzeile

Alle Anfragen mit einer Payload im Anfragetext (wie POST-, PUT- und PATCH-Aufrufe) müssen eine Content-Type-Kopfzeile enthalten. Akzeptierte Werte sind für jeden API-Endpunkt spezifisch. Wenn ein bestimmter Content-Type für einen Endpunkt benötigt wird, wird sein Wert in den Beispiel-API-Anfragen angezeigt, die von den API-Handbüchern für einzelne Platform-Services)werden.

Experience Platform API-Grundlagen

Adobe Experience Platform-APIs verwenden verschiedene zugrunde liegende Technologien und Syntaxen, die für die effektive Verwaltung von Platform-Ressourcen wichtig sind.

Weitere Informationen zu den zugrunde liegenden API-Technologien, die Platform verwendet, einschließlich Beispiel-JSON-Schemaobjekten, finden Sie im Handbuch Grundlagen der Experience Platform-API.

Postman-Sammlungen für Experience Platform-APIs

Postman ist eine Kollaborationsplattform für die API-Entwicklung, mit der Sie Umgebungen mit voreingestellten Variablen einrichten, API-Sammlungen freigeben, CRUD-Anfragen optimieren und vieles mehr. Die meisten Platform-API-Services verfügen über Postman-Sammlungen, die Sie bei API-Aufrufen unterstützen können.

Weitere Informationen zu Postman, einschließlich der Einrichtung einer Umgebung, einer Liste der verfügbaren Sammlungen und des Imports von Sammlungen, finden Sie in der Platform Postman-Dokumentation.

Lesen von Beispiel-API-Aufrufen sample-api

Anfrageformate variieren je nach der verwendeten Platform-API. Am einfachsten erfahren Sie, wie Sie API-Aufrufe strukturieren können, indem Sie sich die in der Dokumentation die für einzelne Platform-Dienste angegebenen Beispiele ansehen.

Die Dokumentation für Experience Platform zeigt Beispiel-API-Aufrufe auf zwei verschiedene Arten. Zunächst wird der Aufruf im API-Format dargestellt, wobei es sich um eine Vorlagendarstellung handelt, die nur den Vorgang (GET, POST, PUT, PATCH, DELETE) und den verwendeten Endpunkt (z. B. /global/classes) zeigt. Manche Vorlagen zeigen auch die Stelle von Variablen an, um zu veranschaulichen, wie ein Aufruf formuliert werden sollte, z. B. GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

Die Aufrufe werden dann als cURL-Befehle in einer Anfrage angezeigt, die die erforderlichen Kopfzeilen und den vollständigen „Basispfad“ enthält, die für eine erfolgreiche Interaktion mit der API erforderlich sind. Der Basispfad sollte allen Endpunkten vorangestellt werden. Der oben genannte Endpunkt /global/classes beispielsweise ändert sich in https://platform.adobe.io/data/foundation/schemaregistry/global/classes. In der gesamten Dokumentation wird das API-Format-/Anfragemuster angezeigt. Es wird erwartet, dass Sie den vollständigen Pfad verwenden, der in der Beispielanfrage angezeigt wird, wenn Sie Ihre eigenen Aufrufe an Platform-APIs durchführen.

Beispiel-API-Anfrage

Im Folgenden finden Sie eine Beispiel-API-Anfrage, die das Format veranschaulicht, mit dem Sie es in der Dokumentation zu tun haben werden.

API-Format

Das API-Format gibt Auskunft über den Vorgang (GET) und den verwendeten Endpunkt. Variablen werden durch geschweifte Klammern gekennzeichnet (in diesem Fall {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Anfrage

In dieser Beispielanfrage werden den Variablen aus dem API-Format tatsächliche Werte im Anfragepfad zugewiesen. Darüber hinaus werden alle erforderlichen Kopfzeilen entweder als Beispiel-Kopfzeilenwerte oder als Variablen angezeigt, in denen sensible Informationen (wie Sicherheits-Token und Zugriffs-IDs) enthalten sein sollten.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -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

Die Antwort zeigt, was Sie nach einem erfolgreichen Aufruf an die API erwarten würden, je nach gesendeter Anfrage. Zum Teil ist die Antwort aus Platzgründen abgeschnitten, d. h. Sie können möglicherweise mehr Informationen oder zusätzliche Informationen zu den im Beispiel dargestellten Informationen sehen.

{
    "results": [
        {
            "title": "XDM ExperienceEvent",
            "$id": "https://ns.adobe.com/xdm/context/experienceevent",
            "meta:altId": "_xdm.context.experienceevent",
            "version": "1"
        },
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile",
            "meta:altId": "_xdm.context.profile",
            "version": "1"
        }
    ],
    "_links": {}
}

Fehlermeldungen

Das Handbuch zur Fehlerbehebung bei Platform enthält eine Liste von Fehlern, auf die Sie bei der Verwendung von Experience Platform-Services stoßen können.

Hinweise zur Fehlerbehebung bei einzelnen Platform-Services finden Sie unter Verzeichnis zur Fehlerbehebung bei Services.

Weitere Informationen zu bestimmten Endpunkten in Platform-APIs, einschließlich erforderlicher Kopfzeilen und Anfragetexte, finden Sie in den Platform-API-Handbüchern.

Platform-API-Handbücher api-guides

Weitere Informationen zu bestimmten Endpunkten und Vorgängen, die für jeden Service verfügbar sind, finden Sie in der API-Referenzdokumentation auf Adobe I/O.

Nächste Schritte

In diesem Dokument wurden die erforderlichen Kopfzeilen und verfügbaren Handbücher vorgestellt und ein Beispiel für einen API-Aufruf bereitgestellt. Nachdem Sie nun über die erforderlichen Kopfzeilenwerte verfügen, die für API-Aufrufe auf Adobe Experience Platform erforderlich sind, wählen Sie einen zu untersuchenden API-Endpunkt aus der Tabelle Platform-API-Handbücher aus.

Antworten auf häufig gestellte Fragen finden Sie im Handbuch zur Fehlerbehebung bei Platform.

Informationen zum Einrichten einer Postman-Umgebung und zum Erkunden der verfügbaren Postman-Sammlungen finden Sie im Platform Postman-Handbuch.