Attivare i tipi di pubblico on-demand tramite l’API di attivazione ad hoc

Panoramica overview

L’API di attivazione ad hoc consente agli addetti al marketing di attivare in modo programmatico i tipi di pubblico nelle destinazioni, in modo rapido ed efficiente, per le situazioni in cui è richiesta l’attivazione immediata.

Utilizza l’API di attivazione ad hoc per attivare i tipi di pubblico on-demand in destinazioni basate su file batch e, a partire dalla versione v4, in destinazioni basate su streaming e API. Consulta Attivare un’esecuzione di attivazione ad hoc più avanti in questa esercitazione.

Il diagramma seguente illustra il flusso di lavoro end-to-end per l’attivazione dei tipi di pubblico tramite l’API di attivazione ad-hoc, inclusi i processi di segmentazione che si svolgono in Experience Platform ogni 24 ore.

Casi d’uso use-cases

Vendite o promozioni flash flash-sales

Un retailer online sta preparando una vendita flash limitata e vuole avvisare i clienti con un breve preavviso. Tramite l’API di attivazione ad hoc di Experience Platform, il team marketing può esportare i tipi di pubblico on-demand e inviare rapidamente e-mail promozionali alla base clienti.

Attualità o ultime notizie current-events

Un hotel si aspetta un tempo inclemente nei giorni successivi e il team vuole informare rapidamente gli ospiti in arrivo, in modo che possano pianificare di conseguenza. Il team marketing può utilizzare l’API di attivazione ad hoc di Experience Platform per esportare i tipi di pubblico on-demand e avvisare gli ospiti.

Test di integrazione integration-testing

I responsabili IT possono utilizzare l’API di attivazione ad hoc di Experience Platform per esportare i tipi di pubblico on-demand, in modo da testare la loro integrazione personalizzata con Adobe Experience Platform e garantire il corretto funzionamento di tutto.

Aggiornamento del pubblico per le destinazioni di streaming audience-refresh-streaming

Una destinazione in streaming o basata su API applica un valore TTL (time-to-live) all’appartenenza al pubblico che riceve da Adobe Experience Platform. Quando tale TTL scade sul lato destinazione, i profili precedentemente qualificati vengono trattati come inattivi, anche se rimangono qualificati in Experience Platform. Il team marketing può utilizzare la versione 4 dell’API di attivazione ad hoc per inviare nuovamente on-demand l’iscrizione corrente completa di un pubblico, senza attendere il prossimo aggiornamento pianificato. Consulta Attivare un’esecuzione di attivazione ad hoc più avanti in questa esercitazione.

Guardrail guardrails

Quando utilizzi l’API di attivazione ad hoc, tieni presenti le seguenti protezioni.

Considerazioni sulla segmentazione segmentation-considerations

Adobe Experience Platform esegue i processi di segmentazione pianificati una volta ogni 24 ore. L’API di attivazione ad hoc viene eseguita in base ai risultati di segmentazione più recenti.

Passaggio 1: Prerequisiti prerequisites

Prima di poter effettuare chiamate alle API Adobe Experience Platform, assicurati di soddisfare i seguenti prerequisiti:

Passaggio 2: raccogliere le credenziali credentials

Per effettuare chiamate alle API di Experience Platform, devi prima completare l’esercitazione di autenticazione. Il completamento del tutorial di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

Le risorse in Experience Platform possono essere isolate in specifiche sandbox virtuali. Nelle richieste alle API di Experience Platform, puoi specificare il nome e l’ID della sandbox in cui verrà eseguita l’operazione. Si tratta di parametri facoltativi.

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione di tipo multimediale aggiuntiva:

Documentazione di riferimento API api-reference-documentation

Questa esercitazione contiene la documentazione di riferimento per tutte le operazioni API. Consulta il riferimento API di Ad Hoc Activation.

Passaggio 3: creare un flusso di attivazione nell’interfaccia utente di Experience Platform activation-flow

Prima di poter attivare i tipi di pubblico tramite l’API di attivazione ad hoc, è necessario aver configurato un flusso di attivazione nell’interfaccia utente di Experience Platform, per la destinazione scelta.

Ciò include l’accesso al flusso di lavoro di attivazione, la selezione dei tipi di pubblico, la configurazione di una pianificazione e l’attivazione di questi. Puoi utilizzare l’interfaccia o l’API per creare un flusso di attivazione:

Passaggio 4: ottieni l’ID del processo di esportazione del pubblico più recente (non richiesto nella versione v2) segment-export-id

Dopo aver configurato un flusso di attivazione per la destinazione batch, i processi di segmentazione pianificati iniziano a essere eseguiti automaticamente ogni 24 ore.

Prima di poter eseguire il processo di attivazione ad hoc, è necessario ottenere l’ID del processo di esportazione del pubblico più recente. Devi passare questo ID nella richiesta del processo di attivazione ad hoc.

Segui le istruzioni descritte qui per recuperare un elenco di tutti i processi di esportazione del pubblico.

Nella risposta, cerca il primo record che include la proprietà dello schema seguente.

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

L’ID del processo di esportazione del pubblico si trova nella proprietà id, come illustrato di seguito.

Passaggio 5: eseguire il processo di attivazione ad hoc activation-job

Adobe Experience Platform esegue i processi di segmentazione pianificati una volta ogni 24 ore. L’API di attivazione ad hoc viene eseguita in base ai risultati di segmentazione più recenti.

Prima di eseguire un processo di attivazione ad hoc, assicurati che il processo di esportazione pianificato per il pubblico sia stato completato. Per informazioni su come monitorare lo stato dei flussi di attivazione, vedere monitoraggio del flusso di dati di destinazione. Ad esempio, se il flusso di dati di attivazione mostra uno stato Elaborazione, attendi che termini prima di eseguire il processo di attivazione ad hoc per esportare un file completo.

Una volta completato il processo di esportazione del pubblico, puoi attivare l’attivazione.

Richiesta request

Per i tipi di pubblico del servizio non di segmentazione (ad esempio, pubblico di caricamento esterno o personalizzato), devi specificare l’ID del pubblico generato da Experience Platform nella richiesta, non l’ID del pubblico esterno. Puoi trovare l’ID generato dal sistema nella parte superiore del pannello di riepilogo del pubblico, visualizzato come ID# seguito da un UUID, quando apri la pagina dei dettagli del pubblico nell’interfaccia utente dei tipi di pubblico.

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"
      ]
   }
}'

Proprietà

Descrizione

• destinationId1
• destinationId2

Gli ID delle istanze di destinazione a cui desideri attivare i tipi di pubblico. Puoi ottenere questi ID dall’interfaccia utente di Experience Platform, passando a Destinazioni > Sfoglia scheda e facendo clic sulla riga di destinazione desiderata per visualizzare l’ID di destinazione nella barra a destra. Per ulteriori informazioni, consulta la documentazione dell’area di lavoro delle destinazioni.

• segmentId1
• segmentId2
• segmentId3

Gli ID dei tipi di pubblico che desideri attivare nella destinazione selezionata. Puoi utilizzare l’API ad hoc per esportare i tipi di pubblico generati da Experience Platform e quelli esterni (caricamento personalizzato). Quando attivi un pubblico esterno, utilizza l’ID generato dal sistema invece dell’ID del pubblico. L’ID generato dal sistema è disponibile nella visualizzazione di riepilogo del pubblico nell’interfaccia utente dei tipi di pubblico.
{width="100" modal="regular"}
{width="100" modal="regular"}

Richiesta con ID esportazione 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"
   ]
}

Risposta response

Una risposta corretta restituisce lo stato 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"
      }
   ]
}

Gestione degli errori API api-error-handling

Gli endpoint API di Destination SDK seguono i principi generali dei messaggi di errore API di Experience Platform. Consulta Codici di stato API e errori di intestazione della richiesta nella guida alla risoluzione dei problemi di Experience Platform.

Codici di errore API e messaggi specifici per l’API di attivazione ad hoc specific-error-messages

Quando utilizzi l’API di attivazione ad hoc, puoi incontrare messaggi di errore specifici per questo endpoint API. Rivedi la tabella per capire come gestirli quando vengono visualizzati.

(Beta) Attivare un’esecuzione di attivazione ad hoc streaming-destinations

Utilizza la versione 4 dell’API di attivazione ad hoc per attivare Attiva ora, un aggiornamento su richiesta dell’iscrizione completa di un pubblico a una destinazione in streaming o basata su API.

Molte destinazioni in streaming e basate su API applicano un TTL (time-to-live) all’iscrizione al pubblico che ricevono da Adobe Experience Platform. Quando tale TTL scade sul lato destinazione, i profili precedentemente qualificati vengono trattati come inattivi, anche se rimangono qualificati in Experience Platform. Attiva un’esecuzione di attivazione ad hoc v4 per inviare nuovamente ogni profilo attualmente qualificato tramite la pipeline di attivazione in streaming esistente, senza attendere il successivo aggiornamento pianificato.

Puoi anche attivare questo aggiornamento dall’interfaccia utente di Experience Platform. Leggi Attiva ora per le destinazioni di streaming.

Guardrail di streaming streaming-guardrails

L’attivazione ad hoc su destinazioni di streaming applica il seguente limite:

Richiesta streaming 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"
      ]
   }
}'

Risposta in streaming streaming-response

In caso di esito positivo, la risposta restituisce lo stato HTTP 202 (Accepted) e crea un processo di streaming per ogni pubblico richiesto.

{
   "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"
      }
   ]
}

Se per questo flusso di dati è già stato attivato lo stesso pubblico nelle ultime 24 ore, la richiesta viene rifiutata con HTTP 409 e un’intestazione Retry-After che indica quanti secondi mancano all’esecuzione di un nuovo tentativo.

Informazioni correlate related-information