Show Menu
ARGOMENTI×

Creazione di un segmento

Questo documento fornisce un'esercitazione per lo sviluppo, il test, la visualizzazione in anteprima e il salvataggio di una definizione di segmento mediante l'API segmentation.yaml Segmentazione.
Per informazioni su come creare segmenti utilizzando l’interfaccia utente, consulta la guida di Segment Builder (Generatore di segmenti).

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:
  • Profilo cliente in tempo reale: Fornisce un profilo di consumo unificato e in tempo reale basato su dati aggregati provenienti da più origini.
  • Servizio di segmentazione della piattaforma Adobe Experience: Consente di creare segmenti di pubblico dai dati del profilo cliente in tempo reale.
  • Experience Data Model (XDM) : Il framework standardizzato tramite il quale la piattaforma organizza i dati sull'esperienza cliente.
Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per effettuare correttamente chiamate alle API della piattaforma.

Lettura di chiamate API di esempio

Questa esercitazione fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi della piattaforma Experience.

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle API della piattaforma, dovete prima completare l'esercitazione di autenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di 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. Tutte le richieste alle API della piattaforma richiedono un'intestazione che specifica il nome della sandbox in cui avrà luogo l'operazione:
  • x-sandbox-name: {SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Piattaforma, consultate la documentazione sulla panoramica della sandbox.
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva:
  • Content-Type: application/json

Sviluppo di una definizione di segmento

Il primo passo nella segmentazione consiste nel definire un segmento, rappresentato in un costrutto chiamato definizione di segmento. Una definizione di segmento è un oggetto che racchiude una query scritta in Profile Query Language (PQL). Questo oggetto è anche denominato predicato PQL . I predicati PQL definiscono le regole per il segmento in base alle condizioni relative a qualsiasi record o dati delle serie temporali forniti al profilo cliente in tempo reale. Per ulteriori informazioni sulla scrittura di query PQL, consultate la guida Panoramica della lingua query profilo (PQL) PQL.
Puoi creare una nuova definizione del segmento effettuando una richiesta POST all’ /segment/definitions endpoint nell’API Profilo cliente in tempo reale. L'esempio seguente illustra come formattare una richiesta di definizione, incluse le informazioni necessarie per definire correttamente un segmento.
Le definizioni dei segmenti possono essere valutate in due modi: segmentazione batch e segmentazione in streaming. La segmentazione in batch valuta i segmenti in base a una pianificazione preimpostata o quando la valutazione viene attivata manualmente, mentre la segmentazione in streaming valuta i segmenti non appena i dati vengono acquisiti in Piattaforma. Questa esercitazione utilizzerà la segmentazione batch . Per ulteriori informazioni sulla segmentazione in streaming, consultate la panoramica sulla segmentazione in streaming.
Formato API
POST /segment/definitions

Richiesta
La richiesta seguente crea una nuova definizione di segmento per uno schema denominato "MyProfile".
curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/definitions \
  -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": "My Sample Cart Abandons Segment Definition",
        "schema": {
            "name": "MyProfile",
        },
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "xEvent.metrics.commerce.abandons.value > 0",
        },
        "mergePolicyId": "mpid1",
        "description": "This Segment represents those users who have abandoned a cart"
    }'

Proprietà
Descrizione
name
Obbligatorio. Un nome univoco con cui fare riferimento al segmento.
schema
Obbligatorio. Schema associato alle entità nel segmento. È costituito da un campo id o name .
expression
Obbligatorio. Entità che contiene informazioni sui campi relativi alla definizione del segmento.
expression.type
Specifica il tipo di espressione. Attualmente, è supportato solo "PQL".
expression.format
Indica la struttura dell'espressione in valore. Attualmente è supportato il seguente formato:
  • pql/text : Una rappresentazione testuale di una definizione di segmento, in base alla grammatica PQL pubblicata. Ad esempio, workAddress.stateProvince = homeAddress.stateProvince .
expression.value
Un'espressione conforme al tipo indicato in expression.format .
mergePolicyId
Identificatore del criterio di unione da utilizzare per i dati esportati. Per ulteriori informazioni, consultare il documento di configurazione del criterio di unione.
description
Una descrizione leggibile dell'espressione.
Risposta
Una risposta corretta restituisce i dettagli della definizione del segmento appena creata, inclusa la definizione di sola lettura generata dal sistema, id che verrà utilizzata più avanti in questa esercitazione.
{
    "id": "1234",
    "name": "My Sample Cart Abandons Segment Definition",
    "description": "This Segment represents those users who have abandoned a cart",
    "type": "PQL",
    "format": "pql/text",
    "expression": "xEvent.metrics.commerce.abandons.value > 0",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/core/ups/segment/definitions/1234"
        }
    }
}

Stima e anteprima di un'audience

Mentre sviluppate la definizione del segmento, potete utilizzare gli strumenti di stima e anteprima nel profilo cliente in tempo reale per visualizzare le informazioni a livello di riepilogo per garantire che stiate isolando il pubblico previsto. Le stime forniscono informazioni statistiche sulla definizione di un segmento, come la dimensione dell'audience e l'intervallo di confidenza proiettati. Le anteprime forniscono elenchi impaginati di profili di qualifica per una definizione di segmento, consentendo di confrontare i risultati con quanto previsto.
Stimando e visualizzando in anteprima il pubblico, potete sottoporre a test e ottimizzare i predicati PQL fino a ottenere un risultato desiderato, da cui poi utilizzarli in una definizione aggiornata del segmento.
Sono necessari due passaggi per visualizzare l’anteprima o ottenere una stima del segmento:
  1. Visualizzare la stima o l’anteprima utilizzando l’ID del processo di anteprima

Modalità di generazione delle stime

Gli esempi di dati vengono utilizzati per valutare i segmenti e stimare il numero di profili di qualifica. I nuovi dati vengono caricati in memoria ogni mattina (tra le 12AM-2AM PT, che è 7-9AM UTC), e tutte le query di segmentazione sono stimate utilizzando i dati di esempio di quel giorno. Di conseguenza, eventuali nuovi campi aggiunti o dati aggiuntivi raccolti saranno riportati nelle stime il giorno successivo.
La dimensione del campione dipende dal numero complessivo di entità nell'archivio profili. Queste dimensioni di campione sono rappresentate nella seguente tabella:
Entità nell'archivio profili
Dimensione del campione
Meno di 1 milione
Set di dati completo
Da 1 a 20 milioni
1 milione
Oltre 20 milioni
5% del totale
Le stime generalmente vengono eseguite su un periodo di 10-15 secondi, a partire da una stima approssimativa e con un perfezionamento man mano che vengono letti più record.

Creare un processo di anteprima

Potete creare un nuovo processo di anteprima effettuando una richiesta POST all’ /preview endpoint.
Formato API
POST /preview

Richiesta
La richiesta seguente crea un nuovo processo di anteprima. Il corpo della richiesta contiene le informazioni sulla query relative al segmento.
curl -X POST \
  https://platform.adobe.io/data/core/ups/preview \
  -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 '{
        "predicateExpression": "xEvent.metrics.commerce.abandons.value > 0",
        "predicateType": "pql/text",
        "predicateModel": "_xdm.context.profile",
        "graphType": "simple",
        "mergeStrategy": "simple"
    }'

Proprietà
Descrizione
predicateExpression
Espressione PQL per eseguire una query sui dati.
predicateModel
Nome dello schema XDM su cui si basano i dati del profilo.
Risposta
Una risposta corretta restituisce i dettagli del processo di anteprima appena creato, incluso l’ID e lo stato di elaborazione corrente.
{
   "state": "RUNNING",
   "previewQueryId": "4a45e853-ac91-4bb7-a426-150937b6af5c",
   "previewQueryStatus": "RUNNING",
   "previewId": "MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg",
   "previewExecutionId": 42
}

Proprietà
Descrizione
state
Stato corrente del processo di anteprima. Sarà in stato "RUNNING" fino al completamento dell'elaborazione, al punto in cui diventa "RESULT_READY" o "FAILED".
previewId
L’ID del processo di anteprima, da utilizzare a scopo di ricerca quando si visualizza una stima o un’anteprima, come indicato nella sezione seguente.

Visualizzare una stima o un'anteprima

I processi di stima e anteprima vengono eseguiti in modo asincrono, in quanto le diverse query possono richiedere diversi tempi di completamento. Una volta avviata la query, potete utilizzare le chiamate API per recuperare (GET) lo stato corrente della stima o dell'anteprima mentre progredisce.
Utilizzando l’API Profilo cliente in tempo reale, potete cercare lo stato corrente di un processo di anteprima in base al relativo ID. Se lo stato è "RESULT_READY", è possibile visualizzare i risultati. A seconda se si desidera visualizzare una stima o un'anteprima, ciascuna ha un proprio endpoint nell'API. Di seguito sono riportati alcuni esempi per entrambi.

Visualizzare una stima

Formato API
GET /estimate/{PREVIEW_ID}

Proprietà
Descrizione
{PREVIEW_ID}
ID del processo di anteprima che si desidera visualizzare.
Richiesta
La richiesta seguente recupera una stima, utilizzando la stima previewId creata nel passaggio precedente.
curl -X GET \
  https://platform.adobe.io/data/core/ups/estimate/MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg \
  -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}'

Risposta
Una risposta corretta restituisce i dettagli della stima.
{
    "estimatedSize": 45,
    "state": "RESULT_READY",
    "profilesReadSoFar": 83834,
    "standardError": 0,
    "error": {
        "description": "",
        "traceback": ""
    },
    "profilesMatchedSoFar": 46,
    "totalRows": 82473,
    "confidenceInterval": "95%",
    "_links": {
        "preview": "https://platform.adobe.io/data/core/ups/preview?previewQueryId=f88bc056-ee48-40d5-9ddb-8865d7d6a0e0"
    }
}

Proprietà
Descrizione
state
Stato corrente del processo di anteprima. Sarà "IN ESECUZIONE" fino al completamento dell'elaborazione, al punto in cui diventa "RESULT_READY" o "FAILED".
_links.preview
Quando lo stato corrente del processo di anteprima è "RESULT_READY", questo attributo fornisce un URL per visualizzare la stima.

Visualizzare un’anteprima

Formato API
GET /preview/{PREVIEW_ID}

Proprietà
Descrizione
{PREVIEW_ID}
ID del processo di anteprima che si desidera visualizzare.
Richiesta
La richiesta seguente recupera un'anteprima, utilizzando la procedura previewId creata nel passaggio precedente.
curl -X GET \
  https://platform.adobe.io/data/core/ups/preview/MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg \
  -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}'

Risposta
Una risposta corretta restituisce i dettagli dell’anteprima.
{
   "results": [{
         "XID_ADOBE-MARKETING-CLOUD-ID-1": {
            "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_ADOBE-MARKETING-CLOUD-ID-1",
            "endCustomerIds": {
               "XID_COOKIE_ID_1": {
                  "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE_ID_1"
               },
               "XID_PROFILE_ID_1": {
                  "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_PROFILE_ID_1"
               }
            }
         }
      },
      {
         "XID_COOKIE-ID-2": {
            "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE-ID-2",
            "endCustomerIds": {
               "XID_COOKIE_ID_2-1": {
                  "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE_ID_2-1"

               },
               "XID_PROFILE_ID_2": {
                  "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_PROFILE_ID_2"
               }
            }
         },
         "XID_ADOBE-MARKETING-CLOUD-ID-3": {
            "_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_ADOBE-MARKETING-CLOUD-ID-1000"
         },
         "state": "RESULT_READY",
         "links": {
            "_self": "https://platform.adobe.io/data/core/ups/preview?expression=<expr-1>&limit=1000",
            "next": "",
            "prev": ""
         }
      }
   ],
   "page": {
      "offset": 0,
      "size": 3
   }
}

Passaggi successivi

Dopo aver sviluppato, testato e salvato la definizione del segmento, puoi creare un processo di segmento per creare un pubblico utilizzando l’API Profilo cliente in tempo reale. Per informazioni dettagliate su come valutare e accedere ai risultati del segmento, consulta l’esercitazione.