Show Menu
THEMEN×

Erste Schritte mit REST-APIs

Informationen zu allgemeinen Anforderungen, Authentifizierung, optionalen Parametern für die Abfrage, Anforderungs-URLs und anderen Verweisen.

API-Anforderungen und -Empfehlungen

Was Sie bei der Arbeit mit Audience Manager APItun müssen und sollten.
Beachten Sie beim Arbeiten mit dem API-Code für Audience Manager Folgendes:
  • Anforderungsparameter: Sofern nicht anders angegeben, sind alle Anforderungsparameter erforderlich.
  • 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 REST-APIs von Audience Manager unterstützen zwei Authentifizierungsmethoden.
Je nach Authentifizierungsmethode müssen Sie die Anforderungs-URLs entsprechend anpassen. Einzelheiten zu den zu verwendenden Hostnamen finden Sie im Abschnitt Umgebung .

JWT-Authentifizierung (Dienstkonto)

Voraussetzungen

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

Authentifizierung

Gehen Sie wie folgt vor, um die JWT-Authentifizierung (Service Account) 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 durchführen.
Um die Audience Manager-REST-APIs automatisiert zu konfigurieren und zu verwenden, können Sie die JWT programmgesteuert generieren. Detaillierte Anweisungen finden Sie unter JWT-Authentifizierung (Dienstkontoauthentifizierung).

OAuth-Authentifizierung (überholt)

Authentifizierung und Erneuerung von Audience Manager- REST API Token über OAuth 2.0 ist jetzt veraltet.
Bitte verwenden Sie stattdessen die JWT-Authentifizierung (Dienstkonto).
Der Audience Manager 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.

Erstellen eines generischen API-Benutzers

Es wird empfohlen, ein separates technisches Benutzerkonto für die Arbeit mit Audience Manager APIeinzurichten. 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 Audience Manager APIverwenden.
Wenden Sie sich an Ihren Audience Manager-Berater, um ein generisches APIBenutzerkonto 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: API-Zugriff 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.
  • Geben Sie die HTTP Kopfzeilen 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
  • 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

Audience Manager REST API unterstützt Autorisierungscode und implizite 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 erhalten Ihre Daten client_id auf der Seite zur Adobe-E/A-Integration .
  • 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
Seite
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.
absteigend
Sortiert die Ergebnisse und gibt sie in absteigender Reihenfolge zurück. Aufsteigend ist der Standardwert.
Suche
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 der Methode "get all"zurückgegeben wird.
folderId
Gibt alle IDs für Eigenschaften im angegebenen Ordner zurück. Nicht für alle Methoden verfügbar.
Berechtigungen
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
(Boolescher Wert) Auf "true"setzen, um die Berechtigungen für das Segment zurückzugeben. Standard 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.

URLs anfordern

In der folgenden Tabelle werden die Anforderungs-URLs, die zum Übergeben von API Anforderungen verwendet werden, nach Methode Liste.
Je nach der von Ihnen verwendeten Authentifizierungsmethode müssen Sie die Anforderungs-URLs entsprechend den unten stehenden Tabellen anpassen.

URLs für die JWT-Authentifizierung anfordern

API Methoden
Anfrage URL
Algorithmisches Modellieren
https://aam.adobe.io/v1/models/
Datenquelle
https://aam.adobe.io/v1/datasources/
Abgeleitete Signale
https://aam.adobe.io/v1/signals/derived/
Ziele
https://aam.adobe.io/v1/destinations/
Domänen
https://aam.adobe.io/v1/partner-sites/
Ordner
Eigenschaften: https://aam.adobe.io/v1/folders/traits /
Segmente: https://aam.adobe.io/v1/folders/segments /
Schema
https://aam.adobe.io/v1/schemas/
Segmente
https://aam.adobe.io/v1/segments/
Eigenschaften
https://aam.adobe.io/v1/traits/
Eigenschaftstypen
https://aam.adobe.io/v1/customer-trait-types
Taxonomie
https://aam.adobe.io/v1/taxonomies/0/

Anfordern von URLs für die OAuth-Authentifizierung (nicht mehr unterstützt)

API Methoden
Anfrage URL
Algorithmisches Modellieren
https://api.demdex.com/v1/models/
Datenquelle
https://api.demdex.com/v1/datasources/
Abgeleitete Signale
https://api.demdex.com/v1/signals/derived/
Ziele
https://api.demdex.com/v1/destinations/
Domänen
https://api.demdex.com/v1/partner-sites/
Ordner
Eigenschaften: https://api.demdex.com/v1/folders/traits /
Segmente: https://api.demdex.com/v1/folders/segments /
Schema
https://api.demdex.com/v1/schemas/
Segmente
https://api.demdex.com/v1/segments/
Eigenschaften
https://api.demdex.com/v1/traits/
Eigenschaftstypen
https://api.demdex.com/v1/customer-trait-types
Taxonomie
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 die URLs Ihrer Umgebung 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 Beta-Umgebung von 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 APIDateien werden regelmäßig veröffentlicht. Bei einer neuen Version wird die API Versionsnummer inkrementiert. Die Versionsnummer wird in der Anforderungs-URL referenziert, wie im folgenden Beispiel gezeigt v<version number> :
https://<host>/v1/...

Antwortcodes definiert

HTTP Statuscodes und Antworttext, der vom Audience Manager zurückgegeben wird REST API.
Antwortcode-ID
Antworttext
Definition
200
OK-
Die Anforderung wurde erfolgreich verarbeitet. Gibt bei Bedarf erwartete Inhalte oder Daten zurück.
201
Erstellt
Die Ressource wurde erstellt. Gibt für PUT und POST Anforderungen zurück.
204
Kein Inhalt
Die Ressource wurde gelöscht. Der Antwortkörper ist leer.
400
Unzulässige Anfrage
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
Verboten
Sie haben keinen Zugriff auf die Ressource.
404
nicht gefunden
Die Ressource konnte für den angegebenen Pfad nicht gefunden werden.
409
Konflikt
Die Anforderung konnte aufgrund eines Konflikts mit dem Zustand der Ressource nicht abgeschlossen werden.
500
Serverfehler
Auf dem Server ist ein unerwarteter Fehler aufgetreten, durch den die Anforderung nicht erfüllt werden konnte.