Prise en main des API Adobe Experience Platform

Adobe Experience Platform est développé selon la philosophie « API first ». Grâce aux API d’Experience Platform, vous pouvez effectuer par programmation des opérations CRUD (Create, Read, Update, Delete) de base sur les données, comme configurer des attributs calculés, accéder à des données/entités, exporter des données, supprimer des données ou des lots inutiles, etc.

Les API de chaque service Experience Platform partagent toutes le même ensemble d’en-têtes d’authentification et utilisent des syntaxes similaires pour leurs opérations CRUD. Le guide suivant décrit les étapes nécessaires à la prise en main des API d’Experience Platform.

Authentification et en-têtes

Pour passer avec succès des appels à des points d’entrée Experience Platform, vous devez suivre le tutoriel authentification. Le tutoriel sur l’authentification indique les valeurs de chacun des en-têtes requis dans les appels API Experience Platform, comme illustré ci-dessous :

En-tête Sandbox

Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Les requêtes envoyées aux API Experience Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération sera effectuée :

Pour plus d’informations sur les sandbox dans Experience Platform, consultez la documentation de présentation des sandbox.

En-tête de type de contenu

Toutes les requêtes ayant un payload dans le corps de la requête (notamment les appels POST, PUT et PATCH) doivent comporter un en-tête Content-Type. Les valeurs acceptées sont spécifiques à chaque point d’entrée de l’API. Si une valeur d’Content-Type spécifique est nécessaire pour un point d’entrée, sa valeur s’affiche dans les exemples de requêtes d’API fournis par les guides d’API pour les services Experience Platform individuels.

Principes fondamentaux des API d’Experience Platform

Les API Adobe Experience Platform utilisent plusieurs technologies et syntaxes sous-jacentes importantes à comprendre pour gérer efficacement les ressources Experience Platform.

Pour en savoir plus sur les technologies d’API sous-jacentes utilisées par Experience Platform, y compris des exemples d’objets de schéma JSON, consultez le guide Principes de base de l’API Experience Platform.

Collections Postman pour les API Experience Platform

Postman est une plateforme de collaboration pour le développement d’API qui vous permet de configurer des environnements avec des variables prédéfinies, de partager des collections d’API, de rationaliser les requêtes CRUD, etc. La plupart des services d’API Experience Platform possèdent des collections Postman qui peuvent être utilisées pour faciliter l’émission d’appels d’API.

Pour en savoir plus sur Postman, notamment sur la configuration d’un environnement, sur une liste des collections disponibles et sur l’importation de collections, consultez la documentation Experience Platform Postman.

Lecture d’exemples d’appels API sample-api

Les formats de requête varient selon l’API Experience Platform utilisée. Le meilleur moyen d’apprendre à structurer vos appels API est de suivre les exemples fournis dans la documentation du service Experience Platform que vous utilisez.

La documentation de Experience Platform présente les exemples d’appels API de deux manières différentes. Tout d’abord, l’appel est présenté dans son format d’API, qui consiste en une représentation de modèle affichant uniquement l’opération (GET, POST, PUT, PATCH, DELETE) et le point d’entrée utilisé (par exemple /global/classes). Certains modèles indiquent également l’emplacement des variables pour mieux illustrer la manière dont un appel doit être formulé, comme par exemple GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

Les appels sont ensuite affichés sous forme de commandes cURL dans une Requête, qui comprend les en-têtes nécessaires et le « chemin racine » complet indispensable pour que l’interaction avec l’API soit réussie. Le chemin racine doit être ajouté à tous les points d’entrée. Par exemple, le point d’entrée /global/classes cité plus haut devient https://platform.adobe.io/data/foundation/schemaregistry/global/classes. Le format/modèle de requête de l’API est visible dans toute la documentation et vous devez utiliser le chemin d’accès complet illustré dans l’exemple de requête lorsque vous effectuez vos propres appels vers les API Experience Platform.

Exemple de requête API

Voici un exemple de requête API illustrant le format que vous rencontrerez dans la documentation.

Format d’API

Le format d’API affiche l’opération (GET) et le point d’entrée utilisé. Les variables sont indiquées par des accolades (ici {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Requête

Dans cet exemple de requête, les variables du format API reçoivent des valeurs réelles dans le chemin de la requête. En outre, tous les en-têtes requis s’affichent sous la forme d’exemples de valeurs d’en-tête ou de variables où des informations sensibles (telles que des jetons de sécurité et des identifiants d’accès) doivent être incluses.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse

La réponse illustre ce que vous vous attendez à recevoir après un appel réussi vers l’API en fonction de la requête envoyée. Parfois, la réponse est tronquée en raison d’un espace insuffisant, il est donc possible que vous voyiez plus d’informations ou des informations supplémentaires par rapport à ce qui est affiché dans l’échantillon.

{
    "results": [
        {
            "title": "XDM ExperienceEvent",
            "$id": "https://ns.adobe.com/xdm/context/experienceevent",
            "meta:altId": "_xdm.context.experienceevent",
            "version": "1"
        },
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile",
            "meta:altId": "_xdm.context.profile",
            "version": "1"
        }
    ],
    "_links": {}
}

Messages d’erreur

Le guide de dépannage d’Experience Platform fournit une liste des erreurs que vous pouvez rencontrer lors de l’utilisation d’un service Experience Platform.

Pour obtenir un guide de dépannage concernant un service Experience Platform spécifique, consultez le répertoire de dépannage des services.

Pour plus d’informations sur les points d’entrée spécifiques dans les API Experience Platform, y compris les en-têtes requis et les corps de requête, consultez les guides de l’API Experience Platform.

Guides de l’API Experience Platform api-guides

Pour plus d’informations sur les points d’entrée et opérations spécifiques disponibles pour chaque service, consultez la documentation de référence sur les API sur Adobe I/O.

Étapes suivantes

Ce document présente les en-têtes requis, les guides disponibles et fournit un exemple d’appel API. Maintenant que vous disposez des valeurs d’en-tête requises pour effectuer des appels API sur Adobe Experience Platform, sélectionnez un point d’entrée d’API que vous souhaitez explorer dans le tableau Guides de l’API Experience Platform.

Pour obtenir des réponses aux questions fréquentes, reportez-vous au guide de dépannage d’Experience Platform.

Pour configurer un environnement Postman et explorer les collections Postman disponibles, reportez-vous au guide Experience Platform Postman.