Valutazione e accesso ai risultati dei segmenti

Questo documento fornisce un'esercitazione per la valutazione dei segmenti e l'accesso ai risultati dei segmenti mediante l' Segmentation API.

Introduzione

Questa esercitazione richiede una conoscenza approfondita dei vari Adobe Experience Platform servizi 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 anche di aver completato l'esercitazione di autenticazione per 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 Experience Platform API, 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 si svolgerà l'operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE

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

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 (nota anche come "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 hai creato una definizione di segmento con Segment Builder, effettua questa operazione prima di continuare con questa esercitazione.

Valutazione programmata

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

NOTE

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 un unico ambiente sandbox, non sarà possibile utilizzare la valutazione pianificata.

Creare una pianificazione

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

Per informazioni più dettagliate sull'utilizzo di questo endpoint, consultate la guida all'endpoint delle pianificazioni.

Attivare una pianificazione

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

Per informazioni più dettagliate sull'utilizzo di questo endpoint, consultate la guida all'endpoint delle pianificazioni.

Aggiornamento dell'ora di pianificazione

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

Per informazioni più dettagliate sull'utilizzo di questo endpoint, consultate la guida all'endpoint delle pianificazioni.

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 controlli 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’ /segment/jobs endpoint nell’ Real-time Customer Profile API.

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

Cerca stato processo segmento

È possibile utilizzare l' 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 segmentMembership mappa viene aggiornata per ogni 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 segmentMembership dell'attributo 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 conoscete il profilo specifico a cui desiderate accedere, potete farlo utilizzando l' Real-time Customer Profile API. I passaggi completi per accedere ai singoli profili sono disponibili nei dati Access Real-time Customer Profile (Profilo cliente in tempo reale) tramite l'esercitazione Profile API (API profilo).

Esportare un segmento

Dopo che un processo di segmentazione è stato completato correttamente (il valore dell' status attributo è "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 sul 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 Profilo cliente in tempo reale della guidaper gli sviluppatori del Registro di sistema dello schema.

Esistono due modi per creare il set di dati necessario:

  • Utilizzo delle API: I passaggi che seguono in questa esercitazione descrivono come creare un set di dati che faccia riferimento a tale oggetto XDM Individual Profile Union Schema utilizzando l' Catalog API.
  • Utilizzo dell’interfaccia utente: Per utilizzare l'interfaccia Adobe Experience Platform utente per creare un dataset che faccia 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 la generazione dei profilidell'audience.

Se disponete già di un set di dati compatibile e ne conoscete l’ID, potete procedere direttamente alla fase di generazione dei profilidi 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 persistere 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 dell'audience

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' /export/jobs endpoint nell' Real-time Customer Profile API 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’ /export/jobs endpoint e includendo nel percorso id il processo di esportazione. Il processo di esportazione viene completato una volta che il status campo 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 all'interno del Data Lake modulo Experience Platform. È quindi possibile utilizzare l’icona Data Access API per accedere ai dati utilizzando l’icona 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' Data Access API per accedere e scaricare file batch, segui l'esercitazione sull'accesso aidati.

Puoi anche accedere ai dati del segmento esportati correttamente utilizzando Adobe Experience Platform Query Service. L’utilizzo dell’interfaccia utente o dell’API RESTful Query Service consente di scrivere, convalidare ed eseguire query sui dati all’interno dell’ Data Lake.

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

In questa pagina