Erste Schritte mit REST APIs

Informationen zu allgemeinen Anforderungen, Authentifizierung, optionalen Parametern für die Abfrage, Anforderung URLs und anderen Referenzen.

API-Anforderungen und -Empfehlungen

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

Beachten Sie Folgendes, wenn Sie mit dem Code Audience Manager-API arbeiten:

  • Anforderungsparameter: Alle Anforderungsparameter sind erforderlich, sofern nicht anders angegeben.
  • Anforderungsheader: bei Verwendung von Adobe-I/ Otokens müssen Sie die x-api-key Kopfzeile angeben. Sie können Ihren API-Schlüssel abrufen, indem Sie die Anweisungen auf der Seite Dienstkontointegration befolgen.
  • JSONInhaltstyp: Geben Sie content-type: application/json ** accept: application/json Ihren Code an.
  • Anforderungen und Antworten: Senden von Anforderungen als korrekt formatiertes JSON Objekt. Audience Manager antwortet mit JSON formatierten Daten. Serverantworten können angeforderte Daten, einen Statuscode oder beides enthalten.
  • Zugriff: Ihr Audience Manager Berater stellt Ihnen eine Client-ID und einen Schlüssel zur Verfügung, mit denen Sie API Anforderungen stellen können.
  • Dokumentations- und Codebeispiele: Text in ** Kursivschrift stellt eine Variable dar, die Sie beim Herstellen oder Empfangen von API Daten angeben oder weitergeben. Ersetzen Sie den Text kursiv durch Ihren eigenen Code, Ihre eigenen Parameter oder andere erforderliche Informationen.

Authentifizierung

Die Audience Manager REST APIs unterstützen zwei Authentifizierungsmethoden.

WICHTIG

Abhängig von Ihrer Authentifizierungsmethode müssen Sie Ihre Anforderung URLs entsprechend anpassen. Einzelheiten zu den zu verwendenden Hostnamen finden Sie im Abschnitt Umgebung.

JWT (Service Account) Authentifizierung mit Adobe I/O

Adobe I/O-Übersicht

Adobe I/O ist das Entwicklerökosystem und die Community der Adobe. Es enthält die Adobe I/O-Entwicklerwerkzeuge und -APIs und APIs für alle Adoben-Produkte.

Dies ist die empfohlene Methode zum Einrichten und Verwenden von Adobe APIs.

Voraussetzungen

Bevor Sie die JWT-Authentifizierung konfigurieren können, stellen Sie sicher, dass Sie Zugriff auf die Adobe Developer Console in Adobe I/O haben. Wenden Sie sich für Zugriffsanfragen an Ihren Unternehmensadministrator.

Authentifizierung

Gehen Sie wie folgt vor, um die JWT (Service Account)-Authentifizierung mit Adobe I/O zu konfigurieren:

  1. Melden Sie sich bei Adobe Developer Console an.
  2. Führen Sie die Schritte unter Dienstkontoverbindung aus.
  3. Versuchen Sie, die Verbindung herzustellen, indem Sie Ihren ersten API-Aufruf entsprechend den Anweisungen von Schritt 3 ausführen.
HINWEIS

Um das Audience Manager REST APIs auf automatisierte Weise zu konfigurieren und zu verwenden, können Sie das JWT programmgesteuert generieren. Detaillierte Anweisungen finden Sie unter JWT (Service Account) Authentication.

OAuth Authentifizierung (nicht mehr unterstützt)

WARNUNG

Audience Manager REST API Token-Authentifizierung und -Erneuerung über OAuth 2.0 ist jetzt veraltet.

Bitte verwenden Sie stattdessen JWT (Service Account) Authentication.

Audience Manager REST API entspricht OAuth 2.0-Standards für die Token-Authentifizierung und -Erneuerung. In den folgenden Abschnitten wird beschrieben, wie Sie sich authentifizieren und mit APIs arbeiten, und wie Beginn mit diesen arbeiten.

Erstellen eines generischen API Benutzers

Es wird empfohlen, ein separates technisches Benutzerkonto für die Arbeit mit Audience Manager APIs zu erstellen. Dies ist ein generisches Konto, das nicht an einen bestimmten Benutzer in Ihrem Unternehmen gebunden ist oder mit diesem verknüpft ist. Dieser Typ von API-Benutzerkonto hilft Ihnen bei der Erreichung von zwei Aspekten:

  • Identifizieren Sie, welchen Dienst API aufruft (z. B. Aufrufe Ihrer Apps, die APIs verwenden, oder von anderen Tools, die API-Anforderungen stellen).
  • Stellen Sie unterbrechungsfreien Zugriff auf die APIs bereit. Ein an eine bestimmte Person gebundenes Konto kann gelöscht werden, wenn sie Ihre Firma verlässt. Dadurch wird verhindert, dass Sie mit dem verfügbaren API-Code arbeiten. Ein generisches Konto, das nicht an einen bestimmten Mitarbeiter gebunden ist, hilft Ihnen, dieses Problem zu vermeiden.

Als Beispiel oder Anwendungsfall für diesen Kontotyp sollten Sie z. B. mehrere Segmente gleichzeitig mit den Massenverwaltungswerkzeugen ändern. Dazu benötigt Ihr Benutzerkonto API Zugriff. Anstatt einem bestimmten Benutzer Berechtigungen hinzuzufügen, erstellen Sie ein unspezifisches API-Benutzerkonto, das über die entsprechenden Anmeldeinformationen, den entsprechenden Schlüssel und das geheime Schlüssel zum Durchführen von API-Aufrufen verfügt. Dies ist auch nützlich, wenn Sie eigene Anwendungen entwickeln, die Audience Manager APIs verwenden.

Arbeiten Sie mit Ihrem Audience Manager-Berater zusammen, um ein generisches API-Benutzerkonto einzurichten, das nur für Benutzer gültig ist.

Arbeitsablauf für die Kennwortauthentifizierung

Kennwort-Authentifizierung sicher Zugriff auf unser REST API. Die folgenden Schritte beschreiben den Arbeitsablauf für die Kennwortauthentifizierung von einem JSON-Client in Ihrem Browser.

TIPP

Verschlüsseln Sie den Zugriff und aktualisieren Sie Token, wenn Sie sie in einer Datenbank speichern.

Schritt 1: Zugriff anfordern API

Wenden Sie sich an Ihren Partner Solutions Manager. Sie erhalten eine API Client-ID und ein geheimes Kennwort. Die ID und das Geheimnis authentifizieren Sie sich beim API.

Hinweis: Wenn Sie ein Aktualisierungstoken erhalten möchten, geben Sie an, dass, wenn Sie API-Zugriff anfordern.

Schritt 2: Token anfordern

Geben Sie eine Token-Anforderung mit Ihrem bevorzugten JSON-Client weiter. Beim Erstellen der Anforderung:

  • Verwenden Sie eine POST-Methode, um https://api.demdex.com/oauth/token aufzurufen.
  • 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 können die Anmeldeinformationen testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert werden.
  • Geben Sie die HTTP headers Authorization:Basic <base-64 clientID:clientSecret> und Content-Type: application/x-www-form-urlencoded ein. Ihre Kopfzeile könnte z. B. wie folgt aussehen:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Richten Sie den Anforderungstext wie folgt ein:

    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Schritt 3: Token empfangen

Die Antwort JSON 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 Taste expires_in gibt die Anzahl der Sekunden an, bis das Zugriffstoken abläuft. Als Best Practice sollten Sie kurze Ablaufzeiten verwenden, um die Exposition zu begrenzen, wenn das Token jemals offen gelegt wird.

Token aktualisieren

Token aktualisieren verlängern den API-Zugriff, nachdem das ursprüngliche Token abgelaufen ist. Bei Bedarf enthält die Antwort JSON im Passwortarbeitsablauf ein Aktualisierungstoken. Wenn Sie kein Aktualisierungstoken erhalten, erstellen Sie mithilfe der Kennwortauthentifizierung 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 Arbeitsablauf für die Verwendung eines Aktualisierungstokens zum Erstellen eines neuen Zugriffstokens von einem JSON-Client in Ihrem Browser.

Schritt 1: Neues Token anfordern

Geben Sie eine Aktualisierungstoken-Anforderung mit Ihrem bevorzugten JSON-Client weiter. Beim Erstellen der Anforderung:

  • Verwenden Sie eine POST-Methode, um https://api.demdex.com/oauth/token aufzurufen.
  • 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 können die Anmeldeinformationen testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert werden.
  • Geben Sie die HTTP-Header Authorization:Basic <base-64 clientID:clientSecret> und Content-Type: application/x-www-form-urlencoded ein. Ihre Kopfzeile könnte z. B. wie folgt aussehen:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Geben Sie im Anforderungstext das grant_type:refresh_token an und geben Sie das Aktualisierungstoken ein, das Sie in Ihrer vorherigen Zugriffsanforderung erhalten haben. Die Anfrage sollte wie folgt aussehen:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Schritt 2: Neues Token erhalten

Die Antwort JSON 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

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 anmelden, um Zugriff auf Token zu erhalten und sie zu aktualisieren.

Authentifizierte API Anforderungen

Voraussetzungen für den Aufruf der API-Methoden, nachdem Sie ein Authentifizierungstoken erhalten haben.

Aufrufe mit den verfügbaren API-Methoden ausführen:

  • Legen Sie in der Kopfzeile HTTP Authorization: Bearer <token> fest.
  • Bei Verwendung der JWT (Dienstkonto)-Authentifizierung müssen Sie die x-api-key-Kopfzeile angeben, die mit der client_id übereinstimmt. Sie können Ihr client_id auf der Seite Adobe I/O integration abrufen.
  • Rufen Sie die erforderliche API-Methode auf.

Optionale API Abfragen-Parameter

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-Methoden verwenden, die alle-Eigenschaften für ein Objekt zurückgeben. Legen Sie diese Optionen in der Anforderungszeichenfolge fest, wenn diese Abfrage an das API übergeben wird.

Parameter Beschreibung
page Gibt Ergebnisse nach Seitenzahl zurück. Nummerierung von Beginn bei 0.
pageSize Legt die Anzahl der Antwortergebnisse fest, die von der Anforderung zurückgegeben werden (10 ist standardmäßig).
sortBy Sortiert Ergebnisse und gibt sie entsprechend der angegebenen JSON-Eigenschaft zurück.
descending Sortiert die Ergebnisse und gibt sie in absteigender Reihenfolge zurück. ascending ist Standard.
search Gibt Ergebnisse basierend auf der angegebenen Zeichenfolge zurück, die Sie als Suchparameter verwenden möchten. Nehmen wir beispielsweise an, Sie möchten Ergebnisse für alle Modelle suchen, die das Wort "Test"in einem der Wertefelder für dieses Element enthalten. Ihre Musteranforderung könnte wie folgt aussehen: GET https://aam.adobe.io/v1/models/?search=Test. Sie können nach jedem Wert suchen, der von einer "get all"-Methode zurückgegeben wird.
folderId Gibt alle IDs für traits innerhalb des angegebenen Ordners zurück. Nicht für alle Methoden verfügbar.
permissions Gibt eine Liste von Segmenten basierend auf der angegebenen Berechtigung zurück. READ ist Standard. Zu den Berechtigungen gehören:
  • READ : Rückgabe- und Segmentinformationen zur Ansicht.
  • WRITE : Aktualisieren Sie PUT ein Segment.
  • CREATE : Erstellen Sie POST ein Segment.
  • DELETE : Segmente löschen. Erfordert Zugriff auf zugrunde liegende Eigenschaften, falls vorhanden. Sie benötigen beispielsweise Rechte zum Löschen der Eigenschaften, die zu einem Segment gehören, wenn Sie es entfernen möchten.

Geben Sie mehrere Berechtigungen mit separaten Schlüssel/Wert-Paaren an. Um beispielsweise eine Liste von Segmenten mit READ- und WRITE-Berechtigungen zurückzugeben, geben Sie "permissions":"READ", "permissions":"WRITE" ein.
includePermissions (Boolean) Auf true setzen, um Ihre Berechtigungen für das Segment zurückzugeben. Standardwert ist false.

Hinweis zu Seitenoptionen

Wenn die Seiteninformationen nicht angegeben sind, gibt die Anforderung Nur JSON zurück, was zu einem Array führt. Wenn die Seiteninformationen angegeben sind, wird die zurückgegebene Liste in ein JSON-Objekt eingeschlossen, das Informationen zum Gesamtergebnis und zur aktuellen Seite enthält. Ihre Musteranforderung mit Seitenoptionen könnte wie folgt aussehen:

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

API URLs

URLs für Anforderungen, Staging- und Produktions-Umgebung und Versionen.

Anfrage URLs

Die folgende Tabelle Liste die Anforderung URLs, die zum Übergeben von API-Anforderungen verwendet wird, nach Methode.

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

Anforderung URLs für JWT Authentifizierung

API Methoden Anfrage URL
Algorithmic Modeling https://aam.adobe.io/v1/models/
Data Source https://aam.adobe.io/v1/datasources/
Derived Signals https://aam.adobe.io/v1/signals/derived/
Destinations https://aam.adobe.io/v1/destinations/
Domains https://aam.adobe.io/v1/partner-sites/
Folders Eigenschaften: https://aam.adobe.io/v1/folders/traits /
Segmente: https://aam.adobe.io/v1/folders/segments /
Schema https://aam.adobe.io/v1/schemas/
Segments https://aam.adobe.io/v1/segments/
Traits https://aam.adobe.io/v1/traits/
Trait Types https://aam.adobe.io/v1/customer-trait-types
Taxonomy https://aam.adobe.io/v1/taxonomies/0/

Anforderung URLs für OAuth Authentifizierung (nicht mehr unterstützt)

API Methoden Anfrage URL
Algorithmic Modeling https://api.demdex.com/v1/models/
Data Source https://api.demdex.com/v1/datasources/
Derived Signals https://api.demdex.com/v1/signals/derived/
Destinations https://api.demdex.com/v1/destinations/
Domains https://api.demdex.com/v1/partner-sites/
Folders Eigenschaften: https://api.demdex.com/v1/folders/traits /
Segmente: https://api.demdex.com/v1/folders/segments /
Schema https://api.demdex.com/v1/schemas/
Segments https://api.demdex.com/v1/segments/
Traits https://api.demdex.com/v1/traits/
Trait Types https://api.demdex.com/v1/customer-trait-types
Taxonomy https://api.demdex.com/v1/taxonomies/0/

Umgebung

Die Audience Manager APIs bieten Zugriff auf verschiedene funktionierende Umgebung. Diese Umgebung helfen Ihnen, Code mit separaten Datenbanken zu testen, ohne dass sich dies auf die Live-Produktionsdaten auswirkt. In der folgenden Tabelle werden die verfügbaren API-Umgebung und die entsprechenden Ressourcen-Hostnamen Liste.

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

Umgebung Hostname für JWT Authentifizierung Hostname für OAuth Authentifizierung
Produktion https://aam.adobe.io/... https://api.demdex.com/...
Beta https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
HINWEIS

Die Beta-Umgebung Audience Manager ist eine kleinere, eigenständige Version der Umgebung. Alle Daten, die Sie testen möchten, müssen in diese Umgebung eingegeben und gesammelt werden.

Versionen

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

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

Antwortcodes definiert

HTTP Statuscodes und Antworttext, der vom Audience Manager REST API.

Antwortcode-ID Antworttext Definition
200 OK Die Anforderung wurde erfolgreich verarbeitet. Gibt bei Bedarf erwartete Inhalte oder Daten zurück.
201 Created Die Ressource wurde erstellt. Gibt für PUT- und POST-Anforderungen zurück.
204 No Content Die Ressource wurde gelöscht. Der Antwortkörper ist leer.
400 Bad Request Der Server hat die Anforderung nicht verstanden. In der Regel aufgrund einer fehlerhaften Syntax. Überprüfen Sie Ihre Anforderung und versuchen Sie es erneut.
403 Forbidden Sie haben keinen Zugriff auf die Ressource.
404 Not Found Die Ressource konnte für den angegebenen Pfad nicht gefunden werden.
409 Conflict Die Anforderung konnte aufgrund eines Konflikts mit dem Zustand der Ressource nicht abgeschlossen werden.
500 Server Error Auf dem Server ist ein unerwarteter Fehler aufgetreten, durch den die Anforderung nicht erfüllt werden konnte.

Auf dieser Seite

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free