Guide de l’API Catalog Service
Le Catalog Service est 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 dans Experience Platform, sans avoir à accéder aux données elles-mêmes. Pour plus d’informations, consultez la Catalog présentation.
Ce guide de développement 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érentes Experience Platform services 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 contiennent des informations supplémentaires que vous devrez connaître ou dont vous devrez disposer pour passer avec succès des appels à la fonction Catalog Service API.
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épannage Experience 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 :
{ORG_ID}
Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes envoyées aux API Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération sera effectuée :
- x-sandbox-name :
{SANDBOX_NAME}
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 Catalog Appels API
Lors de l’exécution de requêtes de GET à la variable Catalog API, 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 Catalog requêtes afin de prendre davantage en charge les bonnes pratiques.
Étapes suivantes
Dans ce document, vous avez découvert les connaissances préalables requises pour effectuer des appels vers 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 la méthode /dataSets mais les principes peuvent s’appliquer à d’autres points de terminaison dans Catalog (par exemple /batches). 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 d’entrée.
Pour un workflow détaillé qui montre comment la variable Catalog L’API est impliquée dans l’ingestion de données. Pour plus d’informations, consultez le tutoriel sur création d’un jeu de données.