Création d’un segment à l’aide de l’API du service de segmentation

Ce document fournit un didacticiel pour le développement, le test, la prévisualisation et l'enregistrement d'une définition de segment à l'aide de Adobe Experience Platform Segmentation Service API.

Pour plus d’informations sur la création de segments à l’aide de l’interface utilisateur, consultez le guide du créateur de segments.

Prise en main

Ce didacticiel nécessite une bonne compréhension des différents services Adobe Experience Platform impliqués dans la création de segments d'audience. Avant de commencer ce tutoriel, veuillez consulter la documentation relative aux services suivants :

Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour pouvoir invoquer les API Platform.

Lecture d’exemples d’appels API

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épannageExperience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API 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: {IMS_ORG}

Toutes les ressources de Experience Platform sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes d'API Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l'opération aura lieu :

  • x-sandbox-name: {SANDBOX_NAME}
REMARQUE

Pour plus d'informations sur les sandbox dans Platform, consultez la documentation d'aperçu de sandbox.

Toutes les requêtes contenant un payload (POST, PUT, PATCH) requièrent un en-tête supplémentaire :

  • Content-Type: application/json

Développement d’une définition de segment

La première étape de la segmentation consiste à définir un segment, représenté dans un concept appelé définition de segment. Une définition de segment est un objet qui encapsule une requête écrite dans Profile Query Language (PQL). Cet objet est également appelé prédicat PQL. Les prédicats PQL définissent les règles du segment en fonction des conditions liées aux données d’enregistrement ou de série temporelle que vous fournissez à Real-time Customer Profile. Pour plus d’informations sur l’écriture de requêtes PQL, reportez-vous au guide de PQL.

Vous pouvez créer une nouvelle définition de segment en envoyant une requête POST au point de terminaison /segment/definitions de l’API Segmentation L’exemple suivant illustre la manière de formater une requête de définition, et inclut les informations requises pour qu’un segment soit défini avec succès.

Pour une explication détaillée de la définition d'un segment, consultez le guide du développeur de définitions de segment.

Estimation et prévisualisation d’une audience

Au fur et à mesure que vous développez votre définition de segment, vous pouvez utiliser les outils d'estimation et de prévisualisation dans Real-time Customer Profile pour vue des informations de synthèse afin de vous assurer que vous isolez l'audience attendue. Les estimations fournissent des informations statistiques sur une définition de segment telles que la taille prévue de l’audience et l’intervalle de confiance. Les prévisualisations fournissent des listes paginées des profils admissibles pour une définition de segment, ce qui vous permet de comparer les résultats avec vos attentes.

En estimant et en prévisualisant votre audience, vous pouvez tester et optimiser vos prédicats PQL jusqu’à ce qu’ils produisent un résultat souhaitable. Ils peuvent alors être utilisés dans une définition de segment mise à jour.

Deux étapes sont nécessaires pour prévisualiser ou obtenir une estimation de votre segment :

  1. Création d’une tâche de prévisualisation
  2. Afficher l’estimation ou la prévisualisation à l’aide de l’identifiant de la tâche de prévisualisation

Comment sont générées les estimations

Des exemples de données sont utilisés pour évaluer les segments et estimer le nombre de profils admissibles. De nouvelles données sont chargées dans la mémoire chaque matin (entre 0 h et 2 h PT, soit entre 7 h et 9 h UTC) et toutes les requêtes de segmentation sont estimées à l’aide des exemples de données de cette journée. Par conséquent, tous les nouveaux champs ajoutés ou toutes les données supplémentaires recueillies seront pris en compte dans les estimations du lendemain.

La taille de l’échantillon dépend du nombre total d’entités dans votre banque de profils. Ces tailles d’échantillon sont représentées dans le tableau suivant :

Entités dans la banque de profils Taille de l’échantillon
Moins de 1 million Jeu de données complet
1 à 20 millions 1 million
Plus de 20 millions 5 % du total

Les estimations durent généralement entre 10 et 15 secondes. L’estimation est d’abord approximative, et se précise au fur et à mesure de la lecture d’un plus grand nombre d’enregistrements.

Création d’une tâche de prévisualisation

Vous pouvez créer une nouvelle tâche de prévisualisation en exécutant une requête POST sur le point de terminaison /preview.

Vous trouverez des instructions détaillées sur la création d'une tâche de prévisualisation dans le guide des points de terminaison des prévisualisations et estimations.

Affichage d’une estimation ou d’une prévisualisation

Les processus d’estimation et de prévisualisation sont exécutés de manière asynchrone, car le temps de traitement peut différer d’une requête à une autre. Une fois qu’une requête a été lancée, vous pouvez utiliser des appels API pour récupérer (GET) l’état actuel de l’estimation ou de la prévisualisation au fur et à mesure de sa progression.

L'API Segmentation Service vous permet de rechercher l'état actuel d'une tâche de prévisualisation par son identifiant. Si l’état affiche « RESULT_READY », vous pouvez consulter les résultats. Pour connaître l'état actuel d'une tâche de prévisualisation, consultez la section récupération d'une section de tâche de prévisualisation du guide des points de terminaison des prévisualisations et estimations. Pour connaître l'état actuel d'un travail d'estimation, consultez la section Récupération d'un travail d'estimation dans le guide des points de terminaison des prévisualisations et estimations.

Étapes suivantes

Une fois que vous avez développé, testé et enregistré votre définition de segment, vous pouvez créer une tâche de segment afin de créer une audience à l’aide de l’API Segmentation Service. Consultez le tutoriel portant sur l’évaluation et l’accès aux résultats des segments pour obtenir des instructions détaillées sur la manière d’y parvenir.

Sur cette page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now