Activer les audiences à la demande via l’API d’activation ad hoc

Vue d’ensemble overview

L’API d’activation ad hoc permet aux spécialistes marketing d’activer par programmation les audiences vers les destinations, de manière rapide et efficace, dans les cas où une activation immédiate est requise.

Utilisez l’API d’activation ad hoc pour activer les audiences à la demande vers des destinations basées sur des fichiers par lots et, à partir de la version 4, vers des destinations en flux continu et basées sur des API. Voir Déclencher une exécution d’activation ad hoc plus bas dans ce tutoriel.

Le diagramme ci-dessous illustre le workflow de bout en bout pour activer des audiences via l’API d’activation ad hoc, y compris les tâches de segmentation qui ont lieu dans Experience Platform toutes les 24 heures.

Cas d’utilisation use-cases

Ventes ou promotions Flash flash-sales

Un retailer en ligne prépare une vente flash limitée et souhaite avertir les clients dans un court délai. Grâce à l’API d’activation ad hoc d’Experience Platform, l’équipe marketing peut exporter des audiences à la demande et envoyer rapidement des e-mails promotionnels à la base de clients.

Événements actuels ou dernières nouvelles current-events

Un hôtel s’attend à un mauvais temps les jours suivants, et l’équipe souhaite informer rapidement les clients afin qu’ils puissent se préparer en conséquence. L’équipe marketing peut utiliser l’API d’activation ad hoc d’Experience Platform pour exporter des audiences à la demande et informer les invités.

Test de l’intégration integration-testing

Les responsables informatiques peuvent utiliser l’API d’activation ad hoc d’Experience Platform pour exporter des audiences à la demande, afin de pouvoir tester leur intégration personnalisée à Adobe Experience Platform et s’assurer que tout fonctionne correctement.

Actualisation de l’audience pour les destinations de diffusion en streaming audience-refresh-streaming

Une destination en flux continu ou basée sur une API applique une durée de vie (TTL) à l’appartenance à l’audience qu’elle reçoit de Adobe Experience Platform. Lorsque cette TTL expire du côté de la destination, les profils précédemment qualifiés sont traités comme inactifs, même s’ils restent qualifiés dans Experience Platform. L’équipe marketing peut utiliser la version v4 de l’API d’activation ad hoc pour renvoyer l’abonnement actuel complet d’une audience à la demande, sans attendre la prochaine actualisation planifiée. Voir Déclencher une exécution d’activation ad hoc plus bas dans ce tutoriel.

Mécanismes de sécurisation guardrails

Gardez à l’esprit les mécanismes de sécurisation suivants lors de l’utilisation de l’API d’activation ad hoc .

Considérations relatives à la segmentation segmentation-considerations

Adobe Experience Platform exécute des tâches de segmentation planifiées une fois toutes les 24 heures. L’API d’activation ad hoc s’exécute en fonction des derniers résultats de segmentation.

Etape 1 : prérequis prerequisites

Avant d’effectuer des appels vers les API Adobe Experience Platform, veillez à respecter les conditions préalables suivantes :

Étape 2 : collecter les informations d’identification credentials

Pour lancer des appels aux API Experience Platform, vous devez d’abord suivre le tutoriel authentification. Le tutoriel sur l’authentification indique les valeurs de chacun des en-têtes requis dans tous les appels API Experience Platform, comme illustré ci-dessous :

Les ressources d’Experience Platform peuvent être isolées dans des sandbox virtuels 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.

Toutes les requêtes qui contiennent un payload (POST, PUT, PATCH) nécessitent un en-tête de type de média supplémentaire :

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. Voir ​ Référence de l’API d’activation ad hoc ​.

Étape 3 : créer un flux d’activation dans l’interface utilisateur d’Experience Platform activation-flow

Avant de pouvoir activer des audiences par le biais de l’API d’activation ad hoc, vous devez d’abord configurer un flux d’activation dans l’interface utilisateur d’Experience Platform, pour la destination choisie.

Cela inclut l’entrée dans le workflow d’activation, la sélection de vos audiences, la configuration d’un planning et leur activation. Vous pouvez utiliser l’interface utilisateur ou l’API pour créer un flux d’activation :

Étape 4 : obtenir le dernier identifiant de tâche d’exportation d’audience (non requis dans v2) segment-export-id

Une fois que vous avez configuré un flux d’activation pour la destination par lots, les tâches de segmentation planifiées commencent à s’exécuter automatiquement toutes les 24 heures.

Avant de pouvoir exécuter la tâche d’activation ad hoc, vous devez obtenir l’identifiant de la dernière tâche d’exportation d’audience. Vous devez transmettre cet identifiant dans la demande de traitement d’activation ad hoc.

Suivez les instructions décrites ici pour récupérer une liste de toutes les tâches d’exportation d’audience.

Dans la réponse, recherchez le premier enregistrement qui inclut la propriété de schéma ci-dessous.

"schema":{
   "name":"_xdm.context.profile"
}

L’identifiant de la tâche d’exportation d’audience se trouve dans la propriété id , comme illustré ci-dessous.

Étape 5 : exécuter la tâche d’activation ad hoc activation-job

Adobe Experience Platform exécute des tâches de segmentation planifiées une fois toutes les 24 heures. L’API d’activation ad hoc s’exécute en fonction des derniers résultats de segmentation.

Avant d’exécuter une tâche d’activation ad hoc, assurez-vous que la tâche d’exportation d’audience planifiée pour vos audiences est terminée. Consultez surveillance des flux de données de destination pour plus d’informations sur la surveillance du statut des flux d’activation. Par exemple, si votre flux de données d’activation affiche un statut Traitement, attendez qu’il soit terminé avant d’exécuter la tâche d’activation ad hoc pour exporter un fichier complet.

Une fois la tâche d’exportation d’audience terminée, vous pouvez déclencher l’activation.

Requête request

Pour les audiences de service non segmentées (par exemple, audiences de chargement externes ou personnalisées), vous devez spécifier l’ID d’audience généré par Experience Platform dans votre requête, et non l’ID d’audience externe. En haut du panneau Résumé de l’audience se trouve l’identifiant généré par le système sous la forme ID# suivi d’un UUID, lorsque vous ouvrez la page des détails de l’audience dans l’interface utilisateur des audiences.

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

Propriété

Description

• destinationId1
• destinationId2

Identifiants des instances de destination vers lesquelles vous souhaitez activer des audiences. Vous pouvez obtenir ces identifiants à partir de l’interface utilisateur d’Experience Platform en accédant à l’onglet Destinations > Parcourir, puis en cliquant sur la ligne de destination souhaitée pour afficher l’identifiant de destination dans le rail de droite. Pour plus d’informations, consultez la documentation de l’espace de travail des destinations.

• segmentId1
• segmentId2
• segmentId3

Identifiants des audiences que vous souhaitez activer vers la destination sélectionnée. Vous pouvez utiliser l’API ad hoc pour exporter des audiences générées par Experience Platform, ainsi que des audiences externes (chargement personnalisé). Lors de l’activation d’audiences externes, utilisez l’identifiant généré par le système plutôt que l’identifiant d’audience. L’identifiant généré par le système est disponible dans la vue de résumé de l’audience dans l’interface utilisateur des audiences.
{width="100" modal="regular"}
{width="100" modal="regular"}

Requête avec ID d’export request-export-ids

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

Réponse response

Une réponse réussie renvoie un statut HTTP 200.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

Gestion des erreurs d’API api-error-handling

Les points d’entrée de l’API Destination SDK suivent les principes généraux des messages d’erreur de l’API Experience Platform. Voir Codes d’état API et Erreurs d’en-tête de requête dans le guide de dépannage d’Experience Platform.

Codes d’erreur d’API et messages spécifiques à l’API d’activation ad hoc specific-error-messages

Lors de l’utilisation de l’API d’activation ad hoc, vous pouvez rencontrer des messages d’erreur spécifiques à ce point d’entrée de l’API. Consultez le tableau pour comprendre comment y remédier lorsqu’ils apparaissent.

(Beta) Déclencher une exécution d’activation ad hoc streaming-destinations

Utilisez la version v4 de l’API d’activation ad hoc pour déclencher Activer maintenant, une actualisation à la demande avec abonnement complet d’une audience vers une destination en flux continu ou basée sur une API.

De nombreuses destinations de streaming et basées sur les API appliquent une durée de vie (TTL) à l’appartenance à l’audience qu’elles reçoivent de Adobe Experience Platform. Lorsque cette TTL expire du côté de la destination, les profils précédemment qualifiés sont traités comme inactifs, même s’ils restent qualifiés dans Experience Platform. Déclenchez une exécution d’activation ad hoc v4 pour renvoyer chaque profil actuellement qualifié par le biais du pipeline d’activation de diffusion en continu existant, sans attendre la prochaine actualisation planifiée.

Vous pouvez également déclencher cette actualisation à partir de l’interface utilisateur d’Experience Platform. Lisez Activer maintenant pour les destinations de diffusion en streaming.

Mécanismes de sécurisation en flux continu streaming-guardrails

L’activation ad hoc vers des destinations de diffusion en continu applique la limite suivante :

Requête de diffusion en continu streaming-request

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

Réponse en flux continu streaming-response

Une réponse réussie renvoie un statut HTTP 202 (Accepté) et crée une tâche de diffusion en continu par audience demandée.

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

Si la même audience a déjà été déclenchée pour ce flux de données au cours des dernières 24 heures, la requête est rejetée avec le HTTP 409 et un en-tête Retry-After indiquant le nombre de secondes avant que vous puissiez réessayer.

Informations connexes related-information