Prise en main de REST APIs

Informations sur les exigences générales, l'authentification, les paramètres de requête facultatifs, la demande URLs et d'autres références.

Configuration requise et recommandations pour l’API

Ce que vous devez et devez faire lorsque vous travaillez avec les Audience Manager APIs.

Tenez compte des points suivants lorsque vous utilisez le code Audience Manager API :

• Paramètres de requête : tous les paramètres de requête sont obligatoires, sauf indication contraire.
• En-têtes de demande : lorsque vous utilisez Adobe I/ Otokens, vous devez fournir l’ x-api-key en-tête. Vous pouvez obtenir votre clé API en suivant les instructions de la page Intégration du compte de service.
• JSONtype de contenu : indiquez content-type: application/json ** accept: application/json et dans votre code.
• Requêtes et réponses : envoie des 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 d’effectuer des API requêtes.
• Documentation et exemples de code : Le texte en ** italiques représente une variable que vous fournissez ou transmettez lors de la création ou de la réception de API données. Remplacez italicised texte par votre propre code, paramètres ou toute autre information requise.

Authentification

Audience Manager REST APIs prend en charge deux méthodes d'authentification.

• Authentification JWT (Service Account) à l’aide d’ Adobe I/O. Adobe I/O est l'écosystème et la communauté du développement de l'Adobe. Il comprend les API des développeurs Adobe I/O et API pour tous les produits d'Adobe. Il s’agit de la méthode recommandée pour configurer et utiliser Adobe APIs.
• Authentification OAuth (désapprouvée). Bien que cette méthode soit obsolète, les clients avec des intégrations OAuth existantes peuvent continuer à utiliser cette méthode.

JWT (Service AccountAuthentification via Adobe I/O)

Aperçu de Adobe I/O

Adobe I/O est l'écosystème et la communauté du développement de l'Adobe. Il comprend les API des développeurs Adobe I/O et 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 l'authentification JWT, assurez-vous d'avoir accès à la Console développeur d'Adobes dans Adobe I/O. Contactez l’administrateur de votre organisation pour obtenir des demandes d’accès.

Authentification

Suivez les étapes ci-dessous pour configurer l'authentification JWT (Service Account) à l'aide de Adobe I/O :

1. Connectez-vous à Adobe Developer Console.
2. Suivez les étapes décrites dans Service Account Connection.
   • Au cours de l'étape 2: Ajoutez une API à votre projet à l’aide de l’authentification du compte de service , sélectionnez l’option Audience Manager API.
3. Essayez la connexion en effectuant votre premier appel API en fonction des instructions de l'étape 3.

OAuth Authentification (obsolète)

Audience Manager REST API suit les normes OAuth 2.0 pour l’authentification et le renouvellement des jetons. Les sections ci-dessous décrivent comment vous authentifier et début en utilisant les APIs.

Créer un utilisateur générique API

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 utilisateur API permet d’accomplir 2 tâches :

• Identifiez le service qui appelle API (par exemple, les appels de vos applications qui utilisent nos APIs ou d'autres outils qui effectuent des demandes API).
• Fournissez 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 code API 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 plusieurs segments à la fois avec les outils de gestion en bloc. Pour ce faire, votre compte utilisateur doit disposer d’un accès API. Plutôt que d'ajouter des autorisations à un utilisateur spécifique, créez un compte utilisateur API non spécifique disposant des informations d'identification, de la clé et du secret appropriés pour effectuer des appels API. Cela s'avère également utile si vous développez vos propres applications qui utilisent les Audience Manager APIs.

Contactez votre consultant Audience Manager pour configurer un compte utilisateur générique API uniquement.

Workflow d'authentification de mot de passe

L'authentification par mot de passe sécurise l'accès à REST API. Les étapes ci-dessous décrivent le processus d'authentification par mot de passe d'un client JSON dans votre navigateur.

Étape 1 : Demande d'accès API

Contactez votre responsable Solutions partenaires. Ils vous fourniront un API identifiant client et un secret. L'ID et le secret vous authentifient dans API.

Remarque : Si vous souhaitez recevoir un jeton actualisé, indiquez-le lorsque vous demandez l’accès API.

Étape 2 : Demander le jeton

Transférez une demande de jeton avec votre client JSON préféré. Lorsque vous créez la requête :

• Utilisez une méthode POST 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 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 réponse JSON 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 clé expires_in 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 nécessaire, la réponse JSON dans le flux de travail des mots de passe comprend 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 401 Status Code et l'en-tête suivant 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 actualisé pour créer un jeton d'accès à partir d’un client JSON dans votre navigateur.

Étape 1 : Demander le nouveau jeton

Transférez une demande de jeton actualisé avec votre client JSON préféré. Lorsque vous créez la requête :

• Utilisez une méthode POST 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 grant_type:refresh_token et transmettez le jeton actualisé que vous avez reçu dans votre précédente requête d’accès. 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 réponse JSON 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

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

Faire des demandes authentifiées API

Exigences relatives à l'appel des méthodes API après réception d'un jeton d'authentification.

Pour lancer des appels à l'aide des méthodes API disponibles :

• Dans l'en-tête HTTP, définissez Authorization: Bearer <token>.
• Lorsque vous utilisez JWT (Service Account) Authentication, vous devez fournir l'en-tête x-api-key, qui sera identique à votre client_id. Vous pouvez obtenir votre client_id à partir de la page Intégration Adobe I/O.
• Appelez la méthode API requise.

Paramètres de Requête API 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 des méthodes API qui renvoient les propriétés all pour un objet. Définissez ces options dans la chaîne de requête lorsque vous transmettez cette requête à 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 propriété JSON 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 effectuer une recherche sur toute valeur renvoyée par une méthode "get all".
folderId	Renvoie tous les ID de traits dans 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 : Utilisez PUT pour 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 les autorisations READ et WRITE uniquement, transmettez "permissions":"READ", "permissions":"WRITE" .
includePermissions	(Boolean) Définissez ce paramètre 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 plain JSON résulte en un tableau. Si les informations de page sont spécifiées, la liste renvoyée est encapsulée dans un objet JSON 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 des requêtes API, 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'authentification JWT

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'authentification OAuth (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 APIs permettent 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 environnements API 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'authentification JWT	Nom d'hôte pour l'authentification OAuth
Production	https://aam.adobe.io/...	https://api.demdex.com/...
Bêta	https://aam-beta.adobe.io/...	https://api-beta.demdex.com/...

Versions

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

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

Codes de réponse définis

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 les requêtes PUT et POST.
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.