Authentifizieren und Zugreifen auf Experience Platform-APIs

Dieses Dokument bietet eine schrittweise Anleitung für den Zugriff auf ein Adobe Experience Platform-Entwicklerkonto, damit Sie Aufrufe an Experience Platform-APIs durchführen können. Am Ende dieses Tutorials haben Sie die folgenden Anmeldeinformationen generiert oder erfasst, die als Kopfzeilen in allen Platform-API-Aufrufen erforderlich sind:

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {ORG_ID}
TIP
Zusätzlich zu den drei oben genannten Anmeldedaten benötigen viele Platform-APIs auch eine gültige {SANDBOX_NAME} als Kopfzeile angegeben werden. Siehe Sandbox-Übersicht Weitere Informationen zu Sandboxes und dem Sandbox-Verwaltungsendpunkt Dokumentation für Informationen zur Auflistung der für Ihr Unternehmen verfügbaren Sandboxes.

Um die Sicherheit Ihrer Anwendungen und Benutzer zu gewährleisten, müssen alle Anfragen an Experience Platform-APIs anhand von Standards wie OAuth authentifiziert und autorisiert werden.

In diesem Tutorial wird beschrieben, wie Sie die erforderlichen Anmeldeinformationen zum Authentifizieren von Platform-API-Aufrufen erfassen, wie im unten stehenden Flussdiagramm beschrieben. Sie können die meisten erforderlichen Anmeldeinformationen bei der ersten einmaligen Einrichtung erfassen. Das Zugriffstoken muss jedoch alle 24 Stunden aktualisiert werden.

Voraussetzungen prerequisites

Um Experience Platform-APIs erfolgreich aufrufen zu können, müssen Sie über Folgendes verfügen:

  • Eine Organisation mit Zugriff auf Adobe Experience Platform.
  • Ein Admin Console-Administrator, der Sie als Entwickler und Anwender für ein Produktprofil hinzufügen kann.
  • Ein Experience Platform-Systemadministrator, der Ihnen die erforderlichen attributbasierten Zugriffssteuerungen gewähren kann, um Lese- oder Schreibvorgänge für verschiedene Experience Platform-Bereiche über APIs durchzuführen.

Sie müssen auch über eine Adobe ID verfügen, um dieses Tutorial abzuschließen. Wenn Sie keine Adobe ID haben, können Sie wie folgt eine erstellen:

  1. Navigieren Sie zu Adobe Developer-Konsole.
  2. Auswählen Neues Konto erstellen.
  3. Schließen Sie den Anmeldevorgang ab.

Entwickler- und Benutzerzugriff für Experience Platform erlangen gain-developer-user-access

Vor der Erstellung von Integrationen in der Adobe Developer Console muss Ihr Konto über Entwickler- und Benutzerberechtigungen für ein Experience Platform-Produktprofil in Adobe Admin Console verfügen.

Entwicklerzugriff erlangen gain-developer-access

Kontakt Admin Console Administrator in Ihrer Organisation, um Sie als Entwickler zu einem Experience Platform-Produktprofil hinzuzufügen, indem Sie Admin Console. Siehe Admin Console Dokumentation für spezifische Anweisungen zum Verwalten des Entwicklerzugriffs für Produktprofile.

Nachdem Sie als Entwickler zugewiesen wurden, können Sie mit der Erstellung von Integrationen in Adobe Developer-Konsole. Bei diesen Integrationen handelt es sich um eine Pipeline von externen Apps und Diensten zu Adobe-APIs.

Benutzerzugriff erlangen gain-user-access

Ihre Admin Console -Administrator muss Sie auch als Benutzer zum selben Produktprofil hinzufügen. Mit dem Benutzerzugriff können Sie in der Benutzeroberfläche das Ergebnis der von Ihnen ausgeführten API-Vorgänge anzeigen.

Siehe Handbuch unter Verwalten von Benutzergruppen in Admin Console für weitere Informationen.

API-Schlüssel (Client-ID) und Organisations-ID generieren generate-credentials

NOTE
Wenn Sie diesem Dokument aus dem Handbuch zur Privacy Service-APIkönnen Sie nun zu diesem Handbuch zurückkehren, um die eindeutigen Zugriffsberechtigungen für Privacy Service.

Nachdem Sie Entwicklern und Benutzern Zugriff auf Platform gewährt haben, über Admin Console, ist der nächste Schritt die Generierung Ihrer {ORG_ID} und {API_KEY} Anmeldedaten in der Adobe Developer-Konsole. Diese Anmeldeinformationen müssen nur einmal generiert werden und können in zukünftigen Platform-API-Aufrufen wiederverwendet werden.

Experience Platform zu einem Projekt hinzufügen add-platform-to-project

Wechseln Sie zur Adobe-Entwicklerkonsole und melden Sie sich mit Ihrer Adobe ID an. Führen Sie anschließend die Schritte aus, die im Tutorial Erstellen eines leeren Projekts in der Dokumentation zu Adobe Developer Console beschrieben werden.

Nachdem Sie ein neues Projekt erstellt haben, wählen Sie API hinzufügen auf Projektübersicht angezeigt.

TIP
Wenn Sie für mehrere Organisationen bereitgestellt sind, verwenden Sie die Organisationsauswahl in der oberen rechten Ecke der Benutzeroberfläche, um sicherzustellen, dass Sie sich in der gewünschten Organisation befinden.

Bildschirm Entwicklerkonsolemit hervorgehobener Option API hinzufügen.

Der Bildschirm API hinzufügen wird angezeigt. Wählen Sie das Produktsymbol für Adobe Experience Platform aus und wählen Sie dann Experience Platform-API vor der Auswahl Nächste.

Wählen Sie Experience Platform-API.

TIP
Wählen Sie die Dokumente anzeigen -Option, um in einem separaten Browserfenster zum Abschluss zu navigieren Experience Platform-API-Referenzdokumentation.

Wählen Sie den Authentifizierungstyp OAuth Server-zu-Server aus. select-oauth-server-to-server

Wählen Sie anschließend den Authentifizierungstyp aus, um Zugriffstoken zu generieren und auf die Experience Platform-API zuzugreifen.

IMPORTANT
Wählen Sie die OAuth Server-zu-Server -Methode, da dies künftig die einzige unterstützte Methode sein wird. Die Dienstkonto (JWT) -Methode veraltet ist. Während Integrationen, die die JWT-Authentifizierungsmethode verwenden, bis zum 1. Januar 2025 weiterhin funktionieren, empfiehlt Adobe dringend, vorhandene Integrationen vor diesem Datum auf die neue OAuth Server-zu-Server-Methode zu migrieren. Weitere Informationen finden Sie im Abschnitt .+----------------+ | badge negative | +================+ | Veraltet | +----------------+JSON-Web-Token (JWT) generieren.

Wählen Sie Experience Platform-API.

Produktprofile für Ihre Integration auswählen select-product-profiles

Im API konfigurieren Bildschirm, auswählen AEP-Default-All-Users.

IMPORTANT
Um Zugriff auf bestimmte Funktionen in Platform zu erhalten, benötigen Sie außerdem einen Systemadministrator, der Ihnen die erforderlichen attributbasierten Zugriffssteuerungsberechtigungen erteilt. Mehr dazu im Abschnitt Abrufen der erforderlichen attributbasierten Zugriffssteuerungsberechtigungen.

Wählen Sie Produktprofile für Ihre Integration aus.

Auswählen Konfigurierte API speichern wenn Sie bereit sind.

Eine exemplarische Vorgehensweise zum Einrichten einer Integration mit der Experience Platform-API finden Sie auch im folgenden Video-Tutorial:

Sammeln von -Anmeldeinformationen gather-credentials

Nachdem die API zum Projekt hinzugefügt wurde, wird die Experience Platform-API -Seite für das Projekt zeigt die folgenden Anmeldeinformationen an, die für alle Aufrufe von Experience Platform-APIs erforderlich sind:

Integrationsinformationen nach dem Hinzufügen einer API in Developer Console.

  • {API_KEY} (Client-ID)
  • {ORG_ID} (Organisations-ID)

Zugriffstoken generieren generate-access-token

Der nächste Schritt besteht darin, eine {ACCESS_TOKEN} Berechtigung zur Verwendung in Platform-API-Aufrufen. Im Gegensatz zu den Werten für {API_KEY} und {ORG_ID}muss ein neues Token alle 24 Stunden generiert werden, damit Sie weiterhin Platform-APIs verwenden können. Auswählen Zugriffstoken generieren, wie unten dargestellt.

Anzeigen der Generierung des Zugriffstokens

TIP
Sie können auch eine Postman-Umgebung und -Sammlung verwenden, um Zugriffstoken zu generieren. Weitere Informationen finden Sie im Abschnitt zu Verwenden von Postman zum Authentifizieren und Testen von API-Aufrufen.

VeraltetJSON-Web-Token (JWT) generieren jwt

WARNING
Die JWT-Methode zum Generieren von Zugriffs-Token wird nicht mehr unterstützt. Alle neuen Integrationen müssen mit der Authentifizierungsmethode OAuth-Server-zu-Server erstellt werden. Adobe empfiehlt auch, Ihre vorhandenen Integrationen zur OAuth-Methode zu migrieren. Lesen Sie die folgende wichtige Dokumentation:
Eingestellte Informationen anzeigen

Der nächste Schritt besteht darin, ein JSON Web Token (JWT) basierend auf Ihren Kontoanmeldeinformationen zu generieren. Mit diesem Wert wird Ihre {ACCESS_TOKEN} Berechtigung zur Verwendung in Platform-API-Aufrufen, die alle 24 Stunden neu generiert werden müssen.

note important
IMPORTANT
In diesem Tutorial wird anhand der folgenden Schritte beschrieben, wie Sie in der Developer Console eine JWT generieren. Diese Erzeugungsmethode sollte jedoch nur zu Test- und Auswertungszwecken verwendet werden.
Für die normale Verwendung muss die JWT automatisch generiert werden. Weitere Informationen zum programmgesteuerten Generieren von JWTs finden Sie unter Authentifizierungshandbuch für Dienstkonten auf Adobe Developer.

Auswählen Dienstkonto (JWT) Wählen Sie im linken Navigationsbereich die Option JWT generieren.

In dem unter Benutzerdefiniertes JWT generieren Fügen Sie den Inhalt des privaten Schlüssels ein, den Sie zuvor beim Hinzufügen der Platform-API zu Ihrem Dienstkonto generiert haben. Wählen Sie anschließend Generate Token.

Die Seite wird aktualisiert und zeigt das generierte JWT sowie einen cURL-Beispielbefehl an, mit dem Sie ein Zugriffstoken generieren können. Wählen Sie für diese Anleitung Kopieren neben Generiertes JWT , um das Token in die Zwischenablage zu kopieren.

Zugriffstoken generieren

Nachdem Sie ein JWT generiert haben, können Sie es in einem API-Aufruf verwenden, um Ihre {ACCESS_TOKEN}. Im Gegensatz zu den Werten für {API_KEY} und {ORG_ID}muss ein neues Token alle 24 Stunden generiert werden, damit Sie weiterhin Platform-APIs verwenden können.

Anfrage

Die folgende Anfrage generiert eine neue {ACCESS_TOKEN} basierend auf den in der Payload angegebenen Anmeldeinformationen. Dieser Endpunkt akzeptiert nur Formulardaten als Payload und muss daher eine Content-Type -Kopfzeile multipart/form-data.

code language-shell
curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'
table 0-row-2 1-row-2 2-row-2 3-row-2
Eigenschaft Beschreibung
{API_KEY} Die {API_KEY} (Client-ID), die Sie in einem vorheriger Schritt.
{SECRET} Das Client-Geheimnis, das Sie in einem vorheriger Schritt.
{JWT} Der JWT, den Sie in einem vorheriger Schritt.
note note
NOTE
Sie können denselben API-Schlüssel, dasselbe Client-Geheimnis und dasselbe JWT verwenden, um ein neues Zugriffstoken für jede Sitzung zu generieren. Auf diese Weise können Sie die Erstellung von Zugriffstoken in Ihren Anwendungen automatisieren.

Antwort

code language-json
{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
table 0-row-2 1-row-2 2-row-2 3-row-2
Eigenschaft Beschreibung
token_type Der Typ of Token zurückgegeben. Für Zugriffstoken ist dieser Wert immer bearer.
access_token Die generierte {ACCESS_TOKEN}. Dieser Wert, dem das Wort vorangestellt ist Bearer, da die Authentication -Kopfzeile für alle Platform-API-Aufrufe.
expires_in Die Anzahl der Millisekunden, die bis zum Ablauf des Zugriffstokens verbleiben. Sobald dieser Wert 0 erreicht, muss ein neues Zugriffstoken generiert werden, um weiterhin Platform-APIs verwenden zu können.

Zugriffsberechtigungen testen test-credentials

Nachdem Sie alle drei erforderlichen Anmeldeinformationen - Zugriffstoken, API-Schlüssel und Organisations-ID - erfasst haben, können Sie versuchen, den folgenden API-Aufruf durchzuführen. Dieser Aufruf listet alle standardmäßigen Experience Data Model (XDM)-Klassen, die für Ihr Unternehmen verfügbar sind. Importieren und Ausführen des -Aufrufs in Postman.

recommendation-more-help

Anfrage

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

Antwort

Wenn Ihre Antwort der unten gezeigten ähnelt, sind Ihre Anmeldedaten gültig und funktionieren. (Diese Antwort wurde aus Platzgründen abgeschnitten.)

{
  "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"
    }
  ]
}
IMPORTANT
Der obige Aufruf reicht zwar aus, um Ihre Zugriffsberechtigungen zu testen, beachten Sie jedoch, dass Sie nicht auf mehrere Ressourcen zugreifen oder sie ändern können, ohne über die richtigen attributbasierten Zugriffssteuerungsberechtigungen zu verfügen. Weitere Informationen finden Sie unter Abrufen der erforderlichen attributbasierten Zugriffssteuerungsberechtigungen unten.

Abrufen der erforderlichen attributbasierten Zugriffssteuerungsberechtigungen get-abac-permissions

Um auf verschiedene Ressourcen innerhalb von Experience Platform zugreifen oder sie ändern zu können, benötigen Sie die entsprechenden Zugriffssteuerungsberechtigungen. Systemadministratoren können Ihnen die benötigte Berechtigungen. Weitere Informationen finden Sie im Abschnitt zu Verwalten von API-Anmeldeinformationen für eine Rolle.

Ausführliche Informationen dazu, wie ein Systemadministrator die erforderlichen Berechtigungen für den Zugriff auf Platform-Ressourcen über die API gewähren kann, finden Sie auch im folgenden Video-Tutorial:

Verwenden von Postman zum Authentifizieren und Testen von API-Aufrufen use-postman

Postman ist ein beliebtes Tool, mit dem Entwickler RESTful-APIs untersuchen und testen können. Sie können Sammlungen und Umgebungen in Experience Platform Postman verwenden, um die Arbeit mit Experience Platform-APIs zu beschleunigen. Mehr dazu Verwenden von Postman im Experience Platform und erste Schritte mit Sammlungen und Umgebungen.

Detaillierte Informationen zur Verwendung von Postman mit Experience Platform-Sammlungen und -Umgebungen finden Sie auch in den folgenden Video-Tutorials:

Herunterladen und Importieren einer Postman-Umgebung zur Verwendung mit Experience Platform-APIs

Verwenden einer Postman-Sammlung zum Generieren von Zugriffstoken

Laden Sie die Identity Management Service Postman-Sammlung und sehen Sie sich das folgende Video an, um zu erfahren, wie Sie Zugriffstoken generieren.

Herunterladen von Experience Platform API Postman-Sammlungen und Interagieren mit den APIs

Systemadministratoren: Gewähren Sie Entwicklern und API-Zugriffskontrolle mit Experience Platform-Berechtigungen grant-developer-and-api-access-control

NOTE
Nur Systemadministratoren können API-Anmeldeinformationen in den Berechtigungen anzeigen und verwalten.

Vor der Erstellung von Integrationen in der Adobe Developer Console muss Ihr Konto über Entwickler- und Benutzerberechtigungen für ein Experience Platform-Produktprofil in Adobe Admin Console verfügen.

Hinzufügen von Entwicklern zum Produktprofil add-developers-to-product-profile

Gehen Sie zu Admin Console und melden Sie sich mit Ihrer Adobe ID an.

Auswählen Produkte, wählen Sie Adobe Experience Platform aus der Liste der Erzeugnisse.

Produktliste auf Admin Console

Aus dem Produktprofile Registerkarte auswählen AEP-Default-All-Users. Alternativ können Sie über die Suchleiste nach dem Produktprofil suchen, indem Sie den Namen eingeben.

Suchen Sie nach dem Produktprofil

Wählen Sie die Entwickler Registerkarte und wählen Sie Entwickler hinzufügen.

Entwickler über die Registerkarte Entwicklerhinzufügen

Geben Sie die E-Mail- oder Benutzername. Eine gültige E-Mail- oder Benutzername zeigt die Entwicklerdetails an. Wählen Sie Speichern aus.

Entwickler mithilfe ihrer E-Mail- oder Benutzernamen hinzufügen

Der Entwickler wurde erfolgreich hinzugefügt und wird im Entwickler Registerkarte.

Entwickler, aufgeführt auf der Registerkarte Entwickler

Zuweisen der API zu einer Rolle

Ein Systemadministrator kann Rollen in der Experience Platform-Benutzeroberfläche APIs zuweisen.

Auswählen Berechtigungen und die Rolle, der Sie die API hinzufügen möchten. Wählen Sie die API-Anmeldeinformationen Registerkarte und wählen Sie API-Anmeldeinformationen hinzufügen.

Registerkarte API-Anmeldeinformationenin der ausgewählten Rolle

Wählen Sie die API aus, die Sie der Rolle hinzufügen möchten, und wählen Sie dann Speichern.

Liste der zur Auswahl verfügbaren APIs

Sie kehren zum API-Anmeldeinformationen -Tab, wo die neu hinzugefügte API aufgelistet ist.

Registerkarte mit API-Anmeldeinformationen mit neu hinzugefügter API

Zusätzliche Ressourcen additional-resources

Weitere Informationen zu den ersten Schritten mit Experience Platform-APIs finden Sie in den folgenden zusätzlichen Ressourcen

Nächste Schritte next-steps

Durch Lesen dieses Dokuments haben Sie Ihre Zugangsdaten für Platform-APIs gesammelt und erfolgreich getestet. Sie können nun den Beispielaufrufen folgen, die im Abschnitt Dokumentation.

Zusätzlich zu den Authentifizierungswerten, die Sie in diesem Tutorial gesammelt haben, benötigen viele Platform-APIs auch eine gültige {SANDBOX_NAME} als Kopfzeile angegeben werden. Weiterführende Informationen dazu finden Sie unter Sandbox-Übersicht.

5741548a-2e07-44b3-9157-9c181502d0c5