Ce document fournit un tutoriel sur l’évaluation des définitions de segment et l’accès à ces résultats à l’aide du Segmentation API.
Ce tutoriel nécessite une compréhension pratique des différentes Adobe Experience Platform services impliqués dans la création d’audiences. 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}
{ORG_ID}
Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Demandes à Platform Les API requièrent un en-tête qui spécifie le nom de l’environnement de test dans lequel l’opération aura lieu :
{SANDBOX_NAME}
Pour plus d’informations sur les sandbox dans Platform, consultez la documentation de présentation des sandbox.
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 la définition de segment par le biais d’une évaluation planifiée ou d’une é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.
Si vous n’avez pas encore terminé la variable créer une définition de segment à l’aide de l’API Segmentation ; tutoriel ou définition de segment créée à l’aide de Créateur de segments, faites-le avant de suivre ce tutoriel.
Grâce à l’évaluation planifiée, votre entreprise peut 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 sandbox avec un maximum de cinq (5) politiques de fusion pour XDM Individual Profile. Si votre organisation compte plus de cinq politiques de fusion pour XDM Individual Profile dans une seul sandbox, vous ne pourrez pas procéder à l’évaluation planifiée.
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 de terminaison dans la section guide de point de fin planifications
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 de terminaison dans la section guide de point de fin planifications
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 de terminaison dans la section guide de point de fin planifications
L’évaluation sur demande vous permet de créer une tâche de segmentation afin de générer un 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 segment d’audience à la demande. Il fait référence à une définition de segment, ainsi qu’à toute stratégie de fusion contrôlant la manière dont Real-Time Customer Profile fusionne des attributs qui se chevauchent dans vos fragments de profil. Une fois la tâche de segmentation terminée, vous pouvez collecter diverses informations sur la définition de segment, telles que les erreurs qui se sont produites au cours du 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 actuellement admissible par la définition de segment.
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 la section guide de point de fin des tâches 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 de terminaison dans la section guide de point de fin des tâches de segmentation
Lorsque les tâches de segmentation sont exécutées avec succès, la variable segmentMembership
est mis à jour pour chaque profil inclus dans la définition de segment. segmentMembership
stocke également toutes les audiences préévaluées ingérées dans Platform, permettant l’intégration à d’autres solutions telles que 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"
}
}
}
}
Propriété | Description |
---|---|
lastQualificationTime |
Horodatage au moment où l’affirmation de l’appartenance au segment a été faite et où le profil a entré ou quitté la définition de segment. |
status |
État 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 :
|
Toute adhésion au segment qui figure dans la variable exited
de plus de 30 jours, en fonction de la variable lastQualificationTime
, sera sujette à suppression.
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.
Si vous connaissez le profil spécifique auquel vous souhaitez accéder, vous pouvez le faire à l’aide de la variable Real-Time Customer Profile API. Les étapes complètes d’accès aux profils individuels sont disponibles dans la section Accès aux données Real-time Customer Profile à l’aide de l’API Profile tutoriel .
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 une définition de segment, le jeu de données doit être basé sur la variable 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 d’affichage d’union, reportez-vous à la section 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: {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"
}
}'
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é. |
Ré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"
]
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 envoyant une requête de POST à l’ /export/jobs
du point de terminaison Real-Time Customer Profile API et 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 de terminaison dans la section guide de point de fin des traitements d’export
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 de terminaison dans la section guide de point de fin des traitements d’export
Une fois l’exportation terminée, vos données sont disponibles dans la variable Data Lake in Experience Platform. Vous pouvez ensuite utiliser la variable Data Access API pour accéder aux données à l’aide de la variable batchId
associée à l'export. Selon la taille de la définition de segment, les données peuvent se présenter sous forme de blocs et le lot peut être constitué de plusieurs fichiers.
Pour obtenir des instructions détaillées sur l’utilisation de la variable Data Access Pour accéder aux fichiers de lot et les télécharger, suivez la Tutoriel sur l’accès aux données.
Vous pouvez également accéder aux données de définition de segment exportées avec succès à l’aide de Adobe Experience Platform Query Service. Utilisation 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 des données dans la variable Data Lake.
Pour plus d’informations sur la manière d’interroger les données d’audience, consultez la documentation sur Query Service.