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

IMPORTANT
Dopo aver completato la fase Beta, ad-hoc activation API è ora generalmente disponibile (GA) per tutti i clienti Experienci Platform. Nella versione GA, l’API è stata aggiornata alla versione 2. Passaggio 4 (Ottieni l’ID del processo di esportazione del pubblico più recente) non è più richiesto, in quanto l’API non richiede più l’ID di esportazione.
Consulta Eseguire il processo di attivazione ad hoc più avanti in questo tutorial per ulteriori informazioni.

Panoramica overview

L’API di attivazione ad hoc consente agli addetti al marketing di attivare in modo programmatico il 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 esportare file completi nel sistema di ricezione dei file desiderato. L’attivazione ad hoc del pubblico è supportata solo da destinazioni basate su file batch.

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 Platform ogni 24 ore.

ad-hoc-activation

Casi d’uso use-cases

Vendite o promozioni Flash

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

Attualità o ultime notizie

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 Experienci Platform per esportare i tipi di pubblico on-demand e avvisare gli ospiti.

Test di integrazione

I responsabili IT possono utilizzare l’API di attivazione ad hoc di Experienci 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.

Guardrail guardrails

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

  • Attualmente, ogni processo di attivazione ad hoc può attivare fino a 80 tipi di pubblico. Se si tenta di attivare più di 80 tipi di pubblico per processo, il processo non riuscirà. Questo comportamento è soggetto a modifiche nelle versioni future.
  • I processi di attivazione ad hoc non possono essere eseguiti in parallelo con i processi pianificati processi di esportazione pubblico. Prima di eseguire un processo di attivazione ad hoc, assicurati che il processo di esportazione del pubblico pianificato sia stato completato. Consulta monitoraggio del flusso di dati di destinazione per informazioni su come monitorare lo stato dei flussi di attivazione. Ad esempio, se il flusso di dati di attivazione mostra Elaborazione stato, attendi il termine prima di eseguire il processo di attivazione ad hoc.
  • Non eseguire più di un processo di attivazione ad hoc simultaneo per pubblico.

Considerazioni sulla segmentazione segmentation-considerations

Adobe Experience Platform esegue 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 di Adobe Experience Platform, assicurati di soddisfare i seguenti prerequisiti:

  • Hai un account organizzazione con accesso a Adobe Experience Platform.
  • Il tuo account di Experience Platform ha developer e user ruoli abilitati per il profilo di prodotto API Adobe Experience Platform. Contatta il tuo Admin Console per abilitare questi ruoli per il tuo account.
  • Hai un Adobe ID. Se non disponi di un Adobe ID, vai al Console Adobe Developer e crea un nuovo account.

Passaggio 2: raccogliere le credenziali credentials

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

  • Autorizzazione: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

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

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
Per ulteriori informazioni sulle sandbox in Experienci Platform, consulta la sezione documentazione di panoramica sulla sandbox.

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

  • Tipo di contenuto: application/json

Passaggio 3: creare un flusso di attivazione nell’interfaccia utente di 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 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

IMPORTANT
Nella versione 2 dell’API di attivazione ad hoc, non è necessario ottenere l’ID del processo di esportazione del pubblico più recente. Puoi saltare questo passaggio e passare a quello successivo.

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.

Seguire 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 in id come mostrato di seguito.

ID processo esportazione pubblico

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

Adobe Experience Platform esegue 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.

IMPORTANT
Nota il seguente vincolo relativo all’attivazione una tantum: prima di eseguire un processo di attivazione ad hoc, assicurati che siano trascorsi almeno 20 minuti dal momento in cui il pubblico è stato attivato per la prima volta in base alla pianificazione impostata in Passaggio 3: creare un flusso di attivazione nell’interfaccia utente di Platform.

Prima di eseguire un processo di attivazione ad hoc, assicurati che il processo di esportazione pianificato per il pubblico sia stato completato. Consulta monitoraggio del flusso di dati di destinazione per informazioni su come monitorare lo stato dei flussi di attivazione. Ad esempio, se il flusso di dati di attivazione mostra Elaborazione stato, attendi il termine 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.

NOTE
Attualmente, ogni processo di attivazione ad hoc può attivare fino a 80 tipi di pubblico. Se si tenta di attivare più di 80 tipi di pubblico per processo, il processo non riuscirà. Questo comportamento è soggetto a modifiche nelle versioni future.

Richiesta request

IMPORTANT
È obbligatorio includere Accept: application/vnd.adobe.adhoc.activation+json; version=2 nella richiesta per utilizzare la v2 dell’API di attivazione ad hoc.
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 Platform, passando a Destinazioni > Sfoglia e facendo clic sulla riga di destinazione desiderata per visualizzare l’ID di destinazione nella barra a destra. Per ulteriori informazioni, leggere documentazione di destination workspace.
  • 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 Platform e quelli esterni (caricamento personalizzato). Quando attivi un pubblico esterno, utilizza l’ID generato dal sistema invece dell’ID del pubblico. Puoi trovare l’ID generato dal sistema nella vista di riepilogo del pubblico nell’interfaccia utente dei tipi di pubblico.
Visualizzazione dell’ID del pubblico che non deve essere selezionato. {width="100" modal="regular"}
Visualizzazione dell’ID del pubblico generato dal sistema che deve essere utilizzato. {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"
   ]
}
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 Platform, passando a Destinazioni > Sfoglia e facendo clic sulla riga di destinazione desiderata per visualizzare l’ID di destinazione nella barra a destra. Per ulteriori informazioni, leggere documentazione di destination workspace.
  • segmentId1
  • segmentId2
  • segmentId3
Gli ID dei tipi di pubblico che desideri attivare nella destinazione selezionata.
  • exportId1
L'ID restituito nella risposta del esportazione pubblico lavoro. Consulta Passaggio 4: ottieni l’ID del processo di esportazione del pubblico più recente per istruzioni su come trovare questo ID.

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"
      }
   ]
}
Proprietà
Descrizione
segment
ID del pubblico attivato.
order
ID della destinazione in cui è stato attivato il pubblico.
statusURL
URL dello stato del flusso di attivazione. Puoi tenere traccia dell’avanzamento del flusso utilizzando API del servizio Flusso.

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. Fai riferimento a Codici di stato API e errori di intestazione della richiesta nella guida alla risoluzione dei problemi di 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.

Messaggio di errore
Risoluzione
Esecuzione già in corso per il pubblico segment ID per ordine dataflow ID con id esecuzione flow run ID
Questo messaggio di errore indica che per un pubblico è attualmente in corso un flusso di attivazione ad hoc. Attendere il completamento del processo prima di riattivarlo.
Segmenti <segment name> non fanno parte di questo flusso di dati o non rientrano nell’intervallo di pianificazione.
Questo messaggio di errore indica che i tipi di pubblico selezionati per l’attivazione non sono mappati al flusso di dati o che la pianificazione di attivazione impostata per i tipi di pubblico è scaduta o non è ancora stata avviata. Controlla se il pubblico è effettivamente mappato al flusso di dati e verifica che la pianificazione di attivazione del pubblico si sovrapponga alla data attuale.

Informazioni correlate related-information

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6