Valutare e accedere ai risultati della definizione dei segmenti

Questo documento fornisce un tutorial per valutare le definizioni dei segmenti e accedere a questi risultati utilizzando Segmentation API.

Introduzione

Questo tutorial richiede una buona conoscenza dei vari servizi Adobe Experience Platform coinvolti nella creazione di tipi di pubblico. Prima di iniziare questo tutorial, consulta la documentazione dei 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 tipi di pubblico dai dati di Real-Time Customer Profile.
  • Experience Data Model (XDM): framework standardizzato in base al quale Platform organizza i dati sull’esperienza del cliente. Per utilizzare al meglio la segmentazione, assicurati che i dati vengano acquisiti come profili ed eventi in base alle best practice per la modellazione dei dati.
  • Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza di Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Intestazioni richieste

Questo tutorial richiede anche di aver completato l'esercitazione di autenticazione per effettuare correttamente le chiamate alle API Platform. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

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

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

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

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

  • Content-Type: application/json

Valutare una definizione di segmento evaluate-a-segment

Dopo aver sviluppato, testato e salvato la definizione del segmento, puoi valutarla tramite valutazione pianificata o su richiesta.

La valutazione pianificata (nota anche come 'segmentazione pianificata') consente di creare una pianificazione ricorrente per l'esecuzione di un processo di esportazione in un momento specifico, mentre la valutazione on demand comporta la creazione di un processo di segmentazione per la generazione immediata del pubblico. Di seguito sono descritti i passaggi per ciascuno di essi.

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

Valutazione programmata scheduled-evaluation

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

NOTE
È possibile abilitare la valutazione pianificata per le sandbox con un massimo di cinque (5) criteri di unione per XDM Individual Profile. Se nell'organizzazione sono presenti più di cinque criteri di unione per XDM Individual Profile in un singolo ambiente sandbox, non sarà possibile utilizzare la valutazione pianificata.

Creare una pianificazione

Effettuando una richiesta POST all'endpoint /config/schedules, è possibile creare una pianificazione e includere l'ora specifica in cui attivare la pianificazione.

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

Abilitare una pianificazione

Per impostazione predefinita, una pianificazione non è attiva al momento della creazione, a meno che la proprietà state non sia impostata su active nel corpo della richiesta di creazione (POST). È possibile abilitare una pianificazione (impostare state su active) effettuando una richiesta 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 degli endpoint di pianificazione

Aggiornare l’ora di pianificazione

È possibile aggiornare la tempistica della pianificazione effettuando una richiesta 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 degli endpoint di pianificazione

Valutazione a richiesta

La valutazione on-demand consente di creare un processo di segmentazione per generare un pubblico ogni volta che necessario. A differenza della valutazione pianificata, questa si verifica solo quando richiesto e non è ricorrente.

Creare un processo di segmentazione

Un processo di segmentazione è un processo asincrono che crea un segmento di pubblico su richiesta. Fa riferimento a una definizione di segmento, nonché a eventuali criteri di unione che controllano il modo in cui Real-Time Customer Profile unisce attributi sovrapposti tra i frammenti di profilo. Al termine di un processo di segmentazione, puoi raccogliere varie informazioni sulla definizione del segmento, ad esempio eventuali errori che si sono verificati durante l’elaborazione e le dimensioni finali del pubblico. È necessario eseguire un processo di segmentazione ogni volta che desideri aggiornare il pubblico attualmente qualificato dalla definizione del segmento.

È possibile creare un nuovo processo di segmentazione effettuando una richiesta POST all'endpoint /segment/jobs nell'API Real-Time Customer Profile.

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

Cercare lo stato del processo di segmento

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

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

Interpretare i risultati del processo segmento

Quando i processi di segmentazione vengono eseguiti correttamente, la mappa segmentMembership viene aggiornata per ogni profilo incluso nella definizione del segmento. segmentMembership memorizza anche eventuali tipi di pubblico pre-valutati che vengono acquisiti in Platform, consentendo l'integrazione con altre soluzioni come Adobe Audience Manager.

Nell'esempio seguente viene illustrato l'aspetto dell'attributo segmentMembership per ogni singolo record di profilo:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      },
      "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
Il timestamp in cui è stata effettuata l’asserzione di appartenenza al segmento e il profilo è entrato o uscito dalla definizione del segmento.
status

Lo stato di partecipazione della definizione del segmento come parte della richiesta corrente. Deve essere uguale a uno dei seguenti valori noti:

  • realized: l'entità è idonea per la definizione del segmento.
  • exited: l'entità sta uscendo dalla definizione del segmento.
NOTE
Qualsiasi appartenenza a un segmento con stato exited per più di 30 giorni, in base a lastQualificationTime, sarà soggetta a eliminazione.

Accedere ai risultati del processo di segmentazione

È possibile accedere ai risultati di un processo di segmentazione in uno dei due modi seguenti: accedere a singoli profili o esportare un intero pubblico in un set di dati.

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 utilizzare l'API Real-Time Customer Profile. I passaggi completi per l'accesso ai singoli profili sono disponibili nell'esercitazione Accedere ai dati del profilo cliente in tempo reale utilizzando l'API profilo.

Esportare un segmento export

Dopo il completamento di un processo di segmentazione (il valore dell'attributo status è "RIUSCITO"), è possibile esportare il pubblico in un set di dati in cui è possibile accedervi e agire di conseguenza.

Per esportare il pubblico, sono necessari i seguenti passaggi:

Creare un set di dati di destinazione create-dataset

Durante l’esportazione di un pubblico, è necessario creare prima un set di dati di destinazione. È importante che il set di dati sia configurato correttamente per garantire l’esportazione in modo corretto.

Una delle considerazioni chiave è lo schema su cui si basa il set di dati (schemaRef.id nella richiesta di esempio API seguente). Per esportare una definizione di segmento, il set di dati deve essere basato su XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Uno schema di unione è uno schema di sola lettura generato dal sistema che aggrega i campi degli schemi che condividono la stessa classe, in questo caso la classe XDM Individual Profile. Per ulteriori informazioni sugli schemi di visualizzazione unione, consulta la sezione Profilo cliente in tempo reale della Guida per gli sviluppatori del registro degli schemi.

Esistono due modi per creare il set di dati necessario:

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

Se disponi già di un set di dati compatibile e conosci il relativo ID, puoi procedere direttamente al passaggio per generare profili di pubblico.

Formato API

POST /dataSets

Richiesta

La richiesta seguente crea un nuovo set di dati, 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: {ORG_ID}' \
  -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"
    }
}'
Proprietà
Descrizione
name
Nome descrittivo del set di dati.
schemaRef.id
ID della visualizzazione unione (schema) a cui verrà associato il set di dati.

Risposta

In caso di esito positivo, la risposta restituisce un array contenente l’ID univoco di sola lettura generato dal sistema per il set di dati appena creato. Per esportare correttamente i membri del pubblico è necessario un ID set di dati configurato correttamente.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Generare profili per i membri del pubblico generate-profiles

Dopo aver creato un set di dati persistente nell'unione, puoi creare un processo di esportazione per rendere persistenti i membri del pubblico nel set di dati effettuando una richiesta POST all'endpoint /export/jobs nell'API Real-Time Customer Profile e fornendo l'ID del set di dati e le informazioni di definizione del segmento per le definizioni dei segmenti che desideri esportare.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida dell'endpoint dei processi di esportazione

Monitorare l’avanzamento dell’esportazione

Durante l'elaborazione di un processo di esportazione, è possibile monitorarne lo stato effettuando una richiesta di GET all'endpoint /export/jobs e includendo id del processo di esportazione nel percorso. Il processo di esportazione viene completato quando il campo status restituisce il valore "SUCCESSEDED".

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida dell'endpoint dei processi di esportazione

Passaggi successivi

Una volta completata l'esportazione, i dati saranno disponibili in Data Lake in Experience Platform. È quindi possibile utilizzare Data Access API per accedere ai dati utilizzando batchId associato all'esportazione. A seconda delle dimensioni della definizione del segmento, i dati possono essere in blocchi e il batch può essere costituito da diversi file.

Per istruzioni dettagliate sull'utilizzo dell'API Data Access per accedere e scaricare i file batch, seguire l'esercitazione sull'accesso ai dati.

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

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

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871