Guide de l’API Catalog Service

Le Catalog Serviceest le système d’enregistrement pour l’emplacement et la parenté des données au sein d’Adobe Experience Platform. Catalog agit comme un magasin de métadonnées ou un "catalogue" dans lequel vous pouvez trouver des informations sur vos données Experience Platform, sans avoir à accéder aux données elles-mêmes. Pour plus d’informations, consultez la Catalog présentation .

Ce guide du développeur décrit les étapes à suivre pour commencer à utiliser l'API Catalog. Le guide fournit ensuite des exemples d’appels API pour effectuer des opérations clés à l’aide de Catalog.

Conditions préalables

Catalog effectue le suivi des métadonnées pour plusieurs types de ressources et d’opérations dans Experience Platform. Ce guide de développement nécessite une compréhension pratique des différents services Experience Platform impliqués dans la création et la gestion de ces ressources :

  • Experience Data Model (XDM) : cadre normalisé selon lequel Platform organise les données de l’expérience client.
  • Ingestion par lots Experience Platform : méthode d’ingestion et de stockage de données de fichiers, par exemple de type CSV et Parquet, dans
  • Ingestion par flux : Comment Experience Platform ingère et stocke des données à partir de périphériques côté client et côté serveur en temps réel.

Les sections suivantes apportent des informations supplémentaires que vous devrez connaître ou dont vous devrez disposer pour passer avec succès des appels à l’API Catalog Service.

Lecture d'exemples d'appels API

Ce guide fournit des exemples d'appels API pour démontrer comment formater vos requêtes. Il s'agit notamment de chemins d'accès, d'en-têtes requis et de payloads de requêtes correctement formatés. L'exemple JSON renvoyé dans les réponses de l'API est également fourni. Pour plus d'informations sur les conventions utilisées dans la documentation pour les exemples d'appels d'API, voir la section concernant la lecture d'exemples d'appels d'API dans le guide de dépannageExperience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API Platform, vous devez d'abord suivre le tutoriel d'authentification. Le tutoriel d'authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d'API Experience Platform, comme indiqué ci-dessous :

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key : {API_KEY}
  • x-gw-ims-org-id : {IMS_ORG}

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

  • x-sandbox-name : {SANDBOX_NAME}
REMARQUE

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

Toutes les requêtes contenant un payload (POST, PUT, PATCH) requièrent un en-tête supplémentaire :

  • Content-Type: application/json

Bonnes pratiques relatives aux appels d’API Catalog

Lors de l’exécution de requêtes de GET à l’API Catalog, la bonne pratique consiste à inclure des paramètres de requête dans vos requêtes afin de renvoyer uniquement les objets et les propriétés dont vous avez besoin. Les requêtes non filtrées peuvent entraîner des payloads de réponse supérieurs à 3 Go, ce qui peut ralentir les performances globales.

Vous pouvez afficher des objets spécifiques en incluant leurs identifiants dans le chemin d’accès à la requête ou utiliser des paramètres de requête tels que properties et limit pour filtrer les réponses. Les filtres peuvent être transmis sous forme d’en-têtes et de paramètres de requête, les filtres transmis sous forme de paramètres de requête prévalant sur les autres. Pour plus d’informations, consultez le document sur le filtrage des données du catalogue.

Comme certaines requêtes peuvent imposer une charge importante à l’API, des limites globales ont été mises en oeuvre sur les requêtes Catalog afin de prendre davantage en charge les bonnes pratiques.

Étapes suivantes

Ce document couvrait les connaissances préalables requises pour effectuer des appels à l’API Catalog. Vous pouvez désormais procéder aux exemples d'appel fournis dans ce guide de développement et suivre leurs instructions.

La plupart des exemples de ce guide utilisent le point de terminaison /dataSets, mais les principes peuvent être appliqués à d’autres points de terminaison dans Catalog (comme /batches et /accounts). Consultez la référence de l’API Catalog Service pour obtenir une liste complète de tous les appels et opérations disponibles pour chaque point de terminaison.

Pour un processus détaillé qui montre comment l’API Catalog est impliquée dans l’ingestion de données, consultez le tutoriel sur la création d’un jeu de données.

Sur cette page