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 sert de banque de métadonnées ou de « 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érents services Experience Platform impliqués dans la création et la gestion de ces ressources :
- Experience Data Model (XDM) : cadre normalisé selon lequel Experience Platform organise les données de l’expérience client.
- Ingestion par lots : méthode dExperience Platformingestion et de stockage de données à partir de fichiers de données, tels que CSV et Parquet.
- Ingestion par flux : méthode dExperience Platformingestion et de stockage de données en temps réel à partir d’appareils côté client et côté serveur.
Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin 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épannage Experience Platform.
Collecte des valeurs des en-têtes requis
Pour lancer des appels aux API Experience 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 Experience 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 appels d’API Catalog
Lors de l’exécution de requêtes GET vers l’API Catalog, il est recommandé d’inclure des paramètres de requête dans vos requêtes afin de renvoyer uniquement les objets et 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 surcharger l’API, des limites globales ont été implémentées sur les requêtes Catalog afin de prendre 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 le point d’entrée /dataSets, mais les principes peuvent être appliqués à d’autres points d’entrée dans Catalog (tels que /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 explique 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.