Show Menu
ARGOMENTI×

Valutazione e accesso ai risultati dei segmenti

Questo documento fornisce un'esercitazione per valutare i segmenti e accedere ai risultati dei segmenti utilizzando l'API segmentation.yaml Segmentazione.

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 cliente unificato 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.
  • Sandbox : Experience Platform fornisce sandbox virtuali che dividono una singola istanza della piattaforma 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 API della piattaforma. 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. Le richieste alle API della piattaforma richiedono un'intestazione che specifica il nome della sandbox in cui si svolgerà l'operazione:
  • x-sandbox-name: {SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Piattaforma, consultate la documentazione sulla panoramica della sandbox.
Tutte le richieste 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 #on-demand-evaluation 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 l’esercitazione Crea un segmento utilizzando l’esercitazione API Profilo cliente in tempo reale o hai creato una definizione di segmento utilizzando 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.
La valutazione pianificata può essere abilitata per le sandbox con un massimo di cinque (5) criteri di unione per il profilo individuale XDM. Se l'organizzazione dispone di più di cinque criteri di unione per il profilo individuale XDM all'interno di un unico ambiente sandbox, non sarà possibile utilizzare la valutazione pianificata.

Creare una pianificazione

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

Richiesta
La richiesta seguente crea una nuova pianificazione in base alle specifiche fornite nel payload.
curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules \
  -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": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Proprietà
Descrizione
name
(Obbligatorio) Nome della pianificazione. Deve essere una stringa.
type
(Obbligatorio) Il tipo di processo in formato stringa. I tipi supportati sono batch_segmentation e export .
properties
(Obbligatorio) Un oggetto contenente proprietà aggiuntive correlate alla pianificazione.
properties.segments
(Obbligatorio se type è uguale a batch_segmentation ) L'utilizzo di ["*"] assicura che tutti i segmenti siano inclusi.
schedule
(Obbligatorio) Una stringa contenente la pianificazione del processo. È possibile pianificare l’esecuzione dei processi solo una volta al giorno, pertanto non è possibile pianificare l’esecuzione di un processo più volte durante un periodo di 24 ore. L’esempio mostrato ( 0 0 1 * * ? ) indica che il processo viene attivato ogni giorno alle 1:00:00 UTC. Per ulteriori informazioni, consulta la documentazione relativa al formato delle espressioni cron.
state
(Facoltativo) Stringa contenente lo stato di pianificazione. Valori disponibili: active e inactive . Il valore predefinito è inactive . Un'organizzazione IMS può creare una sola pianificazione. I passaggi per aggiornare la pianificazione sono disponibili più avanti in questa esercitazione.
Risposta
Una risposta corretta restituisce i dettagli della nuova pianificazione creata.
{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

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 ) eseguendo una richiesta PATCH all' /config/schedules endpoint e includendo l'ID della pianificazione nel percorso.
Formato API
POST /config/schedules/{SCHEDULE_ID}

Richiesta
La richiesta seguente utilizza la formattazione JSON Patch per aggiornare la state pianificazione a active .
curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -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 '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

Risposta
Un aggiornamento riuscito restituisce un corpo di risposta vuoto e lo stato HTTP 204 (nessun contenuto).
La stessa operazione può essere utilizzata per disattivare una pianificazione sostituendo il "valore" nella richiesta precedente con "inattivo".

Aggiornamento dell'ora di pianificazione

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

Richiesta
Nella richiesta seguente viene utilizzata la formattazione della patch JSON per aggiornare l'espressione crontrigger.html cron per la pianificazione. In questo esempio, la pianificazione ora viene attivata alle 10:15:00 UTC.
curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -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 '[
        {
          "op": "add",
          "path": "/schedule",
          "value": "0 15 10 * * ?"
        }
      ]'

Risposta
Un aggiornamento riuscito restituisce un corpo di risposta vuoto e lo stato HTTP 204 (nessun contenuto).

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 in che modo il profilo cliente in tempo reale 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 POST all’ /segment/jobs endpoint nell’API del profilo cliente in tempo reale.
Formato API
POST /segment/jobs

Richiesta
La richiesta seguente crea un nuovo processo segmento in base alle definizioni dei due segmenti fornite nel payload.
curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/jobs \
  -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 '[
        {
          "segmentId" : "42f49f2d-edb0-474f-b29d-2799d89cd5a6"
        },
        {
          "segmentId" : "54a20f19-9a0w-293a-9b82-409b1p3v0192"
        }
    ]'

Proprietà
Descrizione
segmentId
Identificatore di una definizione di segmento da cui generare l'audience. È necessario fornire almeno un ID segmento nell'array payload.
Risposta
Una risposta di successo restituisce i dettagli del processo del segmento appena creato, incluso il relativo valore di sola lettura generato dal sistema id che è univoco per questo processo del segmento.
{
    "profileInstanceId": "ups",
    "computeJobId": 1,
    "id": "b0f99dde-6d3b-4d92-aa92-28072ded71a0",
    "status": "PROCESSING",
    "segments": [
        {
            "segmentId": "42f49f2d-edb0-474f-b29d-2799d89cd5a6",
            "segment": {
                "id": "42f49f2d-edb0-474f-b29d-2799d89cd5a6",
                "version": 1,
                "expression": {
                    "type": "PQL",
                    "format": "pql/text",
                    "value": "homeAddress.country = \"US\""
                },
                "mergePolicy": {
                    "id": "mpid1",
                    "version": 1
                }
            }
        },
        {
            "segmentId": "54a20f19-9a0w-293a-9b82-409b1p3v0192",
            "segment": {
                "id": "54a20f19-9a0w-293a-9b82-409b1p3v0192",
                "version": 1,
                "expression": {
                    "type": "PQL",
                    "format": "pql/text",
                    "value": "homeAddress.country = \"US\""
                },
                "mergePolicy": {
                    "id": "mpid1",
                    "version": 1
                }
            }
        }
    ],
    "updateTime": 1533581808162,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1533581808162,
    "_links": {
        "cancel": {
            "href": "/segment/jobs/b0f99dde-6d3b-4d92-aa92-28072ded71a0",
            "method": "DELETE"
        },
        "checkStatus": {
            "href": "/segment/jobs/b0f99dde-6d3b-4d92-aa92-28072ded71a0",
            "method": "GET"
        }
    }
}

Proprietà
Descrizione
id
Identificatore del nuovo processo del segmento, utilizzato a scopo di ricerca.
status
Lo stato corrente del processo del segmento. Sarà "PROCESSING" fino al completamento dell'elaborazione, al punto in cui diventa "SUCCEEDED" o "FAILED".

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.
Formato API
GET /segment/jobs/{SEGMENT_JOB_ID}

Proprietà
Descrizione
{SEGMENT_JOB_ID}
Indica id il processo del segmento a cui si desidera accedere.
Richiesta
curl -X GET \
  https://platform.adobe.io/data/core/ups/segment/jobs/80388706-29fa-40d3-81cf-a297d0224ad9 \
  -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 del processo di segmentazione e fornisce informazioni diverse a seconda dello stato corrente del processo. Puoi ripetere la richiesta di ricerca fino a status raggiungere "SUCCEEDED", al momento in cui puoi esportare il segmento in un dataset.
{
    "profileInstanceId": "ups",
    "errors": [],
    "computeJobId": 13377,
    "modelName": "_xdm.context.profile",
    "id": "80388706-29fa-40d3-81cf-a297d0224ad9",
    "status": "SUCCEEDED",
    "segments": [
        {
            "segmentId": "b560a09a-de85-4a1c-8477-2f3da1d9e86b",
            "segment": {
                "id": "b560a09a-de85-4a1c-8477-2f3da1d9e86b",
                "version": 1,
                "expression": {
                    "type": "PQL",
                    "format": "pql/json",
                    "value": "homeAddress.country = \"US\""
                },
                "mergePolicy": {
                    "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
                    "version": 1
                }
            }
        }
    ],
    "requestId": "prgu92v4VNvsGuuXticcsqX96UXGjXtS",
    "computeGatewayJobId": "a7c33b77-3aeb-497f-bc88-807915c57b5f",
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1547063631503,
            "endTimeInMs": 1547063731181,
            "totalTimeInMs": 99678
        },
        "profileSegmentationTime": {
            "startTimeInMs": 1547063669001,
            "endTimeInMs": 1547063720887,
            "totalTimeInMs": 51886
        },
        "segmentedProfileCounter": {
            "ca763983-5572-4ea4-809c-b7dff7e0d79b": 4195,
            "251e3a1f-645c-4444-836b-18e6b668bdf8": 0,
            "3da8bad9-29fb-40e0-b39e-f80322e964de": 0,
            "30230300-ccf1-48ad-8012-c5563a007069": 0
        },
        "segmentedProfileByNamespaceCounter": {
            "ca763983-5572-4ea4-809c-b7dff7e0d79b": {
                "email": 4195
            },
            "251e3a1f-645c-4444-836b-18e6b668bdf8": {},
            "3da8bad9-29fb-40e0-b39e-f80322e964de": {},
            "30230300-ccf1-48ad-8012-c5563a007069": {}
        }     
    },
    "updateTime": 1547063731181,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1547063631503,
    "_links": {
        "cancel": {
            "href": "/segment/jobs/80388706-29fa-40d3-81cf-a297d0224ad9",
            "method": "DELETE"
        },
        "checkStatus": {
            "href": "/segment/jobs/80388706-29fa-40d3-81cf-a297d0224ad9",
            "method": "GET"
        }
    }
}

Proprietà
Descrizione
segmentedProfileCounter
Numero totale di profili uniti idonei per il segmento.
segmentedProfileByNamespaceCounter
Una suddivisione dei profili idonei per il segmento in base al codice dello spazio dei nomi dell'identità. Nella panoramica Panoramica dello spazio nomi identità dello spazio nomi identità è possibile trovare un elenco di codici dello spazio nomi identità.

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 già valutati che vengono trasferiti in Piattaforma, 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 conosci il profilo specifico a cui vuoi accedere, puoi farlo utilizzando l'API Profilo cliente in tempo reale. 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 set di dati deve essere basato sullo schema unionale profilo singolo XDM ( 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 guida per 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 dataset che faccia riferimento allo schema dell'unione dei profili XDM utilizzando l'API Catalog.
  • Utilizzo dell’interfaccia utente: Per utilizzare l'interfaccia utente di Adobe Experience Platform per creare un dataset che faccia riferimento allo schema dell'unione, segui i passaggi dell'esercitazione Guida utente di Segment Builder dell'interfaccia utente, quindi torna 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 alla fase di generazione dei 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 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 POST all' /export/jobs endpoint nell'API del profilo cliente in tempo reale e fornendo l'ID del set di dati e le informazioni del segmento per i segmenti che desiderate esportare.
Formato API
POST /export/jobs

Richiesta
La richiesta seguente crea un nuovo processo di esportazione, fornendo i parametri di configurazione nel payload.
curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs \
  -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 '{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "filter": {
      "segments": [
        {
          "segmentId": "4edc8488-2c35-4f6d-b4c6-9075c68d2df4",
          "segmentNs": "AAM",
          "status": ["realized"]
        },
        {
          "segmentId": "1rfe8422-334d-12f4-3sd4-12cf6g990g51",
          "segmentNs": "UPS",
          "status": ["exited"]
        }
      ],
      "segmentQualificationTime": {
            "startTime": "2019-09-01T00:00:00Z",
            "endTime": "2019-09-02T00:00:00Z"
        },
      "fromIngestTimestamp": "2018-10-25T13:22:04-07:00",
      "emptyProfiles": false
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": true
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }'

Proprietà
Descrizione
fields
(Facoltativo) Limita i campi di dati da includere nell’esportazione solo a quelli forniti in questo parametro. Lo stesso parametro è disponibile anche quando si crea un segmento, pertanto i campi nel segmento potrebbero essere già stati filtrati. Se si omette questo valore, tutti i campi verranno inclusi nei dati esportati
mergePolicy
(Facoltativo) Specifica il criterio di unione da applicare ai dati esportati. Includete questo parametro quando vi sono più segmenti da esportare. Se si omette questo valore, il servizio di esportazione utilizzerà il criterio di unione fornito dal segmento.
mergePolicy.id
ID del criterio di unione
mergePolicy.version
Versione specifica del criterio di unione da utilizzare. Se si omette questo valore, per impostazione predefinita verrà utilizzata la versione più recente.
filter
(Facoltativo) Specifica uno o più dei seguenti filtri da applicare al segmento prima dell'esportazione:
filter.segments
(Facoltativo) Specifica i segmenti da esportare. Se si omette questo valore, verranno esportati tutti i dati di tutti i profili. Accetta un array di oggetti segmento, ciascuno dei quali contiene i campi seguenti:
filter.segments.segmentId
(Obbligatorio se si utilizza segments ) ID segmento per i profili da esportare.
filter.segments.segmentNs
(Facoltativo) Spazio dei nomi del segmento per il dato segmentID .
filter.segments.status
(Facoltativo) Un array di stringhe che fornisce un filtro di stato per l'oggetto segmentID . Per impostazione predefinita, status il valore ["realized", "existing"] rappresenta tutti i profili che rientrano nel segmento al momento corrente. I valori possibili sono: "realized" , "existing" , e "exited" .
filter.segmentQualificationTime
(Facoltativo) Filtra in base al tempo di qualificazione del segmento. È possibile specificare l'ora di inizio e/o di fine.
filter.segmentQualificationTime.startTime
(Facoltativo) Ora di inizio qualifica segmento per un ID segmento per un dato stato. Non viene fornito, non verrà applicato alcun filtro all'ora di inizio per la qualifica ID segmento. La marca temporale deve essere fornita in formato RFC 3339 .
filter.segmentQualificationTime.endTime
(Facoltativo) Tempo di fine qualifica segmento per un ID segmento per un dato stato. Non viene fornito, non verrà applicato alcun filtro all'ora di fine per la qualifica di ID segmento. La marca temporale deve essere fornita in formato RFC 3339 .
filter.fromIngestTimestamp
(Facoltativo) Limita i profili esportati a includere solo quelli che sono stati aggiornati dopo questa marca temporale. La marca temporale deve essere fornita in formato RFC 3339 .
filter.fromIngestTimestamp per i profili , se forniti
Include tutti i profili uniti in cui la marca temporale aggiornata unita è maggiore della marca temporale specificata. Supporta greater_than l'operando.
filter.fromTimestamp per gli eventi
Tutti gli eventi acquisiti dopo questa marca temporale verranno esportati in base al risultato del profilo risultante. Questo non è il momento dell’evento stesso ma il momento dell’inserimento degli eventi.
filter.emptyProfiles
(Facoltativo) Valore Boolean. I profili possono contenere record Profilo, record ExperienceEvent o entrambi. I profili senza record Profilo e solo i record ExperienceEvent sono denominati "emptyProfiles". Per esportare tutti i profili nell’archivio profili, inclusi i "emptyProfiles", imposta il valore di emptyProfiles su true . Se emptyProfiles è impostato su false , vengono esportati solo i profili con record Profilo nello store. Per impostazione predefinita, se emptyProfiles l’attributo non è incluso, vengono esportati solo i profili contenenti i record Profilo.
additionalFields.eventList
(Facoltativo) Controlla i campi evento delle serie temporali esportati per oggetti secondari o associati fornendo una o più delle seguenti impostazioni:
additionalFields.eventList.fields
Controllare i campi da esportare.
additionalFields.eventList.filter
Specifica i criteri che limitano i risultati inclusi dagli oggetti associati. Si attende un valore minimo richiesto per l'esportazione, in genere una data.
additionalFields.eventList.filter.fromIngestTimestamp
Filtra gli eventi delle serie temporali a quelli che sono stati acquisiti dopo la marca temporale fornita. Questo non è il momento dell’evento stesso ma il momento dell’inserimento degli eventi.
destination
(Obbligatorio) Informazioni sulla destinazione per i dati esportati
destination.datasetId
(Obbligatorio) L'ID del set di dati in cui devono essere esportati i dati.
destination.segmentPerBatch
(Facoltativo) Un valore booleano che, se non viene fornito, utilizza per impostazione predefinita false . Un valore di false esporta tutti gli ID segmento in un unico ID batch. Un valore di true esportazione consente di esportare un ID segmento in un ID batch. Tenete presente che l’impostazione del valore da assegnare true può influire sulle prestazioni di esportazione batch.
schema.name
(Obbligatorio) Il nome dello schema associato al dataset in cui devono essere esportati i dati.
Risposta
Una risposta corretta restituisce un set di dati compilato con profili idonei per l’ultima esecuzione completata del processo del segmento. Sono stati rimossi tutti i profili che possono essere esistiti in precedenza nel set di dati ma che non erano idonei per il segmento durante l’ultima esecuzione completata del processo del segmento.
{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "filter": {
      "segments": [
        {
          "segmentId": "4edc8488-2c35-4f6d-b4c6-9075c68d2df4",
          "segmentNs": "AAM",
          "status": ["realized"]
        },
        {
          "segmentId": "1rfe8422-334d-12f4-3sd4-12cf6g990g51",
          "segmentNs": "UPS",
          "status": ["exited"]
        }
      ]
    },
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "NEW",
    "requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
    "computeGatewayJobId": {},
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1559674261657
        }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": true,
      "batches" : [
        {
          "segmentId": "4edc8488-2c35-4f6d-b4c6-9075c68d2df4",
          "segmentNs": "AAM",
          "status": ["realized"],
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
        },
        {
          "segmentId": "1rfe8422-334d-12f4-3sd4-12cf6g990g51",
          "segmentNs": "UPS",
          "status": ["exited"],
          "batchId": "df4gssdfb93a09f7e37fa53ad52"
        }
      ]
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}

Se non destination.segmentPerBatch fosse stato incluso nella richiesta (se non presente, è false il valore predefinito) o se il valore fosse stato impostato su false , l' destination oggetto nella risposta precedente non avrebbe una batches matrice e ne avrebbe invece inclusa solo una batchId , come mostrato di seguito. Tale batch singolo includerebbe tutti gli ID del segmento, mentre la risposta precedente mostra un ID segmento singolo per ID batch.
  "destination": {
    "datasetId": "5cf6bcf79ecc7c14530fe436",
    "segmentPerBatch": false,
    "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
  }

Elenca tutti i processi di esportazione

Potete restituire un elenco di tutti i processi di esportazione per una particolare organizzazione IMS eseguendo una richiesta GET all' export/jobs endpoint. La richiesta supporta anche i parametri di query limit e offset , come mostrato di seguito.
Formato API
GET /export/jobs
GET /export/jobs?limit=4
GET /export/jobs?offset=2

Proprietà
Descrizione
limit
Specificare il numero di record da restituire.
offset
Consente di scostare la pagina dei risultati da restituire in base al numero fornito.
Richiesta
curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/ \
  -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
La risposta include un records oggetto contenente i processi di esportazione creati dall'organizzazione IMS.
{
  "records": [
    {
      "profileInstanceId": "ups",
      "jobType": "BATCH",
      "filter": {
          "segments": [
              {
                  "segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff"
              }
          ]
      },
      "id": 726,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "timestampOrdered-none-mp",
          "version": 1
      },
      "status": "SUCCEEDED",
      "requestId": "d995479c-8a08-4240-903b-af469c67be1f",
      "computeGatewayJobId": {
          "exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
          "pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538615973895,
              "endTimeInMs": 1538616233239,
              "totalTimeInMs": 259344
          },
          "profileExportTime": {
              "startTimeInMs": 1538616067445,
              "endTimeInMs": 1538616139576,
              "totalTimeInMs": 72131
          },
          "aCPDatasetWriteTime": {
              "startTimeInMs": 1538616195172,
              "endTimeInMs": 1538616195715,
              "totalTimeInMs": 543
          }
      },
      "destination": {
          "datasetId": "5b7c86968f7b6501e21ba9df",
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
      },
      "updateTime": 1538616233239,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538615973895
    },
    {
      "profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
      "errors": [
        {
          "code": "0090000009",
          "msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
          "callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger" 
        },
        {
          "code": "unknown",
          "msg": "Job aborted.",
          "callStack": "org.apache.spark.SparkException: Job aborted."
        }
      ],
      "jobType": "BATCH",
      "filter": {
        "segments": [
            {
                "segmentId": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
            }
        ]
      },
      "id": 722,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
          "version": 1
      },
      "status": "FAILED",
      "requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
      "computeGatewayJobId": {
          "exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538573416687,
              "endTimeInMs": 1538573922551,
              "totalTimeInMs": 505864
          },
          "profileExportTime": {
              "startTimeInMs": 1538573872211,
              "endTimeInMs": 1538573918809,
              "totalTimeInMs": 46598
          }
      },
      "destination": {
          "datasetId": "5bb4c46757920712f924a3eb",
          "batchId": ""
      },
      "updateTime": 1538573922551,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

Monitorare l'avanzamento dell'esportazione

Come processo di esportazione, potete controllarne lo stato eseguendo una richiesta 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".
Formato API
GET /export/jobs/{EXPORT_JOB_ID}

Proprietà
Descrizione
{EXPORT_JOB_ID}
Indica id il processo di esportazione a cui si desidera accedere.
Richiesta
curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/24115 \
  -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
{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "filter": {
      "segments": [
        {
          "segmentId": "4edc8488-2c35-4f6d-b4c6-9075c68d2df4",
          "segmentNs": "AAM",
          "status": ["realized"]
        },
        {
          "segmentId": "1rfe8422-334d-12f4-3sd4-12cf6g990g51",
          "segmentNs": "UPS",
          "status": ["exited"]
        }
      ]
    },
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "SUCCEEDED",
    "requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
    "computeGatewayJobId": {
      "exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
      "pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
    },
    "metrics": {
      "totalTime": {
        "startTimeInMs": 1547053539564,
        "endTimeInMs": 1547054743929,
        "totalTimeInMs": 1204365
      },
      "profileExportTime": {
        "startTimeInMs": 1547053667591,
        "endTimeInMs": 1547053778195,
        "totalTimeInMs": 110604
      },
      "aCPDatasetWriteTime": {
        "startTimeInMs": 1547054660416,
        "endTimeInMs": 1547054698918,
        "totalTimeInMs": 38502
      }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": true,
      "batches" : [
        {
          "segmentId": "4edc8488-2c35-4f6d-b4c6-9075c68d2df4",
          "segmentNs": "AAM",
          "status": ["realized"],
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
        },
        {
          "segmentId": "1rfe8422-334d-12f4-3sd4-12cf6g990g51",
          "segmentNs": "UPS",
          "status": ["exited"],
          "batchId": "df4gssdfb93a09f7e37fa53ad52"
        }
      ]
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}

Proprietà
Descrizione
batchId
Identificatore dei batch creati da un'esportazione riuscita, da utilizzare a scopo di ricerca durante la lettura dei dati dell'audience.

Passaggi successivi

Una volta completata l'esportazione, i dati sono disponibili all'interno del Data Lake in Experience Platform. Potete quindi utilizzare l'API di accesso ai dati per accedere ai dati utilizzando l' batchId API 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 di accesso ai dati per accedere e scaricare file batch, segui l'esercitazione sull'accesso ai dati.
Puoi anche accedere ai dati del segmento esportati correttamente tramite Adobe Experience Platform Query Service. Utilizzando l'interfaccia utente o l'API RESTful, Query Service consente di scrivere, convalidare ed eseguire query sui dati all'interno del Data Lake.
Per ulteriori informazioni su come eseguire query sui dati del pubblico, consulta la documentazione del servizio Query.