Évaluation et accès aux résultats de la définition de segment
Créé pour :
- Utilisateur ou utilisatrice
Ce document fournit un tutoriel permettant d’évaluer les définitions de segment et d’accéder à ces résultats à l’aide de l’Segmentation API .
Commencer
Ce tutoriel nécessite une compréhension pratique des différents services Adobe Experience Platform impliqués dans la création d’audiences. Avant de commencer ce tutoriel, veuillez consulter la documentation relative aux services suivants :
- Real-Time Customer Profile : fournit un profil client en temps réel unifié basé sur des données agrégées issues de plusieurs sources.
- Adobe Experience Platform Segmentation Service : permet de créer des audiences à partir de données Real-Time Customer Profile.
- Experience Data Model (XDM) : cadre normalisé selon lequel Platform organise les données de l’expérience client. Pour utiliser au mieux la segmentation, veillez à ce que vos données soient ingérées en tant que profils et événements en fonction des bonnes pratiques pour la modélisation des données.
- Sandbox : 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.
En-têtes requis
Ce tutoriel nécessite également que vous ayez suivi le tutoriel sur l’authentificationpour passer avec succès des appels aux API 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}
Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Les requêtes Experience Platform API nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération aura lieu :
- x-sandbox-name :
{SANDBOX_NAME}
NOTEToutes les requêtes POST, PUT et PATCH requièrent un en-tête supplémentaire :
- Content-Type: application/json
Évaluation d’une définition de segment
Une fois votre définition de segment développée, testée et enregistrée, vous pouvez l’évaluer au moyen d’une évaluation planifiée ou d’une évaluation à la demande.
L’évaluation planifiée (également appelée « segmentation planifiée ») vous permet de créer un planning récurrent pour exécuter une tâche d’exportation à un moment précis, tandis que l’évaluation sur demande implique la création d’une tâche de segmentation pour créer immédiatement l’audience. Les étapes à suivre pour chaque type d’évaluation sont décrites ci-dessous.
Si vous n’avez pas encore terminé le tutoriel créer une définition de segment à l’aide de l’API Segmentation ou créé une définition de segment à l’aide du Créateur de segments, veuillez le faire avant de poursuivre ce tutoriel.
Évaluation planifiée
Grâce à l’évaluation planifiée, votre entreprise peut créer une planification récurrente pour exécuter automatiquement les tâches d’exportation.
NOTECréation d’un planning
En effectuant une requête POST sur le point d’entrée /config/schedules, vous pouvez créer un planning et inclure l’heure spécifique à laquelle le planning doit être déclenché.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide planning endpoint guide
Activation d’un planning
Par défaut, un planning est inactif lors de la création, sauf si la propriété state est définie sur active dans le corps de la requête de création (POST). Vous pouvez activer un planning (définissez state sur active) en effectuant une requête PATCH sur le point d’entrée /config/schedules et en incluant l’identifiant du planning dans le chemin.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide planning endpoint guide
Mise à jour de l’heure du planning
Vous pouvez mettre à jour l’heure du planning en effectuant une requête PATCH sur le point d’entrée /config/schedules et en incluant l’identifiant du planning dans le chemin.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide planning endpoint guide
Évaluation sur demande
L’évaluation à la demande vous permet de créer une tâche de segmentation afin de générer une audience chaque fois que vous en avez besoin. Contrairement à l’évaluation planifiée, celle-ci n’a lieu que sur demande et n’est pas récurrente.
Création d’une tâche de segmentation
Une tâche de segmentation est un processus asynchrone qui crée un segment d’audience à la demande. Elle fait référence à une définition de segment, ainsi qu’à toute politique de fusion contrôlant la manière dont Real-Time Customer Profile fusionne les attributs qui se chevauchent dans vos fragments de profil. Une fois la tâche de segmentation terminée, vous pouvez collecter de nombreuses informations sur la définition de segment, telles que les erreurs qui peuvent s’être produites pendant le traitement et la taille finale de votre audience. Une tâche de segmentation doit être exécutée chaque fois que vous souhaitez actualiser l’audience que la définition de segment qualifie actuellement.
Vous pouvez créer une tâche de segmentation en effectuant une requête POST vers le point d’entrée /segment/jobs dans l’API Real-Time Customer Profile.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide point d’entrée des tâches de segment
Recherche de l’état de la tâche de segmentation
Vous pouvez utiliser l’id pour une tâche de segmentation spécifique afin d’effectuer une requête de recherche (GET) pour afficher l’état actuel de la tâche.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide point d’entrée des tâches de segment
Interprétation des résultats des tâches de segmentation
Une fois les tâches de segmentation exécutées avec succès, la carte segmentMembership est mise à jour pour chaque profil inclus dans la définition de segment. segmentMembership stocke également toutes les audiences pré-évaluées qui sont ingérées dans Experience Platform, permettant l’intégration avec d’autres solutions comme Adobe Audience Manager.
L’exemple suivant illustre l’attribut segmentMembership pour chaque enregistrement de profil individuel :
{
"segmentMembership": {
"UPS": {
"04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
"timestamp": "2018-04-26T15:52:25+00:00",
"status": "realized"
},
"53cba6b2-a23b-454a-8069-fc41308f1c0f": {
"lastQualificationTime": "2018-04-26T15:52:25+00:00",
"status": "realized"
}
},
"Email": {
"abcd@adobe.com": {
"lastQualificationTime": "2017-09-26T15:52:25+00:00",
"status": "exited"
}
}
}
}
lastQualificationTimestatusStatut de participation de la définition de segment dans le cadre de la requête actuelle. Doit être égal à l’une des valeurs connues suivantes :
realized: l’entité est éligible pour la définition de segment.exited: l’entité quitte la définition de segment.
NOTEexited pendant plus de 30 jours, selon le lastQualificationTime, peut être supprimée.Accès aux résultats de la tâche de segmentation
Vous pouvez accéder aux résultats d’une tâche de segmentation de deux manières : en accédant aux profils individuels ou en exportant une audience entière vers un jeu de données.
Les sections suivantes décrivent ces options de manière plus détaillée.
Recherche d’un profil
Si vous connaissez le profil spécifique auquel vous souhaitez accéder, vous pouvez le faire à l’aide de l’API Real-Time Customer Profile. Les étapes complètes d’accès aux profils individuels sont disponibles dans le tutoriel Accéder aux données du profil client en temps réel à l’aide de l’API Profile.
Exportation d’un segment
Une fois la tâche de segmentation terminée (la valeur de l’attribut status correspond à "SUCCEEDED"), vous pouvez exporter votre audience vers un jeu de données permettant son accès et son utilisation.
Les étapes suivantes sont requises pour exporter votre audience :
- Création d’un jeu de données cible : créez le jeu de données permettant de contenir les membres de l’audience.
- Génération de profils d’audience dans le jeu de données : renseignez le jeu de données avec des profils individuels XDM en fonction des résultats d’une tâche de segmentation.
- Contrôle de la progression de l’exportation : vérifiez la progression actuelle du processus d’exportation.
- Lecture des données d’audience : récupérez les profils individuels XDM obtenus représentant les membres de votre audience.
Création d’un jeu de données cible
Lors de l’exportation d’une audience, un jeu de données cible doit d’abord être créé. Il est important que le jeu de données soit correctement configuré pour garantir la réussite de l’exportation.
Le schéma sur lequel repose le jeu de données est l’une des principales considérations (schemaRef.id dans l’exemple de requête API ci-dessous). Pour exporter une définition de segment, le jeu de données doit être basé sur la XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Un schéma d’union est un schéma en lecture seule généré par le système regroupant les champs des schémas qui partagent la même classe, dans ce cas précis, la classe XDM Individual Profile. Pour plus d’informations sur les schémas de vue d’union, consultez la section Profil client en temps réel) du guide de développement du registre des schémas.
Il existe deux manières de créer le jeu de données nécessaire :
- Utilisation des API : les étapes qui suivent ce tutoriel expliquent comment créer un jeu de données qui référence le XDM Individual Profile Union Schema à l’aide de l’API Catalog.
- À l’aide de l’interface utilisateur : pour utiliser l’interface utilisateur Adobe Experience Platform afin de créer un jeu de données qui référence le schéma d’union, suivez les étapes du tutoriel IU, puis revenez au présent tutoriel pour suivre les étapes de génération de profils d’audience.
Si vous disposez déjà d’un jeu de données compatible et que vous connaissez son identifiant, vous pouvez passer directement à l’étape de génération de profils.
Format d’API
POST /dataSets
Requête
La requête suivante crée un jeu de données et fournit des paramètres de configuration dans le payload.
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/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}' \
-d '{
"name": "Segment Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
nameschemaRef.idRéponse
Une réponse réussie renvoie un tableau contenant l’ID unique et en lecture seule généré par le système du jeu de données que vous venez de créer. Un identifiant de jeu de données correctement configuré est nécessaire pour exporter les membres de l’audience.
[
"@/datasets/5b020a27e7040801dedba61b"
]
Génération de profils pour les membres de l’audience
Une fois que vous disposez d’un jeu de données persistant dans l’union, vous pouvez créer une tâche d’exportation afin de conserver les membres de l’audience dans le jeu de données en adressant une requête POST au point d’entrée /export/jobs de l’API Real-Time Customer Profile et en fournissant l’identifiant du jeu de données et les informations de définition de segment pour les définitions de segment que vous souhaitez exporter.
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide point d’entrée des tâches d’exportation
Contrôle de la progression de l’exportation
Lorsqu’une tâche d’exportation est en cours de traitement, vous pouvez contrôler son état en effectuant une requête GET sur le point d’entrée /export/jobs et en incluant l’id de la tâche d’exportation dans le chemin. La tâche d’exportation est terminée lorsque le champ status renvoie la valeur "SUCCEEDED".
Vous trouverez des informations plus détaillées sur l’utilisation de ce point d’entrée dans le guide point d’entrée des tâches d’exportation
Étapes suivantes
Une fois l’exportation terminée, vos données sont disponibles dans le Data Lake dans Experience Platform. Vous pouvez ensuite utiliser l’Data Access API pour accéder aux données à l’aide du batchId associé à l’exportation. Selon la taille de la définition de segment, les données peuvent être en blocs et le lot peut se composer de plusieurs fichiers.
Pour obtenir des instructions détaillées sur l’utilisation de l’API Data Access pour accéder aux fichiers par lot et les télécharger, suivez le tutoriel Data Access.
Vous pouvez également accéder aux données de définition de segment correctement exportées à l’aide de Adobe Experience Platform Query Service. À l’aide de l’interface utilisateur ou de l’API RESTful, Query Service vous permet d’écrire, de valider et d’exécuter des requêtes sur les données de l’Data Lake.
Pour plus d’informations sur la manière d’interroger les données d’audience, consultez la documentation sur Query Service.