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.

WICHTIG

Abhängig von Ihrer Authentifizierungsmethode müssen Sie Ihre Anfrage anpassen URLs entsprechend. Siehe Umgebungen für Details zu den Hostnamen, die Sie verwenden sollten.

JWT (Service Account) Authentifizierung mit Adobe Developer

Adobe Developer - Überblick

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 Console 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 Console.
  2. Führen Sie die Schritte unter Service-Konto-Verbindung.
  3. Probieren Sie die Verbindung aus, indem Sie Ihre erste API -Aufruf basierend auf den Anweisungen von Schritt 3.
HINWEIS

So konfigurieren und verwenden Sie die Audience Manager REST APIs In automatisierter Weise können Sie die JWT programmiert. Siehe JWT-Authentifizierung (Dienstkonto) für detaillierte Anweisungen.

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.

    technisches Konto

  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)

WARNUNG

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

Verwenden Sie JWT-Authentifizierung (Dienstkonto) anstatt.

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.

TIPP

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

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:

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.

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 Ergebnisse gemäß den angegebenen zurück JSON -Eigenschaft.
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 einemget all".
folderId Gibt alle IDs für traits innerhalb des angegebenen Ordners. 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 : Verwendung PUT , um ein Segment zu aktualisieren.
  • CREATE : Verwendung POST , um ein Segment zu erstellen.
  • 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. So geben Sie beispielsweise eine Liste von Segmenten mit READ und WRITE nur Berechtigungen, weitergeben "permissions":"READ", "permissions":"WRITE" .
includePermissions (Boolean) Legen Sie true , um Ihre Berechtigungen für das Segment zurückzugeben. Standardwert ist false.

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

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 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.

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 Audience Manager Die Beta-Umgebung 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 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.

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 -Anfragen.
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