Show Menu
THEMEN×

Getting Started with REST APIs

Information about general requirements, authentication, optional query parameters, request URLs, and other references.

API-Anforderungen und -Empfehlungen

Was Sie tun müssen und sollten, wenn Sie mit den Audience Manager APIs arbeiten.
Beachten Sie beim Arbeiten mit Audience Manager-API -Code Folgendes:
  • Anforderungsparameter: alle Anforderungsparameter sind erforderlich, sofern nicht anders angegeben.
  • Anforderungsheader : Wenn Sie Adobe-E/A -Token verwenden, 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 und geben Sie Ihren Code ein accept: application/json .
  • 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.
  • Dokumentation und Codebeispiele: Text in Kursivschrift stellt eine Variable dar, die Sie beim Herstellen oder Empfangen von API Daten angeben oder übermitteln. Ersetzen Sie kursiv gedruckten Text durch Ihren eigenen Code, Ihre eigenen Parameter oder andere erforderliche Informationen.

Authentifizierung

Die Audience Manager Unterstützung REST APIs umfasst zwei Authentifizierungsmethoden.
Je nach 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-E/A

Adobe-E/A-Übersicht

Adobe I/O ist das Entwicklerökosystem und die Community der Adobe. Es enthält die Adobe-E/A-Entwicklerwerkzeuge sowie APIs und APIs für alle Adobe-Produkte .
Dies ist die empfohlene Art der Einrichtung und Verwendung Adobe​APIs.

Voraussetzungen

Bevor Sie die JWT Authentifizierung konfigurieren können, stellen Sie sicher, dass Sie Zugriff auf die Adobe Developer Console in der 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 mithilfe Adobe I/Oder folgenden Schritte zu konfigurieren:
  1. Melden Sie sich bei der 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 gemäß den Anweisungen in Schritt 3 tätigen.
Um die Konfiguration und die Arbeit mit der Audience Manager​REST APIs automatisiert zu gestalten, können Sie die JWT programmgesteuert generieren. Detaillierte Anweisungen finden Sie unter JWT-Authentifizierung (Dienstkontoauthentifizierung).

OAuth Authentifizierung (nicht mehr unterstützt)

Audience Manager REST API Token-Authentifizierung und -Erneuerung über OAuth 2.0 ist jetzt veraltet.
Bitte verwenden Sie stattdessen die JWT-Authentifizierung (Dienstkonto).
Die Audience Manager Variable REST API entspricht den OAuth 2.0 Standards für die Token-Authentifizierung und -Erneuerung. In den folgenden Abschnitten wird beschrieben, wie Sie sich authentifizieren und Beginn mit den APIs arbeiten.

Generischen API Benutzer erstellen

Es wird empfohlen, ein separates technisches Benutzerkonto für die Arbeit mit den Audience Manager s einzurichten. APIEs wird empfohlen. Dies ist ein generisches Konto, das nicht an einen bestimmten Benutzer in Ihrem Unternehmen gebunden ist oder mit diesem verknüpft ist. Mit diesem API Benutzerkonto können Sie zwei Dinge erreichen:
  • Identifizieren Sie, welcher Dienst den Dienst aufruft API (z. B. Aufrufe von Apps, die unsere APIs verwenden, oder von anderen Tools, die Anforderungen API stellen).
  • Gewähren Sie ununterbrochenen Zugriff auf die APIs. 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.
Beispiel oder Anwendungsfall für diesen Kontotyp: Sie möchten mit den Massenverwaltungstools viele Segmente gleichzeitig ändern. Um dies zu tun, muss Ihr Benutzerkonto API Zugriff haben. 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 API Aufrufen verfügt. Dies ist auch nützlich, wenn Sie eigene Anwendungen entwickeln, die die Audience Manager APIs verwenden.
Arbeiten Sie mit Ihrem Audience Manager Berater zusammen, um ein generisches, APIausschließlich-benutzerkonto einzurichten.

Arbeitsablauf für die Kennwortauthentifizierung

Passwortauthentifizierung sicher Zugriff auf unsere REST API. Die folgenden Schritte beschreiben den Arbeitsablauf für die Kennwortauthentifizierung von einem JSON Client in Ihrem Browser.
Verschlüsseln Sie den Zugriff und aktualisieren Sie Token, wenn Sie sie in einer Datenbank speichern.

Schritt 1: Zugriff API anfordern

Wenden Sie sich an Ihren Partner Solutions Manager. Sie geben Ihnen eine API Client-ID und ein Geheimnis. Die ID und das Geheimnis authentifizieren Sie sich beim API.
Hinweis: Wenn Sie ein Aktualisierungstoken erhalten möchten, geben Sie dies an, wenn Sie den API Zugriff anfordern.

Schritt 2: Token anfordern

Geben Sie eine Token-Anforderung an Ihren bevorzugten JSON Client weiter. Beim Erstellen der Anforderung:
  • 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 werden die Anmeldeinformationen testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert.
  • Übergeben Sie die HTTP und headers Authorization:Basic <base-64 clientID:clientSecret> Content-Type: application/x-www-form-urlencoded . 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 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"
}

Der expires_in Schlüssel 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 erneuern den API Zugriff, nachdem das ursprüngliche Token abgelaufen ist. Bei Anforderung 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 an Ihren bevorzugten JSON Client weiter. Beim Erstellen der Anforderung:
  • 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 werden die Anmeldeinformationen testId : testSecret in dGVzdElkOnRlc3RTZWNyZXQ= konvertiert.
  • Übergeben Sie die HTTP-Header Authorization:Basic <base-64 clientID:clientSecret> und Content-Type: application/x-www-form-urlencoded . Ihre Kopfzeile könnte z. B. wie folgt aussehen:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Geben Sie im Anforderungstext das Aktualisierungstoken an, das Sie in Ihrer vorherigen Zugriffsanforderung erhalten haben, grant_type:refresh_token und übergeben Sie es an. Die Anfrage sollte wie folgt aussehen:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Schritt 2: Neues Token erhalten

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 Unterstützung REST API von Autorisierungscode und impliziter Authentifizierung. Um diese Zugriffsmethoden verwenden zu können, müssen sich Ihre Benutzer anmelden, um Zugriff auf Token zu erhalten und sie zu aktualisieren. https://api.demdex.com/oauth/authorize

Authentifizierte API Anforderungen erstellen

Voraussetzungen für den Aufruf von API Methoden nach Erhalt eines Authentifizierungstokens.
Aufrufe anhand der verfügbaren API Methoden durchzuführen:
  • Legen Sie in der HTTP Kopfzeile Authorization: Bearer <token> fest.
  • Bei Verwendung der JWT-Authentifizierung (Dienstkontoauthentifizierung) müssen Sie die x-api-key Kopfzeile angeben, die mit der Ihrer identisch ist client_id . Sie können Ihre Daten client_id von der Adobe-I/O-Integrationsseite abrufen.
  • Rufen Sie die erforderliche API Methode auf.

Optionale API Abfrage-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 die 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 den angegebenen Ordner 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 : Verwenden Sie POST zum Erstellen eines Segments.
  • 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 nur WRITE Berechtigungen zurückzugeben, geben Sie "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Boolean) Legen Sie fest, dass true Sie Ihre Berechtigungen für das Segment zurückgeben. Standardwert ist false .

Hinweis zu Seitenoptionen

Wenn keine Seiteninformationen angegeben werden, gibt die Anforderung Nur- JSON Ergebnisse in einem Array zurück. Wenn Seiteninformationen angegeben werden , 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

In der folgenden Tabelle wird die Anforderung URLs für die Übermittlung von API Anforderungen nach Methode Liste.
Je nach der von Ihnen verwendeten Authentifizierungsmethode müssen Sie Ihre Anforderung URLs entsprechend den unten stehenden Tabellen anpassen.

Anfrage URLs zur 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 zur OAuth Authentifizierung (überholt)

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 Arbeitsabläufe APIbieten Zugang zu verschiedenen 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.
Je nach der von Ihnen 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/...
Die Audience Manager Beta-Umgebung 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 APIDateien werden regelmäßig veröffentlicht. Bei einer neuen Version wird die API Versionsnummer inkrementiert. Die Versionsnummer wird in der Anforderung URL wie im folgenden Beispiel gezeigt v<version number> angegeben:
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.