Erste Schritte mit REST APIs

Informationen zu allgemeinen Anforderungen, Authentifizierung, optionalen Abfrageparametern, Anforderung URLs und anderen Verweisen.

API-Anforderungen und -Empfehlungen

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

Beachten Sie Folgendes beim Arbeiten mit dem Code Audience Manager-API:

  • Anforderungsparameter: Alle Anforderungsparameter sind erforderlich, sofern nicht anders angegeben.
  • Anforderungsheader: bei Verwendung von Adobe I/ Token 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 und Ihren Code an.
  • Anforderungen und Antworten: Anforderungen als ordnungsgemäß formatiertes JSON Objekt senden. 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 Anfragen stellen können.
  • Dokumentation und Codebeispiele: Text in ** Kursivschrift stellt eine Variable dar, die Sie beim Erstellen oder Empfangen von API Daten bereitstellen oder übergeben. Ersetzen Sie den Text kursiv durch Ihren eigenen Code, Ihre eigenen Parameter oder andere erforderliche Informationen.

Authentifizierung

Audience Manager REST APIs unterstützt zwei Authentifizierungsmethoden.

WICHTIG

Abhängig von Ihrer Authentifizierungsmethode müssen Sie Ihre Anfrage URLs entsprechend anpassen. Weitere Informationen zu den Hostnamen, die Sie verwenden sollten, finden Sie im Abschnitt Umgebungen .

JWT (Service Account) Authentifizierung mit Adobe I/O

Übersicht über Adoben I/O

Adobe I/O ist das Entwickler-Ökosystem und die Community der Adobe. Sie enthält die Adobe I/O-Entwicklertools und -APIs und APIs für alle Adobe-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 Organisationsadministrator.

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 Dienstkontenverbindung aus.
  3. Probieren Sie die Verbindung aus, indem Sie Ihren ersten API-Aufruf anhand der Anweisungen von Schritt 3 ausführen.
HINWEIS

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

OAuth Authentifizierung (veraltet)

WARNUNG

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

Verwenden Sie stattdessen JWT (Service Account) Authentication .

Der Audience Manager REST API folgt OAuth 2.0-Standards für die Token-Authentifizierung und -Erneuerung. In den folgenden Abschnitten wird beschrieben, wie Sie sich authentifizieren und mit den APIs 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. Mit diesem Benutzerkonto von API können Sie zwei Dinge erreichen:

  • Ermitteln Sie, welcher Dienst die API aufruft (z. B. Aufrufe aus Ihren Apps, die unsere APIs verwenden, oder aus anderen Tools, die API-Anfragen stellen).
  • Gewähren Sie unterbrechungsfreien 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 dem verfügbaren API-Code arbeiten. 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 den Tools für die Massenverwaltung ändern. Dazu benötigt Ihr Benutzerkonto API Zugriff. Anstatt einem bestimmten Benutzer Berechtigungen hinzuzufügen, erstellen Sie ein unspezifisches API-Benutzerkonto mit den entsprechenden Anmeldeinformationen, Schlüsseln und Geheimnissen, um API-Aufrufe durchzuführen. 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 allgemeines, ausschließlich API-Benutzerkonto einzurichten.

Workflow zur Kennwortauthentifizierung

Passwortauthentifizierung sicher Zugriff auf REST API. Die folgenden Schritte beschreiben den Workflow 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 Geheimnis. Die Kennung und das Geheimnis authentifizieren Sie bei API.

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

Schritt 2: Token anfordern

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

  • 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 werden die Anmeldedaten testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert.
  • Ü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 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"
}

Der Schlüssel expires_in stellt die Anzahl der Sekunden dar, 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 verlängern den API-Zugriff, nachdem das ursprüngliche Token abgelaufen ist. Bei Bedarf enthält die Antwort JSON 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 einen 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 Sie eine Aktualisierungs-Token-Anfrage mit Ihrem bevorzugten JSON-Client. Wenn Sie die Anforderung erstellen:

  • 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 werden die Anmeldedaten testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert.
  • Übergeben Sie die HTTP-Header 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 grant_type:refresh_token an und übergeben Sie das Aktualisierungstoken, 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 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 stellen

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

So stellen Sie Aufrufe für die verfügbaren API-Methoden bereit:

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

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

Parameter Beschreibung
page Gibt Ergebnisse nach Seitenzahl zurück. Die Nummerierung beginnt bei 0.
pageSize Legt die Anzahl der von der Anfrage zurückgegebenen Antwortergebnisse fest (standardmäßig 10).
sortBy Sortiert Ergebnisse und gibt sie gemäß der angegebenen JSON-Eigenschaft zurück.
descending Sortiert 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. Angenommen, Sie möchten Ergebnisse für alle Modelle mit dem Wort "Test"in einem der Wertefelder für dieses Element finden. Ihre Beispielanfrage 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 : Zurückgeben und Anzeigen von Informationen zu einem Segment.
  • WRITE : Verwenden Sie PUT zum Aktualisieren eines Segments.
  • CREATE : Verwenden Sie POST zum Erstellen eines Segments.
  • DELETE : Segmente löschen. Erfordert Zugriff auf zugrunde liegende Eigenschaften, falls vorhanden. Beispielsweise benötigen Sie Berechtigungen 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.

Ein Hinweis zu Seitenoptionen

Wenn die Seiteninformationen nicht angegeben sind, gibt die Anforderung nur JSON zurück und führt zu einem Array. 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 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 Anfrage URLs auf, die zum Übergeben von API-Anforderungen verwendet wird, nach Methode.

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

Anfrage 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/

Anfrage URLs für OAuth Authentifizierung (veraltet)

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/

Umgebungen

Die Audience Manager APIs bieten 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 aufgeführt.

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 Produktionsumgebung. Alle Daten, die Sie testen möchten, müssen in dieser Umgebung eingegeben und erfasst 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 Anfrage URL als v<version number> referenziert, wie im folgenden Beispiel gezeigt:

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

Definierte Antwortcodes

HTTP Status-Codes und Antworttext, der vom Audience Manager REST APIzurückgegeben wird.

Antwort-Code-ID Antworttext Definition
200 OK Die Anfrage 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 Antworttext ist leer.
400 Bad Request Der Server hat die Anfrage nicht verstanden. In der Regel aufgrund einer fehlerhaften Syntax. Überprüfen Sie Ihre Anfrage 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 Anfrage konnte aufgrund eines Konflikts mit dem Status der Ressource nicht abgeschlossen werden.
500 Server Error Auf dem Server ist ein unerwarteter Fehler aufgetreten, der die Erfüllung der Anforderung verhinderte.

Auf dieser Seite