Activez les audiences vers des destinations basées sur des fichiers à l’aide de l’API Flow Service
Utilisez les fonctionnalités améliorées d’exportation de fichiers pour accéder à la fonctionnalité de personnalisation améliorée lors de l’exportation de fichiers en dehors d’Experience Platform :
- Options de dénomination de fichier supplémentaires.
- Possibilité de définir des en-têtes de fichier personnalisés dans vos fichiers exportés via l’étape de mappage améliorée.
- Possibilité de sélectionner le type de fichier fichier exporté.
- Possibilité de personnaliser le formatage des fichiers de données CSV exportés.
Cette fonctionnalité est prise en charge par les six cartes de stockage dans le cloud répertoriées ci-dessous :
Cet article explique le processus requis pour utiliser l’API Flow Service afin d’exporter des profils qualifiés de Adobe Experience Platform vers l’un des emplacements de stockage dans le cloud liés ci-dessus.
Prise en main get-started
Ce guide nécessite une compréhension du fonctionnement des composants suivants de Adobe Experience Platform :
- Experience Data Model (XDM) System : Cadre normalisé selon lequel Experience Platform organise les données de l’expérience client.
- Segmentation Service : crée Adobe Experience Platform Segmentation Service des audiences dans Adobe Experience Platform à partir de vos données Real-Time Customer Profile.
- Sandboxes : Experience Platform fournit des sandbox virtuels qui divisent une instance Experience Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.
Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin pour activer des données vers des destinations basées sur des fichiers dans Experience Platform.
Autorisations nécessaires permissions
Pour exporter des profils, vous avez besoin des autorisations de contrôle d’accès Afficher les destinations, Activer les destinations, Afficher les profils et Afficher les segments 🔗. Lisez la présentation du contrôle d’accès ou contactez votre administrateur ou administratrice du produit pour obtenir les autorisations requises.
Pour exporter des identités, vous devez disposer de l’autorisation de contrôle d’accès Afficher le graphique d’identités 🔗.
Lecture d’exemples d’appels API reading-sample-api-calls
Ce tutoriel 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.
Collecter des valeurs pour les en-têtes obligatoires et facultatifs gather-values-headers
Pour lancer des appels aux API Experience Platform, vous devez d’abord suivre le tutoriel Authentification Experience Platform. 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}
Les ressources dans Experience Platform peuvent être isolées dans des sandbox spécifiques. Dans les requêtes aux API Experience Platform, vous pouvez spécifier le nom et l’identifiant du sandbox dans lequel l’opération aura lieu. Il s’agit de paramètres facultatifs.
- x-sandbox-name :
{SANDBOX_NAME}
Toutes les requêtes contenant une payload (POST, PUT, PATCH) nécessitent un en-tête de type de média supplémentaire :
- Content-Type:
application/json
Documentation de référence sur les API api-reference-documentation
Ce tutoriel vous permet de trouver la documentation de référence relative à toutes les opérations API. Consultez la documentation de l’API Flow Service - Destinations sur le site web d’Adobe Developer. Nous vous recommandons de consulter ce tutoriel et la documentation de référence sur les API en parallèle.
Glossaire glossary
Pour obtenir une description des termes que vous rencontrerez dans ce tutoriel sur l’API, consultez la section glossaire de la documentation de référence de l’API.
Sélectionner la destination où exporter les audiences select-destination
Avant de démarrer le workflow d’exportation de profils, identifiez la spécification de connexion et les identifiants de spécification de flux de la destination vers laquelle vous avez l’intention d’exporter des audiences. Utilisez le tableau ci-dessous à titre de référence.
4fce964d-3f37-408f-9778-e597338a21ee1a0514a6-33d4-4c7f-aff8-594799c475496d6b59bf-fb58-4107-9064-4d246c0e5bb2752d422f-b16f-4f0d-b1c6-26e448e3b388be2c3209-53bc-47e7-ab25-145db8b873e117be2013-2549-41ce-96e7-a70363bec29310440537-2a7b-4583-ac39-ed38d4b848e8cd2fc47e-e838-4f38-a581-8fff2f99b63ac5d93acb-ea8b-4b14-8f53-02138444ae99585c15c4-6cbf-4126-8f87-e26bff78b65736965a81-b1c6-401b-99f8-22508f1e6a26fd36aaa4-bf2b-43fb-9387-43785eeeb799Vous avez besoin de ces identifiants pour construire différentes entités de service de flux dans les étapes suivantes de ce tutoriel. Vous devez également référencer des parties de la spécification de connexion elle-même pour configurer certaines entités afin de pouvoir récupérer la spécification de connexion à partir des API Flow Service. Consultez les exemples ci-dessous de récupération des spécifications de connexion pour toutes les destinations du tableau :
Requête
| accordion | ||
|---|---|---|
| Récupérer les connection spec pour les Amazon S3 | ||
|
Réponse
| accordion | ||
|---|---|---|
| Amazon S3 - Spécification de connexion | ||
|
Requête
| accordion | ||
|---|---|---|
| Récupérer les connection spec pour les Azure Blob Storage | ||
|
Réponse
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec | ||
|
Requête
| accordion | ||
|---|---|---|
| Récupérer les connection spec pour Azure Data Lake Gen 2(ADLS Gen2) | ||
|
Réponse
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec | ||
|
Requête
| accordion | ||
|---|---|---|
| Récupérer les connection spec pour les Data Landing Zone(DLZ) | ||
|
Réponse
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec | ||
|
Requête
| accordion | ||
|---|---|---|
| Récupérer les connection spec pour les Google Cloud Storage | ||
|
Réponse
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec | ||
|
Requête
| accordion | ||
|---|---|---|
| Récupération de connection spec pour SFTP | ||
|
Réponse
| accordion | ||
|---|---|---|
| SFTP - Connection spec | ||
|
Suivez les étapes ci-dessous pour configurer un flux de données d’exportation d’audience vers une destination d’espace de stockage. Pour certaines étapes, les requêtes et les réponses diffèrent entre les différentes destinations d’espace de stockage. Dans ce cas, utilisez les onglets de la page pour récupérer les requêtes et les réponses spécifiques à la destination à laquelle vous souhaitez vous connecter et exporter des audiences. Veillez à utiliser les connection spec et flow spec corrects pour la destination que vous configurez.
Création d’une connexion Source create-source-connection
Après avoir décidé vers quelle destination vous exportez des audiences, vous devez créer une connexion source. La connexion source représente la connexion au magasin de profils Experience Platform interne.
Requête
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés lors du copier-coller de la requête dans le terminal de votre choix.
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Une réponse réussie renvoie l’identifiant (id) de la connexion source nouvellement créée et un etag. Notez l’identifiant de connexion source, car vous en aurez besoin ultérieurement lors de la création du flux de données.
Créer une connexion de base create-base-connection
Une connexion de base stocke en toute sécurité les informations d’identification vers la destination. Selon le type de destination, les informations d’identification nécessaires pour s’authentifier sur cette destination peuvent varier. Pour trouver ces paramètres d’authentification, récupérez d’abord le connection spec de la destination souhaitée, comme décrit dans la section Sélectionner la destination où exporter les audiences, puis examinez le authSpec de la réponse. Référencez les onglets ci-dessous pour les propriétés authSpec de toutes les destinations prises en charge.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec des auth spec | ||
|
Notez la ligne en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres d’authentification dans le connection spec.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec des auth spec | ||
|
Notez la ligne en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres d’authentification dans le connection spec.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec des auth spec | ||
|
Notez la ligne en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres d’authentification dans le connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Connection spec des auth spec | |||||
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec des auth spec | ||
|
Notez la ligne en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres d’authentification dans le connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Connection spec affichant les auth spec | |||||
Notez la ligne en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres d’authentification dans le connection spec.
|
À l’aide des propriétés spécifiées dans la spécification d’authentification (qui est authSpec à partir de la réponse), vous pouvez créer une connexion de base avec les informations d’identification requises, spécifiques à chaque type de destination, comme illustré dans les exemples ci-dessous :
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Demande de connexion de base avec clé d’accès et authentification par clé secrète | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Demande de connexion de base avec authentification du rôle assumé | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Amazon S3 réponse de connexion de base | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Demande de connexion de base | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Azure Blob Storage - Réponse de la connexion de base | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Demande de connexion de base | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Réponse de la connexion de base | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Demande de connexion de base | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Data Landing Zone - Réponse de la connexion de base | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Demande de connexion de base | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Google Cloud Storage - Réponse de la connexion de base | ||
|
Requête
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP avec mot de passe - Demande de connexion de base | |||||||||||||||||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP avec clé SSH - Demande de connexion de base | |||||||||||||||||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| SFTP - Réponse de connexion de base | ||
|
Ajouter un chiffrement aux fichiers exportés add-encryption
Vous pouvez éventuellement ajouter un chiffrement à vos fichiers exportés. Pour ce faire, vous devez ajouter des éléments à partir de l’objet encryption. Consultez l’exemple de requête ci-dessous avec les paramètres obligatoires mis en surbrillance :
| code language-json line-numbers data-start-1 data-line-offset-4 h-26-27 |
|---|
|
Requête
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés lors du copier-coller de la requête dans le terminal de votre choix.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-19 |
|---|
|
Réponse
| code language-json |
|---|
|
Notez l’ID de connexion à partir de la réponse. Cet identifiant sera requis à l’étape suivante lors de la création de la connexion cible.
Créer une connexion cible create-target-connection
Ensuite, vous devez créer une connexion cible. Connexions Target stockez les paramètres d’exportation pour les audiences exportées. Les paramètres d’exportation incluent l’emplacement d’exportation, le format de fichier, la compression et d’autres détails. Par exemple, pour les fichiers CSV, vous pouvez sélectionner plusieurs options d’exportation. Obtenez des informations détaillées sur toutes les options d’exportation de fichiers CSV prises en charge sur la page configurations de formatage de fichier.
Consultez les propriétés targetSpec fournies dans la connection spec de la destination pour comprendre les propriétés prises en charge pour chaque type de destination. Référencez les onglets ci-dessous pour les propriétés targetSpec de toutes les destinations prises en charge.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec affichant les paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec affichant les paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec affichant les paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec affichant les paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec affichant les paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
| accordion | ||
|---|---|---|
| SFTP : Connection spec des paramètres de connexion cible | ||
|
Notez les lignes mises en surbrillance avec des commentaires intégrés dans l’exemple de connection spec ci-dessous, qui fournissent des informations supplémentaires sur l’emplacement des paramètres de target spec dans la spécification de connexion. Vous pouvez également voir dans l’exemple ci-dessous quels paramètres cibles ne s’appliquent pas aux destinations d’exportation d’audiences.
|
En utilisant la spécification ci-dessus, vous pouvez créer une demande de connexion cible spécifique à la destination d’espace de stockage souhaitée, comme illustré dans les onglets ci-dessous.
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Requête
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Demande de connexion cible | |||||
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Demande de connexion cible avec des options CSV | |||||
|
Réponse
| accordion | ||
|---|---|---|
| Connexion cible - Réponse | ||
|
Notez le target connection ID de la réponse. Cet identifiant sera requis à l’étape suivante lors de la création du flux de données pour exporter des audiences.
Une réponse réussie renvoie l’identifiant (id) de la nouvelle connexion source cible et un etag. Notez l’identifiant de connexion cible, car vous en aurez besoin ultérieurement lors de la création du flux de données.
Créer un flux de données create-dataflow
L’étape suivante de la configuration de destination consiste à créer un flux de données. Un flux de données lie les entités créées précédemment et fournit également des options pour configurer le planning d’exportation des audiences. Pour créer le flux de données, utilisez les payloads ci-dessous, en fonction de la destination d’espace de stockage souhaitée, et remplacez les identifiants d’entité de flux des étapes précédentes. Notez que dans cette étape, vous n’ajoutez aucune information liée au mappage d’attribut ou d’identité au flux de données. Cela se fera à l’étape suivante.
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers Amazon S3 destination - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers Azure Blob Storage destination - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers Azure Data Lake Gen 2(ADLS Gen2) destination - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers Data Landing Zone destination - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers Google Cloud Storage destination - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Requête
| accordion | ||
|---|---|---|
| Créer un flux de données d’exportation d’audience vers une destination SFTP - Requête | ||
|
Notez les lignes en surbrillance avec des commentaires intégrés dans l’exemple de requête, qui fournissent des informations supplémentaires. Supprimez les commentaires intégrés dans la requête lors du copier-coller de la requête dans le terminal de votre choix.
|
Réponse
| accordion | ||
|---|---|---|
| Créer un flux de données - Réponse | ||
|
Notez l’identifiant du flux de données dans la réponse. Cet identifiant sera requis lors des étapes suivantes.
Ajouter des audiences à l’exportation add-audiences
Au cours de cette étape, vous pouvez également sélectionner les audiences que vous souhaitez exporter vers la destination. Pour obtenir des informations détaillées sur cette étape et le format de requête permettant d’ajouter une audience au flux de données, consultez les exemples dans la section Mettre à jour un flux de données de destination de la documentation de référence de l’API.
Configurer le mappage des attributs et des identités attribute-and-identity-mapping
Après avoir créé votre flux de données, vous devez configurer le mappage pour les attributs et les identités que vous souhaitez exporter. Effectuez les étapes suivantes dans l’ordre :
- Récupérez le schéma d’entrée.
- Récupérez et examinez le schéma du partenaire.
- Créez le schéma de sortie, y compris chaque champ que vous souhaitez exporter en tant que destination de mappage.
- Vérifiez que chaque destination de mappage existe dans le schéma de sortie.
- Créez le jeu de mappages.
- Mettez à jour le flux de données avec le jeu de mappages.
Par exemple, pour obtenir le mappage suivant illustré dans l’interface utilisateur, vous devez suivre les étapes répertoriées ci-dessus et décrites en détail dans les en-têtes suivants.
firstName, lastName ou Email, doit déjà exister dans le schéma de sortie avant de créer le jeu de mappages. Si un champ de destination de mappage est manquant dans le schéma de sortie, la requête du jeu de mappages échoue.Création d’un schéma d’entrée create-input-schema
Pour créer un schéma d’entrée, vous devez d’abord récupérer votre schéma d’union et les identités qui peuvent être exportées vers la destination. Il s’agit du schéma des attributs et des identités que vous pouvez sélectionner comme mappage source.
Consultez ci-dessous des exemples de requêtes et de réponses pour récupérer les attributs et les identités.
Demande d’obtention des attributs
| code language-shell |
|---|
|
Réponse
La réponse ci-dessous a été abrégée par souci de concision.
| code language-json |
|---|
|
Demande d’obtention des identités
| code language-shell |
|---|
|
Réponse
La réponse renvoie les identités que vous pouvez utiliser lors de la création du schéma d’entrée. Notez que cette réponse renvoie les espaces de noms d’identité standard et personnalisés que vous configurez dans Experience Platform.
| code language-json |
|---|
|
Ensuite, vous devez copier la réponse ci-dessus et l’utiliser pour créer votre schéma d’entrée. Vous pouvez copier l’intégralité de la réponse JSON de la réponse ci-dessus et la placer dans l’objet jsonSchema indiqué ci-dessous.
Demande de création d’un schéma d’entrée
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
L’identifiant dans la réponse représente l’identifiant unique du schéma d’entrée que vous avez créé. Copiez l’identifiant de la réponse, car vous le réutiliserez à une étape ultérieure.
Création d’un schéma de sortie create-output-schema
Vous devez ensuite configurer le schéma de sortie pour votre exportation. Tout d’abord, vous devez rechercher et inspecter votre schéma de partenaire existant.
Requête
Notez que l’exemple ci-dessous utilise le connection spec ID pour Amazon S3. Veuillez remplacer cette valeur par l’identifiant de spécification de connexion spécifique à votre destination.
| code language-shell |
|---|
|
Réponse avec un exemple de schéma
Examinez la réponse que vous obtenez lors de l’exécution de l’appel ci-dessus. Vous devez analyser la réponse en profondeur pour trouver l’objet targetSpec.attributes.partnerSchema.jsonSchema
| code language-json |
|---|
|
Vous devez ensuite créer un schéma de sortie. Copiez la réponse JSON obtenue ci-dessus et collez-la dans l’objet jsonSchema ci-dessous.
Le schéma de partenaire contient uniquement des structures génériques, telles que attributes, identityMap et segmentMembership. Avant de créer le jeu de mappages à l’étape suivante, ajoutez une propriété à l’objet jsonSchema pour chaque champ à mapper. L’API de mappage valide chaque destination de mappage par rapport au schéma de sortie. De ce fait, un champ de destination de mappage qui n’existe pas dans le schéma de sortie entraîne l’échec de la requête du jeu de mappages.
L’exemple de requête et de réponse ci-dessous montre les propriétés firstName, lastName, Email, personalEmail_address et segmentMembership_status déjà ajoutées au schéma de sortie avec les structures attributes, identityMap et segmentMembership génériques du schéma de partenaire. Ces propriétés correspondent aux destinations de mappage utilisées dans l’exemple de jeu de mappages plus loin dans cette section.
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
L’identifiant dans la réponse représente l’identifiant unique du schéma de sortie que vous avez créé. Copiez l’identifiant de la réponse, car vous le réutiliserez à une étape ultérieure.
Créer un jeu de mappages create-mapping-set
Utilisez ensuite l’API data prep pour créer le jeu de mappages à l’aide de l’identifiant de schéma d’entrée, de l’identifiant de schéma de sortie et des mappages de champs de votre choix.
Requête
| note important |
|---|
| IMPORTANT |
|
Avant de créer le jeu de mappages, vérifiez les points suivants :
- Chaque champ de destination de mappage, tel que
firstName,lastNameetEmail, existe déjà dans le schéma de sortie. - Chaque chemin source existe dans le schéma d’entrée.
- Les mappages d’identités utilisent des espaces de noms d’identité valides.
- Les champs d’appartenance à un segment, tels que
segmentMembership_status, sont définis dans le schéma de sortie si vous les référencez dans un mappage. - Le schéma d’entrée, le schéma de sortie et le jeu de mappages appartiennent tous au même sandbox.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-16-42 |
|---|
|
Réponse
| code language-json |
|---|
|
MAPPER-3101-400 indiquant que le chemin XDM n’est pas valide, une ou plusieurs de vos valeurs de destination de mappage n’existent pas dans le schéma de sortie. Ajoutez les champs manquants au schéma de sortie et réessayez la requête de jeu de mappages.Notez l’identifiant du jeu de mappages, car vous en aurez besoin à l’étape suivante pour mettre à jour le flux de données existant avec l’identifiant du jeu de mappages.
Ensuite, obtenez l’identifiant du flux de données à mettre à jour.
Voir récupérer les détails d’un flux de données de destination pour plus d’informations sur la récupération de l’identifiant d’un flux de données.
Enfin, vous devez PATCH le flux de données avec les informations du jeu de mappages que vous venez de créer.
Requête
| code language-shell |
|---|
|
Réponse
La réponse de l’API Flow Service renvoie l’identifiant du flux de données mis à jour.
| code language-json |
|---|
|
Effectuer d’autres mises à jour du flux de données other-dataflow-updates
Pour apporter des mises à jour à votre flux de données, utilisez l’opération PATCH . Par exemple, vous pouvez ajouter une action marketing à vos flux de données, mettre à jour vos flux de données pour sélectionner des champs en tant que clés obligatoires ou clés de déduplication, ajouter des attributs d’enrichissement pour les audiences de chargement personnalisées ou ajouter la génération de manifeste de fichier aux destinations existantes.
Ajout d’une action marketing add-marketing-action
Pour ajouter une action marketing, reportez-vous aux exemples de requête et de réponse ci-dessous.
If-Match est requis lors de l’exécution d’une requête PATCH. La valeur de cet en-tête est la version unique du flux de données que vous souhaitez mettre à jour. La valeur etag est mise à jour avec chaque mise à jour réussie d’une entité de flux telle que le flux de données, la connexion cible, etc.https://platform.adobe.io/data/foundation/flowservice/flows/{ID} , où {ID} correspond à l’identifiant du flux de données que vous souhaitez mettre à jour.If-Match entre guillemets doubles, comme dans les exemples ci-dessous, lors de l’exécution de requêtes PATCH.Requête
| code language-shell |
|---|
|
Réponse
Une réponse réussie renvoie le code de réponse 200 avec l’identifiant du flux de données mis à jour et la balise électronique mise à jour.
| code language-json |
|---|
|
Ajouter une clé obligatoire add-mandatory-key
Pour ajouter une clé obligatoire, reportez-vous aux exemples de requête et de réponse ci-dessous.
If-Match est requis lors de l’exécution d’une requête PATCH. La valeur de cet en-tête est la version unique du flux de données que vous souhaitez mettre à jour. La valeur etag est mise à jour avec chaque mise à jour réussie d’une entité de flux telle que le flux de données, la connexion cible, etc.https://platform.adobe.io/data/foundation/flowservice/flows/{ID} , où {ID} correspond à l’identifiant du flux de données que vous souhaitez mettre à jour.If-Match entre guillemets doubles, comme dans les exemples ci-dessous, lors de l’exécution de requêtes PATCH.Requête
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Ajout d’une clé de déduplication add-deduplication-key
Pour ajouter une clé de déduplication, consultez les exemples de requête et de réponse ci-dessous
If-Match est requis lors de l’exécution d’une requête PATCH. La valeur de cet en-tête est la version unique du flux de données que vous souhaitez mettre à jour. La valeur etag est mise à jour avec chaque mise à jour réussie d’une entité de flux telle que le flux de données, la connexion cible, etc.https://platform.adobe.io/data/foundation/flowservice/flows/{ID} , où {ID} correspond à l’identifiant du flux de données que vous souhaitez mettre à jour.If-Match entre guillemets doubles, comme dans les exemples ci-dessous, lors de l’exécution de requêtes PATCH.Requête
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Ajouter la génération du manifeste de fichier à la destination existante add-file-manifest
Les fichiers JSON de manifeste contiennent des informations sur l’emplacement d’exportation, la taille d’exportation, etc. Le manifeste est nommé à l’aide du format manifest-<<destinationId>>-<<dataflowRunId>>.json. Affichez un exemple de fichier de manifeste. Le fichier manifeste comprend les champs suivants :
flowRunId: exécution flux de données qui a généré le fichier exporté.scheduledTime: heure en UTC à laquelle le fichier a été exporté.exportResults.sinkPath: chemin d’accès à l’emplacement de stockage où le fichier exporté est déposé.exportResults.name: nom du fichier exporté.size: taille du fichier exporté, en octets.
Pour ajouter la génération du manifeste de fichier à une destination existante, vous devez mettre à jour les paramètres de connexion cible à l’aide de l’opération PATCH. Cela permet la génération de fichiers de manifeste pour votre destination, qui fournit des métadonnées sur les fichiers exportés.
If-Match est requis lors de l’exécution d’une requête PATCH. La valeur de cet en-tête est la version unique de la connexion cible que vous souhaitez mettre à jour. La valeur etag est mise à jour avec chaque mise à jour réussie d’une entité de flux telle que le flux de données, la connexion cible, etc.https://platform.adobe.io/data/foundation/flowservice/targetConnections/{ID} , où {ID} correspond à l’identifiant de connexion cible que vous souhaitez mettre à jour.If-Match entre guillemets doubles, comme dans les exemples ci-dessous, lors de l’exécution de requêtes PATCH.Requête
| code language-shell |
|---|
|
Ajouter des attributs d’enrichissement add-enrichment-attributes
Les attributs d’enrichissement s’appliquent lorsque vous activez les audiences Chargement personnalisé, qui sont des audiences ingérées dans Experience Platform sous forme de fichiers CSV. Utilisez ce workflow pour sélectionner les attributs de ces audiences à inclure dans le fichier exporté.
Le workflow nécessite deux étapes : tout d’abord, créez un jeu de mappages qui définit les attributs à exporter (étapes 1 et 2), puis référencez ce jeu de mappages lors de l’ajout de l’audience à votre flux de données (étape 3).
InvalidParameterException: "One deduplication key (i.e. primary field) must be specified when activating audiences with enrichment info".Étape 1 : récupérer le jeu de données et le schéma de la payload enrichment-step1
Pour chaque audience pour laquelle l’enrichissement est activé, récupérez le jeu de données de payload et le schéma XDM associés. Les propriétés du schéma sont utilisées comme schéma d’entrée et de sortie lors de la création de jeux de mappages.
Étape 1a : récupération en bloc des audiences avec des métadonnées de jeu de données de payload
Envoyez les identifiants d’audience à enrichir au point d’entrée d’obtention en masse du service de segmentation.
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Notez le champ originName et le payloadDatasetId de la réponse. Vous avez besoin des deux pour les étapes suivantes.
Étape 1b : récupérer le jeu de données de payload
Utilisez le payloadDatasetId de la réponse précédente pour récupérer le jeu de données à partir du service de catalogue.
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Extrayez la valeur schemaRef.id. Vous en avez besoin à l’étape suivante.
Étape 1c : récupérer le schéma XDM dans Schema Registry
Utilisez le schemaRef.id de la réponse du jeu de données pour récupérer le schéma XDM complet. Encodez par URL l’identifiant de schéma lors de son utilisation comme paramètre de chemin d’accès.
Par exemple, https://ns.adobe.com/acme/schemas/88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176 devient https%3A%2F%2Fns.adobe.com%2Facme%2Fschemas%2F88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176.
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Étape 1d : extraire le schéma JSON
Le schéma JSON que vous utilisez à l’étape 2a dépend du type d’audience, identifié par originName à l’étape 1a.
Pour les audiences pour lesquelles originName n’est pas AUDIENCE_ORCHESTRATION, extrayez uniquement le sous-objet d’espace de noms du client à properties[meta:tenantNamespace] et combinez-le avec le title de niveau supérieur. Ignorez les champs système tels que les _id et les timestamp.
Exemple de schéma JSON extrait :
| code language-json |
|---|
|
Pour les audiences pour lesquelles originName est AUDIENCE_ORCHESTRATION, utilisez l’ensemble complet des propriétés de niveau supérieur à partir de la réponse du registre des schémas. Ajoutez des meta:xdmType: "object" et des type: "object" explicitement. Le title est toujours extrait de la réponse de niveau supérieur du registre des schémas.
Exemple de schéma JSON extrait :
| code language-json |
|---|
|
Le tableau suivant résume la source du schéma et les champs à utiliser pour chaque type d’audience.
originName n’est pas AUDIENCE_ORCHESTRATIONproperties[meta:tenantNamespace]originName est AUDIENCE_ORCHESTRATIONpropertiesÉtape 2 : créer le jeu de mappages enrichment-step2
La création d’un jeu de mappages est une séquence de deux appels : enregistrez le schéma JSON de l’étape 1d en tant que schéma de conversion pour obtenir un identifiant de schéma, puis créez le jeu de mappages référençant cet identifiant de schéma.
Étape 2a : créer le schéma de conversion
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Étape 2b : créez le jeu de mappages
Utilisez les {CONVERSION_SCHEMA_ID} de la réponse précédente comme inputSchema.id et outputSchema.id. Chaque clé de propriété du schéma est à la fois la source et la destination. La sourceType doit toujours être text/x.schema-path.
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Stockez les valeurs id et version renvoyées. Il s’agit des mappingSet.id et mappingSet.version que vous référencez à l’étape suivante.
Étape 3 : ajouter des attributs d’enrichissement au flux de données enrichment-step3
Une fois le jeu de mappages créé, utilisez une requête PATCH pour ajouter l’audience avec sa configuration d’enrichissement à votre flux de données.
If-Match est requis lors de l’exécution d’une requête PATCH. La valeur de cet en-tête est la version unique du flux de données que vous souhaitez mettre à jour. La valeur etag est mise à jour avec chaque mise à jour réussie d’une entité de flux telle que le flux de données, la connexion cible, etc.https://platform.adobe.io/data/foundation/flowservice/flows/{ID} , où {ID} correspond à l’identifiant du flux de données que vous souhaitez mettre à jour.If-Match entre guillemets doubles, comme dans les exemples ci-dessous, lors de l’exécution de requêtes PATCH.Requête
| code language-shell |
|---|
|
L’objet enrichmentInfo possède les propriétés suivantes :
enabledsourceTypeAUDIENCE_DATASET, par exemple.mappingSet.idmappingSet.versionUne fois le flux exécuté, les attributs d’enrichissement résolus sont disponibles dans le modèle d’exportation à l’adresse :
destination.enrichmentAttributes.{namespace}.{segmentId}
enrichmentInfo.enabled sur false pour toutes les audiences. Aucun jeu de mappages n’est requis dans ce cas.Valider le flux de données (obtenir les exécutions du flux de données) get-dataflow-runs
Pour vérifier les exécutions d’un flux de données, utilisez l’API d’exécutions de flux de données :
Requête
| code language-shell |
|---|
|
Réponse
| code language-json |
|---|
|
Vous trouverez des informations sur les différents paramètres renvoyés par l’API d’exécution de flux de données dans la documentation de référence de l’API.
Gestion des erreurs d’API api-error-handling
Les points d’entrée d’API de ce tutoriel suivent les principes généraux des messages d’erreur de l’API Experience Platform. Voir Codes d’état de l’API et Erreurs d’en-tête de requête dans le guide de dépannage d’Experience Platform pour plus d’informations sur l’interprétation des réponses d’erreur.
Étapes suivantes next-steps
Vous avez réussi à connecter Experience Platform à l’une de vos destinations d’espace de stockage préférées et à configurer un flux de données vers la destination correspondante pour exporter des audiences. Consultez les pages suivantes pour plus d’informations, telles que la modification des flux de données existants à l’aide de l’API Flow Service :