Informations sur les exigences générales, authentification, paramètres de requête facultatifs, requête URLs, ainsi que d’autres références.
Ce que vous devez faire et devez faire lorsque vous utilisez le Audience Manager APIs.
Notez ce qui suit lorsque vous utilisez API d’Audience Manager code :
x-api-key
en-tête . Vous pouvez obtenir votre API en suivant les instructions de la section Intégration de compte de service page.content-type: application/json
et accept: application/json
dans votre code.Le Audience Manager REST APIs prennent en charge deux méthodes d’authentification.
Selon votre méthode d’authentification, vous devez ajuster votre requête. URLs en conséquence. Voir Environnements pour plus d’informations sur les noms d’hôtes que vous devez utiliser.
Adobe Developer est l’écosystème de développement et la communauté de l’Adobe. Elle comprend API pour tous les produits Adobe.
Il s’agit de la méthode recommandée pour configurer et utiliser Adobe APIs.
Avant de pouvoir configurer JWT authentification, assurez-vous que vous avez accès au Console Adobe Developer in Adobe Developer. Contactez l’administrateur de votre entreprise pour les demandes d’accès.
Suivez les étapes ci-dessous pour configurer JWT (Service Account) authentification Adobe Developer:
Pour configurer et utiliser le Audience Manager REST APIs de manière automatisée, vous pouvez générer la variable JWT par programmation. Voir Authentification JWT (compte de service) pour obtenir des instructions détaillées.
Si votre compte d’Audience Manager utilise Contrôle d’accès en fonction du rôle, vous devez créer un compte utilisateur technique d’Audience Manager et l’ajouter au groupe RBAC d’Audience Manager qui effectuera les appels d’API.
Pour créer un compte d’utilisateur technique et l’ajouter à un groupe RBAC, procédez comme suit :
Effectuez une GET
appel à https://aam.adobe.io/v1/users/self
. L’appel crée un compte d’utilisateur technique que vous pouvez voir dans la variable Admin Console, dans la variable Users page.
Connectez-vous à votre compte d’Audience Manager et ajouter le compte utilisateur technique au groupe d’utilisateurs qui effectuera les appels d’API.
Audience Manager REST API authentification et renouvellement des jetons via OAuth 2.0 est désormais obsolète.
Veuillez utiliser Authentification JWT (compte de service) au lieu de .
Le Audience Manager REST API following OAuth 2.0 normes d’authentification et de renouvellement des jetons. Les sections ci-dessous décrivent comment vous authentifier et commencer à utiliser le APIs.
Nous vous recommandons de créer un compte d’utilisateur technique distinct pour utiliser la variable 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 entreprise. Ce type de API Le compte utilisateur vous permet d’accomplir 2 tâches :
Par exemple, pour ce type de compte, supposons que vous souhaitiez modifier de nombreux segments à la fois avec la variable Outils de gestion en bloc. Pour ce faire, votre compte d’utilisateur doit API accès. Au lieu d’ajouter des autorisations à un utilisateur spécifique, créez un API compte utilisateur disposant des informations d’identification, de la clé et du secret appropriés pour créer API appels . Cela s’avère également utile si vous développez vos propres applications qui utilisent la variable Audience Manager APIs.
Travaillez avec votre Audience Manager consultant pour configurer une variable générique, APIcompte utilisateur uniquement.
Authentification par mot de passe sécurisé REST API. Les étapes ci-dessous décrivent le processus d’authentification par mot de passe à partir d’un JSON dans votre navigateur.
Chiffrez l’accès et actualisez les jetons si vous les stockez dans une base de données.
Contactez votre responsable Partenaires en solutions . Ils vous fourniront un API ID client et secret. L’identifiant et le secret vous authentifient dans la variable API.
Remarque : Si vous souhaitez recevoir un jeton d’actualisation, indiquez-le lorsque vous demandez API accès.
Transmettre une requête de jeton avec vos préférences JSON client. Lorsque vous créez la requête :
POST
méthode d’appel https://api.demdex.com/oauth/token
.testId : testSecret
convertir en dGVzdElkOnRlc3RTZWNyZXQ=
.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
grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
Le JSON La 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"
}
Le expires_in
key représente le nombre de secondes jusqu’à l’expiration du jeton d’accès. Pour respecter les bonnes pratiques, utilisez de courts délais d’expiration pour limiter l’exposition si le jeton est un jour exposé.
Actualiser le renouvellement des jetons API accéder après l’expiration du jeton d’origine. Si nécessaire, la réponse JSON dans le workflow du mot de passe, inclut un jeton d’actualisation. Si vous ne recevez pas de jeton d’actualisation, créez-en un nouveau par le biais du processus d’authentification par mot de passe.
Vous pouvez également utiliser un jeton d’actualisation 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 d’actualisation pour créer un jeton d’accès à partir d’un JSON dans votre navigateur.
Transmettez une requête de jeton d’actualisation avec vos préférences. JSON client. Lorsque vous créez la requête :
POST
méthode d’appel https://api.demdex.com/oauth/token
.testId : testSecret
convertir en dGVzdElkOnRlc3RTZWNyZXQ=
.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
grant_type:refresh_token
et transmettez le jeton d’actualisation que vous avez reçu dans votre demande d’accès précédente. La requête doit se présenter comme suit : grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
Le JSON La 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"
}
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 à https://api.demdex.com/oauth/authorize
pour accéder aux jetons et les actualiser.
Conditions requises pour l’appel API une fois que vous avez reçu un jeton d’authentification.
Pour lancer des appels par rapport à la disponibilité API methods:
HTTP
header, set Authorization: Bearer <token>
.x-api-key
qui sera identique à votre client_id
. Vous pouvez obtenir votre client_id
de la Intégration d’Adobe Developer page.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 méthodes renvoyées all 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 variable API.
Paramètre | Description |
---|---|
page |
Renvoie les résultats par numéro de page. La numérotation commence à 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 en fonction des JSON . |
descending |
Trie et renvoie les résultats dans l’ordre décroissant. ascending est la valeur par défaut. |
search |
Renvoie des résultats en fonction de la chaîne spécifiée que vous souhaitez utiliser comme paramètre de recherche. Par exemple, supposons que vous souhaitiez trouver des résultats pour tous les modèles ayant le mot "Test" dans l’un des champs de valeur de cet élément. Votre exemple de requête peut ressembler à ceci : GET https://aam.adobe.io/v1/models/?search=Test . Vous pouvez rechercher n’importe quelle valeur renvoyée par un "get all". |
folderId |
Renvoie tous les identifiants pour 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 la valeur par défaut. Les autorisations incluent :
Spécifiez plusieurs autorisations avec des paires clé-valeur distinctes. Par exemple, pour renvoyer une liste de segments avec READ et WRITE autorisations uniquement, transmettre "permissions":"READ" , "permissions":"WRITE" . |
includePermissions |
(Boolean) Défini sur true pour renvoyer vos autorisations pour le segment. La valeur par défaut est false . |
Lorsque des informations de page n’est pas spécifié, la requête renvoie plain JSON donne un tableau. Si des informations sur la page is spécifié, alors la liste renvoyée est encapsulée dans une 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
URLs pour les demandes, les environnements d’évaluation et de production, ainsi que les versions.
Le tableau suivant répertorie la requête. URLs utilisé pour transmettre API requêtes, par méthode.
Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre requête. URLs selon les tableaux ci-dessous.
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/ |
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/ |
Le 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 répertorie les API environnements et noms d’hôtes de ressources correspondants.
Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre environnement. URLs selon le tableau ci-dessous.
Environnement | Nom d’hôte pour JWT authentication | Nom d’hôte pour OAuth authentication |
---|---|---|
Production | https://aam.adobe.io/... |
https://api.demdex.com/... |
Beta | https://aam-beta.adobe.io/... |
https://api-beta.demdex.com/... |
Le Audience Manager L’environnement bêta est une version autonome à plus petite échelle de l’environnement de production. Toutes les données que vous souhaitez tester doivent être entrées et collectées dans cet environnement.
Nouvelles versions de ces APIs sont publiés selon un calendrier régulier. Une nouvelle version incrémente le API numéro de version. Le numéro de version est référencé dans la requête. URL as v<version number>
comme illustré dans l’exemple suivant :
https://<host>/v1/...
HTTP
codes d’état et texte de réponse renvoyés par la variable Audience Manager REST API.
Identifiant de code de réponse | Texte de la réponse | Définition |
---|---|---|
200 |
OK |
La requête a été traitée avec succès. Renvoie le contenu ou les données attendus, le cas échéant. |
201 |
Created |
La ressource a été créée. Renvoie pour PUT et POST 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 requête. Généralement en raison d’une syntaxe incorrecte. Vérifiez votre requête, puis réessayez. |
403 |
Forbidden |
Vous n’avez pas accès à la ressource. |
404 |
Not Found |
La ressource est introuvable pour le chemin spécifié. |
409 |
Conflict |
Impossible de terminer la requête 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é de répondre à la demande. |