This document provides a tutorial for evaluating segments and accessing segment results using the Segmentation API.
This tutorial requires a working understanding of the various Adobe Experience Platform services involved in creating audience segments. Avant de commencer ce tutoriel, veuillez consulter la documentation relative aux services suivants :
Ce tutoriel exige aussi que vous ayez terminé le tutoriel sur l’authentification pour passer des appels à des API 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 :
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:
{SANDBOX_NAME}
For more information on sandboxes in Platform, see the sandbox overview documentation.
Toutes les requêtes POST, PUT et PATCH requièrent un en-tête supplémentaire :
Une fois que vous avez développé, testé et enregistré votre définition de segment, vous pouvez ensuite évaluer le segment soit par une évaluation planifiée soit par l’évaluation sur 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.
If you have not yet completed the create a segment using the Segmentation API tutorial or created a segment definition using Segment Builder, please do so before proceeding with this tutorial.
L’évaluation planifiée permet à votre organisation IMS de créer un planning récurrent pour exécuter automatiquement les tâches d’exportation.
L’évaluation planifiée peut être activée pour les environnements de test avec un maximum de cinq (5) stratégies de fusion pour XDM Individual Profile. If your organization has more than five merge policies for XDM Individual Profile within a single sandbox environment, you will not be able to use scheduled evaluation.
En effectuant une requête POST sur le point de terminaison /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 de terminaison dans le guide des points de terminaison planifiés.
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 de terminaison /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 de terminaison dans le guide des points de terminaison planifiés.
Vous pouvez mettre à jour l’heure du planning en effectuant une requête PATCH sur le point de terminaison /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 de terminaison dans le guide des points de terminaison planifiés.
L’évaluation sur demande vous permet de créer une tâche de segmentation afin de générer un segment ciblé 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.
Une tâche de segmentation est un processus asynchrone qui crée un nouveau segment ciblé. It references a segment definition, as well as any merge policies controlling how Real-time Customer Profile merges overlapping attributes across your profile fragments. Lorsqu’une tâche de segmentation se termine avec succès, vous pouvez collecter diverses informations sur le segment, telles que les erreurs qui se sont produites au cours du traitement et la taille finale de votre audience.
Vous pouvez créer une tâche de segmentation en exécutant une requête POST sur le point de terminaison /segment/jobs
dans l’API Real-time Customer Profile
Vous trouverez des informations plus détaillées sur l’utilisation de ce point de terminaison dans le guide des points de terminaison des tâches de segment.
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 de terminaison dans le guide des points de terminaison des tâches de segment.
Lorsque les tâches de segmentation sont exécutées avec succès, le mappage segmentMembership
est mis à jour pour chaque profil inclus dans le segment. segmentMembership
stocke également tous les segments d’audience préévalués qui sont assimilés Platform, ce qui permet l’intégration à d’autres solutions, telles que Adobe Audience Managerles solutions.
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": "existing"
},
"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"
}
}
}
}
Propriété | Description |
---|---|
lastQualificationTime |
La date et l’heure auxquelles l’appartenance au segment a été affirmée et le profil est entré dans le segment ou en est sorti. |
status |
L’état de la participation au segment dans le cadre de la requête actuelle. Doit être égal à l’une des valeurs connues suivantes :
|
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.
If you know the specific profile that you would like to access, you can do so using the Real-time Customer Profile API. Toutes les étapes pour accéder aux profils individuels sont disponibles dans le tutoriel sur l’accès aux données de Real-time Customer Profile à l’aide de l’API Profile.
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 :
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 un segment, le jeu de données doit être basé sur le 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 la vue d’union des schémas, consultez la section Real-time Customer Profile 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 :
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: {IMS_ORG}' \
-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"
},
"fileDescription": {
"persisted": true,
"containerFormat": "parquet",
"format": "parquet"
}
}'
Propriété | Description |
---|---|
name |
Un nom explicite pour le jeu de données. |
schemaRef.id |
L’identifiant de la vue d’union (schéma) à laquelle le jeu de données sera associé. |
fileDescription.persisted |
Une valeur booléenne qui, lorsqu’elle est définie sur true , permet de conserver le jeu de données dans la vue d’union. |
Réponse
Une réponse réussie renvoie un tableau contenant l’identifiant 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"
]
Une fois que vous disposez d’un jeu de données d’union persistant, vous pouvez créer une tâche d’exportation afin de conserver les membres de l’audience dans le jeu de données, en effectuant une requête POST sur le point de terminaison /export/jobs
dans l’API et en fournissant l’identifiant du jeu de données et les informations sur les segments que vous souhaitez exporter.Real-time Customer Profile
Vous trouverez des informations plus détaillées sur l’utilisation de ce point de terminaison dans le guide des points de terminaison des tâches d’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 de terminaison /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 de terminaison dans le guide des points de terminaison des tâches d’exportation.
Once the export has completed successfully, your data is available within the Data Lake in Experience Platform. You can then use the Data Access API to access the data using the batchId
associated with the export. Selon la taille du segment, les données peuvent se présenter sous forme de blocs et le lot peut être constitué de plusieurs fichiers.
For step-by-step instructions on how to use the Data Access API to access and download batch files, follow the Data Access tutorial.
Vous pouvez également accéder aux données de segment exportées avec succès à l’aide de Adobe Experience Platform Query Service. Using the UI or RESTful API, Query Service allows you to write, validate, and run queries on data within the Data Lake.
For more information on how to query audience data, please review the documentation on Query Service.