Show Menu
SUJETS×

Getting Started with REST APIs

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

Configuration requise et recommandations pour l’API

Les choses que vous devez faire et que vous devez faire lorsque vous travaillez avec les Audience Manager APIs.
Tenez compte des points suivants lorsque vous utilisez le code de l’API Audience Manager :
  • Paramètres de requête : tous les paramètres de requête sont requis, sauf indication contraire.
  • En-têtes de demande : lorsque vous utilisez des jetons d'E/S Adobe, vous devez fournir l' x-api-key en-tête. Vous pouvez obtenir votre API clé en suivant les instructions de la page d’intégration du compte de service.
  • JSONtype de contenu : Spécifiez content-type: application/json et ** accept: application/json dans votre code.
  • Demandes et réponses : Envoie les requêtes sous la forme d’un JSON objet correctement formaté. Audience Manager répond par des données JSON formatées. Les réponses du serveur peuvent contenir des données demandées, un code d’état ou les deux.
  • Accès : Votre Audience Manager consultant vous fournira un ID de client et une clé qui vous permettront de faire API des demandes.
  • Documentation et exemples de code : Le texte en italique représente une variable que vous fournissez ou transmettez lors de la création ou de la réception de API données. Remplacez le texte en italique par votre propre code, paramètres ou autres informations requises.

Authentification

Le Audience Manager​REST APIs prend en charge deux méthodes d’authentification.
Selon votre méthode d’authentification, vous devez ajuster votre requête URLs en conséquence. Consultez la section Environnements pour plus d’informations sur les noms d’hôtes à utiliser.

JWT (Service AccountAuthentification par E/S Adobe

Présentation des E/S Adobe

Adobe I/O est l'écosystème et la communauté du développement de l'Adobe. Il comprend les outils de développement d'E/S Adobe, les API et les API pour tous les produits d'Adobe.
Il s’agit de la méthode recommandée pour configurer et utiliser Adobe​APIs.

Conditions préalables

Avant de pouvoir configurer JWT l'authentification, assurez-vous d'avoir accès à la console de développement des Adobes dans les E/S Adobes. Contactez l’administrateur de votre organisation pour obtenir des demandes d’accès.

Authentification

Suivez les étapes ci-dessous pour configurer JWT (Service Account) l’authentification à l’aide Adobe I/O:
  1. Connectez-vous à la Console développeur Adobe.
  2. Suivez les étapes décrites dans Connexion au compte de service.
  3. Essayez la connexion en effectuant votre premier API appel en fonction des instructions de l' étape 3 .
Pour configurer et travailler avec le Audience Manager​REST APIs de manière automatisée, vous pouvez générer le fichier JWT par programmation. Voir Authentification JWT.md JWT (Service Account) pour obtenir des instructions détaillées.

OAuth Authentification (obsolète)

Audience Manager REST API l’authentification et le renouvellement des jetons par OAuth 2.0 l’intermédiaire de est désormais obsolète.
Utilisez plutôt l'authentification #jwt-service-account-authentication-jwt JWT (Service Account).
Le Audience Manager​REST API suit OAuth 2.0 les normes d’authentification et de renouvellement des jetons. Les sections ci-dessous décrivent comment vous authentifier et début en utilisant les APIs.

Créer un API utilisateur générique

Nous vous recommandons de créer un compte utilisateur technique distinct pour travailler avec les Audience Manager APIs. Il s’agit d’un compte générique qui n’est pas lié ou associé à un utilisateur spécifique de votre organisation. Ce type de compte API utilisateur vous permet d’accomplir deux tâches :
  • Identifiez le service qui appelle le API (par exemple, les appels de vos applications qui utilisent nos APIapplications ou d'autres outils qui effectuent des API demandes).
  • Fournir un accès ininterrompu aux APIs. Un compte lié à une personne spécifique peut être supprimé lorsqu'il quitte votre société. Cela vous empêchera de travailler avec le API code disponible. Un compte générique qui n’est pas lié à un employé particulier permet d’éviter ce problème.
À titre d'exemple ou de cas d'utilisation pour ce type de compte, supposons que vous souhaitiez modifier un grand nombre de segments à la fois avec les outils de gestion en bloc. Eh bien, pour ce faire, votre compte d'utilisateur a besoin d' API accès. Plutôt que d’ajouter des autorisations à un utilisateur spécifique, créez un compte d’ API utilisateur non spécifique doté des informations d’identification, de la clé et du secret appropriés pour effectuer API des appels. Cela s'avère également utile si vous développez vos propres applications qui utilisent les Audience Manager applications APIs.
Contactez votre Audience Manager consultant pour configurer un compte d’utilisateur générique APIuniquement.

Workflow d’authentification de mot de passe

L'authentification par mot de passe sécurise l'accès à notre REST APIsite. Les étapes ci-dessous décrivent le processus d’authentification par mot de passe d’un JSON client de votre navigateur.
Chiffrez l’accès et actualisez les jetons si vous les stockez dans une base de données.

Étape 1 : Demande API d'accès

Contactez votre responsable Solutions partenaires. Ils vous fourniront un ID API client et un secret. L’ID et le secret vous authentifient auprès du API.
Remarque : Si vous souhaitez recevoir un jeton actualisé, indiquez-le lorsque vous demandez l’ API accès.

Étape 2 : Demander le jeton

Transmettez une demande de jeton à votre JSON client préféré. Lorsque vous créez la requête :
  • Utilisez une POST méthode pour appeler https://api.demdex.com/oauth/token .
  • Convertissez votre ID client et votre secret en chaîne codée en base 64. Séparez l’ID et le secret à l’aide de deux points au cours du processus de conversion. Par exemple, les informations d’identification testId : testSecret sont converties en dGVzdElkOnRlc3RTZWNyZXQ= .
  • Passez la HTTP​headers Authorization:Basic <base-64 clientID:clientSecret> et Content-Type: application/x-www-form-urlencoded . Par exemple, votre en-tête peut ressembler à ceci :
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Configurez le corps de la demande comme suit :
    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Étape 3 : Recevoir le jeton

La JSON réponse contient votre jeton d'accès. La réponse doit se présenter comme suit :
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

La expires_in clé représente le nombre de secondes avant l’expiration du jeton d'accès. Il est recommandé d’utiliser de courts délais d’expiration pour limiter l’exposition si le jeton est un jour exposé.

Actualiser le jeton

Actualisez les jetons pour renouveler API l’accès après l’expiration du jeton d’origine. Si cela est demandé, la réponse JSON du flux de travail des mots de passe inclut un jeton actualisé. Si vous ne recevez pas de jeton actualisé, créez-en un nouveau par le biais du processus d’authentification par mot de passe.
Vous pouvez également utiliser un jeton actualisé pour générer un nouveau jeton avant l’expiration du jeton d'accès existant.
Si votre jeton d'accès a expiré, vous recevez un en-tête 401 Status Code et l’en-tête suivants dans la réponse :
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
Les étapes suivantes décrivent le processus d’utilisation d’un jeton d’actualisation pour créer un jeton d'accès à partir d’un JSON client dans votre navigateur.

Étape 1 : Demander le nouveau jeton

Transférez une demande de jeton actualisé avec votre JSON client préféré. Lorsque vous créez la requête :
  • Utilisez une POST méthode pour appeler https://api.demdex.com/oauth/token .
  • Convertissez votre ID client et votre secret en chaîne codée en base 64. Séparez l’ID et le secret à l’aide de deux points au cours du processus de conversion. Par exemple, les informations d’identification testId : testSecret sont converties en dGVzdElkOnRlc3RTZWNyZXQ= .
  • Transmettez les en-têtes HTTP Authorization:Basic <base-64 clientID:clientSecret> et Content-Type: application/x-www-form-urlencoded . Par exemple, votre en-tête peut ressembler à ceci :
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Dans le corps de la requête, spécifiez le jeton grant_type:refresh_token actualisé que vous avez reçu dans votre précédente requête d’accès et transmettez-le. La demande doit se présenter comme suit :
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Étape 2 : Recevoir le nouveau jeton

La JSON réponse contient votre nouveau jeton d'accès. La réponse doit se présenter comme suit :
{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Code d’autorisation et authentification implicite

Le Audience Manager​REST API prend en charge le code d’autorisation et l’authentification implicite. Pour utiliser ces méthodes d’accès, les utilisateurs doivent se connecter pour accéder https://api.demdex.com/oauth/authorize et actualiser les jetons.

Faire des API requêtes authentifiées

Conditions requises pour appeler API les méthodes après réception d’un jeton d’authentification.
Pour lancer des appels par rapport aux API méthodes disponibles :
  • Dans l’ HTTP en-tête, définissez Authorization: Bearer <token> .
  • Lors de l’utilisation de l’authentification JWT (Service AccountAuthentification par E/S Adobe JWT (Service Account), vous devez fournir l’ x-api-key en-tête, qui sera identique à celui de votre client_id compte. Vous pouvez accéder à votre client_id demande à partir de la page d'intégration des E/S Adobe.
  • Appelez la API méthode requise.

Paramètres API de Requête facultatifs

Définissez les paramètres facultatifs disponibles pour les méthodes qui renvoient toutes les propriétés d’un objet.
Vous pouvez utiliser ces paramètres facultatifs avec API des méthodes qui renvoient toutes les propriétés d’un objet. Définissez ces options dans la chaîne de requête lors de la transmission de cette requête à la API.
Paramètre
Description
page
Renvoie les résultats par numéro de page. Débuts de numérotation à 0.
pageSize
Définit le nombre de résultats de réponse renvoyés par la requête (10 est la valeur par défaut).
sortBy
Trie et renvoie les résultats selon la JSON propriété spécifiée.
descending
Trie et renvoie les résultats dans l’ordre décroissant. ascending est définie par défaut.
search
Renvoie des résultats basés sur la chaîne spécifiée que vous souhaitez utiliser comme paramètre de recherche. Supposons, par exemple, que vous souhaitiez trouver des résultats pour tous les modèles qui contiennent le mot "Test" dans l’un des champs de valeur de cet élément. Votre exemple de demande peut se présenter comme suit : GET https://aam.adobe.io/v1/models/?search=Test . Vous pouvez rechercher n’importe quelle valeur renvoyée par une méthode "get all".
folderId
Renvoie tous les ID pour traits le dossier spécifié. Non disponible pour toutes les méthodes.
permissions
Renvoie une liste de segments basée sur l’autorisation spécifiée. READ est définie par défaut. Les autorisations comprennent :
  • READ : Informations de retour et de vue sur un segment.
  • WRITE : Permet PUT de mettre à jour un segment.
  • CREATE : Utilisez POST pour créer un segment.
  • DELETE : Suppression d’un segment. Nécessite l'accès aux caractéristiques sous-jacentes, le cas échéant. Par exemple, vous aurez besoin de droits pour supprimer les caractéristiques qui appartiennent à un segment si vous souhaitez le supprimer.
Spécifiez plusieurs autorisations avec des paires clé-valeur distinctes. Par exemple, pour renvoyer une liste de segments avec READ et WRITE des autorisations uniquement, transmettez "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Boolean) Définissez cette variable sur true pour renvoyer vos autorisations pour le segment. La valeur par défaut est false .

Remarque concernant les options de page

Lorsque les informations de page ne sont pas spécifiées, la requête renvoie des résultats simples JSON dans un tableau. Si des informations sur la page sont spécifiées, la liste renvoyée est encapsulée dans un JSON objet contenant des informations sur le résultat total et la page active. Votre exemple de requête utilisant les options de page peut ressembler à ceci :
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs pour les demandes, les environnements d’évaluation et de production et les versions.

Demande URLs

Le tableau suivant liste la requête URLs utilisée pour transmettre API des requêtes, par méthode.
Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre requête URLs en fonction des tableaux ci-dessous.

Demande URLs d’ JWT authentification

API Méthodes
Demande 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
Caractéristiques : https://aam.adobe.io/v1/folders/traits /
Segments : 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/

Demande URLs d’ OAuth authentification (obsolète)

API Méthodes
Demande 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
Caractéristiques : https://api.demdex.com/v1/folders/traits /
Segments : 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/

Environnements

Les Audience Manager s APIpermettent d'accéder à différents environnements de travail. Ces environnements vous aident à tester le code par rapport à des bases de données distinctes sans affecter les données de production en direct. Le tableau suivant liste les API environnements disponibles et les noms d’hôte de ressources correspondants.
Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre environnement URLs en fonction du tableau ci-dessous.
Environnement
Nom d’hôte pour l’ JWT authentification
Nom d’hôte pour l’ OAuth authentification
Production
https://aam.adobe.io/...
https://api.demdex.com/...
Bêta
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
L'environnement Audience Manager bêta est une version autonome à plus petite échelle de l'environnement de production. Toutes les données à tester doivent être entrées et collectées dans cet environnement.

Versions

De nouvelles versions de ces APIlogiciels sont publiées régulièrement. Une nouvelle version incrémente le numéro de API version. Le numéro de version est référencé dans la requête URL , comme v<version number> indiqué dans l’exemple suivant :
https://<host>/v1/...

Définition des codes de réponse

HTTP les codes d’état et le texte de réponse renvoyés par le Audience Manager​REST API.
ID de code de réponse
Texte de la réponse
Définition
200
OK
La demande a été traitée avec succès. Renverra le contenu ou les données attendus si nécessaire.
201
Created
La ressource a été créée. Renvoie pour PUT et POST les requêtes.
204
No Content
La ressource a été supprimée. Le corps de la réponse sera vide.
400
Bad Request
Le serveur n'a pas compris la demande. Généralement en raison d’une syntaxe incorrecte. Vérifiez votre demande et réessayez.
403
Forbidden
Vous n'avez pas accès à la ressource.
404
Not Found
Impossible de trouver la ressource pour le chemin spécifié.
409
Conflict
Impossible de terminer la demande en raison d'un conflit avec l'état de la ressource.
500
Server Error
Le serveur a rencontré une erreur inattendue qui l'a empêchée de répondre à la demande.