Valutazione e accesso ai risultati dei segmenti

Questo documento fornisce un'esercitazione per valutare i segmenti e accedere ai risultati dei segmenti utilizzando Segmentation API.

Introduzione

Questa esercitazione richiede una conoscenza approfondita dei vari servizi Adobe Experience Platform coinvolti nella creazione di segmenti di pubblico. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi:

  • Real-time Customer Profile: Fornisce un profilo cliente unificato in tempo reale basato su dati aggregati provenienti da più origini.
  • Adobe Experience Platform Segmentation Service: Consente di creare segmenti di pubblico dai Real-time Customer Profile dati.
  • Experience Data Model (XDM): Il framework standardizzato tramite il quale la piattaforma organizza i dati sull'esperienza cliente.
  • Sandbox: Experience Platform fornisce sandbox virtuali che dividono una singola Platform istanza in ambienti virtuali separati per sviluppare e sviluppare applicazioni per esperienze digitali.

Intestazioni necessarie

Questa esercitazione richiede inoltre di aver completato l' esercitazione sull'autenticazione al fine di effettuare correttamente le chiamate alle Platform API. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come illustrato di seguito:

  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Le richieste alle Platform API richiedono un'intestazione che specifica il nome della sandbox in cui verrà eseguita l'operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Per ulteriori informazioni sulle sandbox in Platform, consultate la documentazione di panoramica sulla sandbox.

Tutte le richieste di POST, PUT e PATCH richiedono un'intestazione aggiuntiva:

  • Content-Type: application/json

Valutazione di un segmento

Dopo aver sviluppato, testato e salvato la definizione del segmento, puoi valutare il segmento tramite una valutazione programmata o su richiesta.

La valutazione pianificata (detta anche "segmentazione pianificata") consente di creare una pianificazione periodica per l’esecuzione di un processo di esportazione in un momento specifico, mentre la valutazione su richiesta comporta la creazione di un processo segmento per creare immediatamente l’audience. Di seguito sono descritti i passaggi da seguire per ciascuno di essi.

Se non hai ancora completato la creazione di un segmento tramite l'esercitazione API di segmentazione o creato una definizione di segmento utilizzando Generatore di segmenti, esegui questa esercitazione prima di continuare.

Valutazione pianificata

Mediante la valutazione pianificata, l’organizzazione IMS può creare una pianificazione periodica per eseguire automaticamente i processi di esportazione.

NOTA

La valutazione pianificata può essere abilitata per le sandbox con un massimo di cinque (5) criteri di unione per XDM Individual Profile. Se l'organizzazione dispone di più di cinque criteri di unione per XDM Individual Profile all'interno di un unico ambiente sandbox, non sarà possibile utilizzare la valutazione pianificata.

Creare una pianificazione

Eseguendo una richiesta POST all'endpoint /config/schedules, potete creare una pianificazione e includere l'ora specifica in cui avviare la pianificazione.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida dell'endpoint di pianificazione

Attivare una pianificazione

Per impostazione predefinita, una pianificazione è inattiva quando viene creata, a meno che la proprietà state sia impostata su active nel corpo della richiesta di creazione (POST). Puoi abilitare una pianificazione (impostare state su active) effettuando una richiesta di PATCH all'endpoint /config/schedules e includendo l'ID della pianificazione nel percorso.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida dell'endpoint di pianificazione

Aggiornamento dell'ora di pianificazione

È possibile aggiornare i tempi di pianificazione effettuando una richiesta di PATCH all'endpoint /config/schedules e includendo l'ID della pianificazione nel percorso.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida dell'endpoint di pianificazione

Valutazione su richiesta

La valutazione su richiesta consente di creare un processo di segmento per generare un segmento di pubblico ogni volta che lo desiderate. A differenza della valutazione pianificata, ciò si verificherà solo se richiesto e non ricorrente.

Creazione di un processo di segmento

Un processo di segmento è un processo asincrono che crea un nuovo segmento di pubblico. Fa riferimento a una definizione di segmento, nonché a qualsiasi criterio di unione che controlla il modo in cui Real-time Customer Profile unisce gli attributi sovrapposti nei frammenti di profilo. Quando un processo del segmento viene completato correttamente, potete raccogliere varie informazioni sul segmento, ad esempio eventuali errori che si sono verificati durante l'elaborazione e le dimensioni finali del pubblico.

Puoi creare un nuovo processo per segmenti effettuando una richiesta di POST all'endpoint /segment/jobs nell'API Real-time Customer Profile.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi del segmento

Cerca stato processo segmento

È possibile utilizzare id per un processo segmento specifico per eseguire una richiesta di ricerca (GET) al fine di visualizzare lo stato corrente del processo.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi del segmento

Interpreta i risultati del segmento

Quando i processi del segmento vengono eseguiti correttamente, la mappa segmentMembership viene aggiornata per ciascun profilo incluso nel segmento. segmentMembership memorizza inoltre tutti i segmenti di pubblico pre-valutati a cui vengono inviati Platform, consentendo l'integrazione con altre soluzioni come Adobe Audience Manager.

L'esempio seguente mostra l'aspetto dell'attributo segmentMembership per ciascun record di profilo:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "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"
      }
    }
  }
}
Proprietà Descrizione
lastQualificationTime La marca temporale in cui è stata rilasciata l'asserzione dell'appartenenza al segmento e il profilo è entrato o uscito dal segmento.
status Stato della partecipazione al segmento come parte della richiesta corrente. Deve essere uguale a uno dei seguenti valori noti:
  • existing: L'entità continua a trovarsi nel segmento.
  • realized: L'entità sta entrando nel segmento.
  • exited: L'entità sta uscendo dal segmento.

Accesso ai risultati del segmento

È possibile accedere ai risultati di un processo segmento in uno dei due modi seguenti: puoi accedere a singoli profili o esportare un'intera audience in un dataset.

Le sezioni seguenti descrivono queste opzioni in modo più dettagliato.

Cercare un profilo

Se si conosce il profilo specifico a cui si desidera accedere, è possibile farlo utilizzando l'API Real-time Customer Profile. I passaggi completi per accedere ai singoli profili sono disponibili nell'esercitazione Access Real-time Customer Profile data (Accesso ai dati del profilo cliente in tempo reale) tramite l'API del profilo.

Esportare un segmento

Dopo che un processo di segmentazione è stato completato correttamente (il valore dell'attributo status è "SUCCEEDED"), potete esportare il pubblico in un set di dati in cui è possibile accedervi e agire.

Per esportare il pubblico sono necessari i seguenti passaggi:

Creare un dataset di destinazione

Quando si esporta un'audience, è necessario creare prima un set di dati di destinazione. È importante che il set di dati sia configurato correttamente per garantire il successo dell'esportazione.

Una delle considerazioni chiave è lo schema su cui si basa il dataset (schemaRef.id nella richiesta di esempio API di seguito). Per esportare un segmento, il dataset deve essere basato su XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Uno schema unione è uno schema di sola lettura generato dal sistema che aggrega i campi degli schemi che condividono la stessa classe, in questo caso si tratta della classe XDM Singolo profilo. Per ulteriori informazioni sugli schemi di visualizzazione dell'unione, vedere la sezione relativa al profilo cliente in tempo reale della guida per gli sviluppatori del Registro di sistema dello schema](…/…/xdm/api/getting-started.md).[

Esistono due modi per creare il set di dati necessario:

  • Utilizzo delle API: I passaggi descritti in questa esercitazione descrivono come creare un set di dati che faccia riferimento a tale set di dati XDM Individual Profile Union Schema utilizzando l' Catalog API.
  • Utilizzo dell'interfaccia utente: Per utilizzare l'interfaccia Adobe Experience Platform utente per creare un set di dati che fa riferimento allo schema dell'unione, seguire i passaggi dell' esercitazione dell'interfaccia utente, quindi tornare a questa esercitazione per procedere con i passaggi necessari per generare i profili dell'audience.

Se disponete già di un set di dati compatibile e ne conoscete l'ID, potete procedere direttamente al passaggio per generare profili di audience.

Formato API

POST /dataSets

Richiesta

La richiesta seguente crea un nuovo dataset, fornendo i parametri di configurazione nel 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: {IMS_ORG}' \
  -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"
    },
    "fileDescription": {
        "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    }
}'
Proprietà Descrizione
name Un nome descrittivo per il set di dati.
schemaRef.id ID della visualizzazione unione (schema) a cui sarà associato il set di dati.
fileDescription.persisted Un valore booleano che, se impostato su true, consente al dataset di rimanere nella visualizzazione unione.

Risposta

Una risposta corretta restituisce un array contenente l'ID univoco generato dal sistema di sola lettura del set di dati appena creato. Per esportare correttamente i membri dell'audience è necessario un ID dataset configurato correttamente.

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

Generazione di profili per i membri del pubblico

Una volta ottenuto un dataset persistente nell'unione, potete creare un processo di esportazione per mantenere i membri dell'audience nel dataset effettuando una richiesta di POST all'endpoint /export/jobs nell'API Real-time Customer Profile e fornendo l'ID del set di dati e le informazioni sul segmento per i segmenti che desiderate esportare.

Ulteriori informazioni sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di esportazione

Monitorare l'avanzamento dell'esportazione

Come processo di esportazione, potete controllarne lo stato effettuando una richiesta di GET all'endpoint /export/jobs e includendo la id del processo di esportazione nel percorso. Il processo di esportazione viene completato una volta che il campo status restituisce il valore "SUCCEEDED".

Ulteriori informazioni sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di esportazione

Passaggi successivi

Una volta completata l'esportazione, i dati sono disponibili entro il Data Lake in Experience Platform. È quindi possibile utilizzare Data Access API per accedere ai dati utilizzando la batchId associata all'esportazione. A seconda della dimensione del segmento, i dati possono essere in blocchi e il batch può essere composto da diversi file.

Per istruzioni dettagliate su come utilizzare l'API Data Access per accedere e scaricare file batch, seguire l' esercitazione sull'accesso ai dati.

È inoltre possibile accedere ai dati del segmento esportati correttamente utilizzando Adobe Experience Platform Query Service. Utilizzando l'interfaccia utente o RESTful API, Query Service è possibile scrivere, convalidare ed eseguire query sui dati all'interno della Data Lake.

Per ulteriori informazioni su come eseguire query ai dati sul pubblico, consulta la documentazione su Query Service.

In questa pagina