Erste Schritte mit REST APIs

Informationen zu allgemeinen Anforderungen, Authentifizierung, optionalen Abfrageparametern, Anforderung URLsund andere Verweise.

API-Anforderungen und -Empfehlungen

Was Sie tun müssen und sollten, wenn Sie mit dem Audience Manager APIs.

Beachten Sie Folgendes beim Arbeiten mit Audience Manager-API code:

• Anforderungsparameter: alle Anfrageparameter sind erforderlich, sofern nicht anders angegeben.
• Anfragekopfzeilen: bei Verwendung Adobe Developer Token, müssen Sie die x-api-key -Kopfzeile. Sie können API durch Befolgen der Anweisungen im Integration von Dienstkonten Seite.
• JSONInhaltstyp: Angeben content-type: application/json und accept: application/json in Ihrem Code.
• Anforderungen und Antworten: Anforderungen als ordnungsgemäß formatierten JSON -Objekt. Audience Manager antwortet mit JSON formatierten Daten. Serverantworten können angeforderte Daten, einen Statuscode oder beides enthalten.
• Zugriff: Ihre Audience Manager -Berater stellt Ihnen eine Client-ID und einen Schlüssel zur Verfügung, mit der Sie API -Anfragen.
• Dokumentation und Codebeispiele: Text in kursiv stellt eine Variable dar, die Sie bereitstellen oder übergeben, wenn Sie API Daten. Ersetzen kursiv Text mit Ihrem eigenen Code, Ihren eigenen Parametern oder anderen erforderlichen Informationen.

Authentifizierung

Die Audience Manager REST APIs unterstützt zwei Authentifizierungsmethoden.

• JWT-Authentifizierung (Dienstkonto) using Adobe Developer. Adobe Developer ist das Entwickler-Ökosystem und die Community der Adobe. Er umfasst APIs für alle Adobe-Produkte. Dies ist die empfohlene Methode zur Einrichtung und Verwendung von Adobe APIs.
• OAuth-Authentifizierung (veraltet). Diese Methode wird zwar nicht mehr unterstützt, Kunden mit vorhandenen OAuth Integrationen können diese Methode weiterhin verwenden.

JWT (Service Account) Authentifizierung mit Adobe Developer

Übersicht über Adobe Developer

Adobe Developer ist das Entwickler-Ökosystem und die Community der Adobe. Er umfasst APIs für alle Adobe-Produkte.

Dies ist die empfohlene Methode zur Einrichtung und Verwendung von Adobe APIs.

Voraussetzungen

Vor der Konfiguration JWT Authentifizierung, stellen Sie sicher, dass Sie Zugriff auf die Adobe Developer-Konsole in Adobe Developer. Wenden Sie sich für Zugriffsanfragen an Ihren Organisationsadministrator.

Authentifizierung

Gehen Sie wie folgt vor, um JWT (Service Account) Authentifizierung mit Adobe Developer:

1. Melden Sie sich bei der Adobe Developer-Konsole.
2. Führen Sie die Schritte unter Service-Konto-Verbindung.
   • Während Schritt 2: Hinzufügen einer API zu Ihrem Projekt mithilfe der Authentifizierung für Dienstkonten, wählen Sie die Audience Manager API -Option.
3. Probieren Sie die Verbindung aus, indem Sie Ihre erste API -Aufruf basierend auf den Anweisungen von Schritt 3.

RBAC-Berechtigungen für technische Konten

Wenn Ihr Audience Manager-Konto Rollenbasierte Zugriffssteuerungmüssen Sie ein technisches Audience Manager-Benutzerkonto erstellen und es der Audience Manager-RBAC-Gruppe hinzufügen, die die API-Aufrufe durchführt.

Gehen Sie wie folgt vor, um ein technisches Benutzerkonto zu erstellen und es einer RBAC-Gruppe hinzuzufügen:

1. Erstellen Sie eine GET Aufruf von https://aam.adobe.io/v1/users/self. Durch den Aufruf wird ein technisches Benutzerkonto erstellt, das Sie im Admin Consolein der Users Seite.

   

2. Melden Sie sich bei Ihrem Audience Manager-Konto an und das technische Benutzerkonto hinzufügen an die Benutzergruppe, die die API-Aufrufe durchführt.

OAuth Authentifizierung (veraltet)

Die Audience Manager REST API following OAuth 2.0 Standards für die Token-Authentifizierung und -Erneuerung. In den folgenden Abschnitten wird beschrieben, wie Sie sich authentifizieren und mit der Arbeit mit dem APIs.

Generische Elemente erstellen API Benutzer

Es wird empfohlen, ein eigenes technisches Benutzerkonto für die Arbeit mit der Audience Manager APIs. Dies ist ein generisches Konto, das nicht an einen bestimmten Benutzer in Ihrem Unternehmen gebunden ist oder mit diesem verknüpft ist. Diese Art von API Mit dem Benutzerkonto können Sie zwei Dinge erreichen:

• Identifizieren, welcher Dienst die API (z. B. Aufrufe aus Ihren Apps, die unsere APIs oder von anderen Werkzeugen, die API -Anfragen).
• Ununterbrochenen Zugriff auf die APIs. Ein Konto, das an eine bestimmte Person gebunden ist, kann gelöscht werden, wenn sie Ihr Unternehmen verlässt. Dadurch wird verhindert, dass Sie mit den verfügbaren API Code. Ein generisches Konto, das nicht an einen bestimmten Mitarbeiter gebunden ist, hilft Ihnen, dieses Problem zu vermeiden.

Nehmen wir als Beispiel oder Anwendungsfall für diesen Kontotyp an, Sie möchten viele Segmente gleichzeitig mit der Tools für die Massenverwaltung. Dazu benötigt Ihr Benutzerkonto API Zugriff. Anstatt einem bestimmten Benutzer Berechtigungen hinzuzufügen, erstellen Sie eine unspezifische API Benutzerkonto mit den entsprechenden Anmeldeinformationen, Schlüsseln und Geheimnissen für API -Aufrufe. Dies ist auch nützlich, wenn Sie eigene Anwendungen entwickeln, die die Audience Manager APIs.

Arbeiten mit Audience Manager Berater, um eine generische API- nur Benutzerkonto.

Workflow zur Kennwortauthentifizierung

Sicherer Zugriff auf die Kennwortauthentifizierung REST API. Die folgenden Schritte beschreiben den Workflow für die Kennwortauthentifizierung von einem JSON Client in Ihrem Browser.

Schritt 1: Anfrage API Zugriff

Wenden Sie sich an Ihren Partner Solutions Manager. Sie werden Ihnen eine API Client-ID und geheimer Schlüssel. Die Kennung und das Geheimnis authentifizieren Sie bei der API.

Hinweis: Wenn Sie ein Aktualisierungstoken erhalten möchten, geben Sie dies bei der Anforderung an API Zugriff.

Schritt 2: Token anfordern

Übergeben einer Token-Anfrage mit Ihrer bevorzugten JSON Client. Wenn Sie die Anforderung erstellen:

• Verwenden Sie eine POST -Methode zum Aufrufen https://api.demdex.com/oauth/token.
• Konvertieren Sie Ihre Client-ID und Ihr Geheimnis in eine Base-64-kodierte Zeichenfolge. Trennen Sie die ID und das Geheimnis während des Konvertierungsprozesses durch einen Doppelpunkt. Beispielsweise die Anmeldedaten testId : testSecret konvertieren in dGVzdElkOnRlc3RTZWNyZXQ=.
• Übergeben Sie die HTTP headers Authorization:Basic <base-64 clientID:clientSecret> und Content-Type: application/x-www-form-urlencoded . Die Kopfzeile könnte beispielsweise wie folgt aussehen:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Richten Sie den Anfragetext wie folgt ein:
  
  grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Schritt 3: Token empfangen

Die JSON -Antwort enthält Ihr Zugriffstoken. Die Antwort sollte wie folgt aussehen:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

Die expires_in key gibt die Anzahl der Sekunden an, bis das Zugriffstoken abläuft. Es hat sich bewährt, kurze Ablaufzeiten zu verwenden, um die Exposition zu begrenzen, wenn das Token jemals offen gelegt wird.

Token aktualisieren

Token aktualisieren erneuern API -Zugriff nach Ablauf des ursprünglichen Tokens. Auf Anfrage wird die Antwort JSON enthält im Kennwort-Workflow ein Aktualisierungstoken. Wenn Sie kein Aktualisierungstoken erhalten, erstellen Sie mithilfe des Kennwortauthentifizierungsprozesses ein neues.

Sie können auch ein Aktualisierungstoken verwenden, um ein neues Token zu generieren, bevor das vorhandene Zugriffstoken abläuft.

Wenn Ihr Zugriffstoken abgelaufen ist, erhalten Sie eine 401 Status Code und die folgende Kopfzeile in der Antwort:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

Die folgenden Schritte beschreiben den Workflow für die Verwendung eines Aktualisierungstokens zum Erstellen eines neuen Zugriffstokens aus einem JSON Client in Ihrem Browser.

Schritt 1: Anfordern des neuen Tokens

Übergeben einer Aktualisierungs-Token-Anforderung mit Ihrer bevorzugten JSON Client. Wenn Sie die Anforderung erstellen:

• Verwenden Sie eine POST -Methode zum Aufrufen https://api.demdex.com/oauth/token.
• Konvertieren Sie Ihre Client-ID und Ihr Geheimnis in eine Base-64-kodierte Zeichenfolge. Trennen Sie die ID und das Geheimnis während des Konvertierungsprozesses durch einen Doppelpunkt. Beispielsweise die Anmeldedaten testId : testSecret konvertieren in dGVzdElkOnRlc3RTZWNyZXQ=.
• Übergeben von HTTP-Headern Authorization:Basic <base-64 clientID:clientSecret> und Content-Type: application/x-www-form-urlencoded. Die Kopfzeile könnte beispielsweise wie folgt aussehen:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Geben Sie im Anfragetext die grant_type:refresh_token und geben Sie das Aktualisierungs-Token weiter, das Sie in Ihrer vorherigen Zugriffsanfrage erhalten haben. Die Anfrage sollte wie folgt aussehen:
  grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Schritt 2: Empfangen des neuen Tokens

Die JSON -Antwort enthält Ihr neues Zugriffstoken. Die Antwort sollte wie folgt aussehen:

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Autorisierungscode und implizite Authentifizierung

Die Audience Manager REST API unterstützt Autorisierungscode und implizite Authentifizierung. Um diese Zugriffsmethoden verwenden zu können, müssen sich Ihre Benutzer bei https://api.demdex.com/oauth/authorize , um auf Token zuzugreifen und sie zu aktualisieren.

Authentifizieren API Anforderungen

Anforderungen an den Aufruf von API Methoden, nachdem Sie ein Authentifizierungstoken erhalten haben.

So stellen Sie Aufrufe gegen die verfügbare bereit API Methoden:

• Im HTTP Header, festgelegt Authorization: Bearer <token>.
• Bei Verwendung von JWT-Authentifizierung (Dienstkonto), müssen Sie die x-api-key -Kopfzeile, die mit Ihrem client_id. Sie können client_id von Adobe Developer-Integration Seite.
• Rufen Sie die erforderliche API -Methode.

Optional API Abfrageparameter

Legen Sie die optionalen Parameter fest, die für Methoden verfügbar sind, die alle Eigenschaften für ein Objekt zurückgeben.

Sie können diese optionalen Parameter mit API zurückgegebene Methoden all -Eigenschaften für ein Objekt. Legen Sie diese Optionen in der Anforderungszeichenfolge fest, wenn Sie diese Abfrage an die API.

Ein Hinweis zu Seitenoptionen

Wann Seiteninformationen ist nicht angegeben, gibt die Anfrage die Ebene zurück JSON führt zu einem Array. Wenn Seiteninformationen is angegeben ist, wird die zurückgegebene Liste in eine JSON -Objekt, das Informationen zum Gesamtergebnis und zur aktuellen Seite enthält. Ihre Beispielanfrage mit Seitenoptionen könnte in etwa wie folgt aussehen:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs für Anforderungen, Staging- und Produktionsumgebungen und -versionen.

Anfrage URLs

Die folgende Tabelle listet die Anforderung auf URLs verwendet, um API -Anfragen nach Methode.

Abhängig von der verwendeten Authentifizierungsmethode müssen Sie Ihre Anfrage anpassen URLs entsprechend den unten stehenden Tabellen.

Anfrage URLs für JWT Authentifizierung

Anfrage URLs für OAuth Authentifizierung (veraltet)

Umgebungen

Die Audience Manager APIbietet Zugriff auf verschiedene Arbeitsumgebungen. Diese Umgebungen helfen Ihnen beim Testen von Code mit separaten Datenbanken, ohne dass sich dies auf Live-Produktionsdaten auswirkt. In der folgenden Tabelle sind die verfügbaren API Umgebungen und die entsprechenden Ressourcen-Hostnamen.

Abhängig von der verwendeten Authentifizierungsmethode müssen Sie Ihre Umgebung anpassen URLs entsprechend der unten stehenden Tabelle.

Versionen

Neue Versionen dieser APIs werden regelmäßig veröffentlicht. Bei einer neuen Version wird die API Versionsnummer. Die Versionsnummer wird in der Anfrage referenziert URL as v<version number> wie im folgenden Beispiel gezeigt:

https://<host>/v1/...

Definierte Antwortcodes

HTTP Status-Codes und Antworttext, der von der Audience Manager REST API.

Ressourcen für Business.Adobe.com

Third Party Integrations Third Party Data Customer Journey Analytics Mobile Analytics Audience Segmentation General Data Protection Regulation