Endpoint "profile export jobs"
Real-Time Customer Profile consente di creare una singola vista dei singoli clienti riunendo dati provenienti da più origini, inclusi sia i dati degli attributi che i dati comportamentali. I dati profilo possono quindi essere esportati in un set di dati per ulteriore elaborazione. Ad esempio: Profile i dati possono essere esportati per l’attivazione mediante la creazione di tipi di pubblico, mentre gli attributi di profilo possono essere esportati a scopo di reporting.
Questo documento fornisce istruzioni dettagliate per la creazione e la gestione dei processi di esportazione mediante API profilo.
Oltre a creare un processo di esportazione, puoi anche accedere a Profile dati utilizzando /entities
endpoint, noto anche come "Profile Access". Consulta la guida dell’endpoint "entities" per ulteriori informazioni. Per i passaggi su come accedere a Profile dati tramite l’interfaccia utente, consulta guida utente.
Introduzione
Gli endpoint API utilizzati in questa guida fanno parte del Real-Time Customer Profile API. Prima di continuare, controlla guida introduttiva per collegamenti alla documentazione correlata, una guida per la lettura delle chiamate API di esempio di questo documento e informazioni importanti sulle intestazioni richieste necessarie per effettuare correttamente le chiamate a Experience Platform API.
Creare un processo di esportazione
Esportazione Profile I dati richiedono innanzitutto la creazione di un set di dati in cui esportare i dati, quindi l’avvio di un nuovo processo di esportazione. Entrambi i passaggi possono essere eseguiti utilizzando le API Experienci Platform, con la prima che utilizza l’API Catalog Service e la seconda che utilizza l’API Profilo cliente in tempo reale. Le istruzioni dettagliate per il completamento di ciascun passaggio sono descritte nelle sezioni che seguono.
Creare un set di dati di destinazione
Durante l’esportazione Profile dati, è prima necessario creare 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 (di seguito). Per esportare i dati del profilo, il set di dati deve essere basato su XDM Individual Profile Schema di unione (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, è il XDM Individual Profile classe. Per ulteriori informazioni sugli schemi di visualizzazione unione, consulta la sezione union nella guida di base della composizione dello schema.
I passaggi seguenti in questa esercitazione descrivono come creare un set di dati che faccia riferimento a XDM Individual Profile Unione dello schema tramite Catalog API. È inoltre possibile utilizzare il Platform per creare un set di dati che faccia riferimento allo schema di unione. I passaggi per utilizzare l’interfaccia utente sono descritti in questo tutorial sull’interfaccia utente per esportare i tipi di pubblico ma sono applicabili anche qui. Una volta completato, puoi tornare a questa esercitazione per procedere con i passaggi per avvio di un nuovo processo di esportazione.
Se disponi già di un set di dati compatibile e conosci il relativo ID, puoi procedere direttamente al passaggio per avvio di un nuovo processo di esportazione.
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": "Profile Data Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
name
schemaRef.id
Risposta
In caso di esito positivo, la risposta restituisce un array contenente l’ID univoco di sola lettura generato dal sistema del set di dati appena creato. Per esportare correttamente i dati profilo è necessario un ID set di dati configurato correttamente.
[
"@/datasets/5b020a27e7040801dedba61b"
]
Avvia processo di esportazione initiate
Una volta che hai un set di dati persistente nell’unione, puoi creare un processo di esportazione per rendere persistenti i dati del profilo nel set di dati effettuando una richiesta POST al /export/jobs
nell’API del profilo cliente in tempo reale e fornendo i dettagli dei dati che desideri esportare nel corpo della richiesta.
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
}
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}'
fields
mergePolicy
mergePolicy.id
mergePolicy.version
additionalFields.eventList
(Facoltativo) Controlla i campi evento della serie temporale esportati per gli oggetti figlio o associati fornendo una o più delle seguenti impostazioni:
eventList.fields
: controlla i campi da esportare.eventList.filter
: specifica i criteri che limitano i risultati inclusi dagli oggetti associati. Prevede un valore minimo richiesto per l'esportazione, in genere una data.eventList.filter.fromIngestTimestamp
: filtra gli eventi della serie temporale con quelli che sono stati acquisiti dopo la marca temporale fornita. Non è l’ora dell’evento in sé, ma il tempo di acquisizione degli eventi.
destination
(Obbligatorio) Informazioni sulla destinazione dei dati esportati:
destination.datasetId
: (Obbligatorio) ID del set di dati in cui devono essere esportati i dati.destination.segmentPerBatch
: (Facoltativo) Un valore booleano che, se non specificato, utilizza per impostazione predefinitafalse
. Un valore difalse
esporta tutti gli ID di definizione segmento in un singolo ID batch. Un valore ditrue
esporta un ID di definizione segmento in un ID batch. Tieni presente che impostando il valore sutrue
può influire sulle prestazioni di esportazione in batch.
schema.name
Risposta
In caso di esito positivo, la risposta restituisce un set di dati popolato con dati di profilo come specificato nella richiesta.
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"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": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
Elenca tutti i processi di esportazione
È possibile restituire un elenco di tutti i processi di esportazione per una particolare organizzazione eseguendo una richiesta di GET al export/jobs
endpoint. La richiesta supporta anche i parametri di query limit
e offset
, come illustrato di seguito.
Formato API
GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
start
start=4
limit
limit=10
page
page=2
sort
asc
) o decrescente ( desc
). Il parametro sort non funziona quando si restituiscono più pagine di risultati. Esempio: sort=updateTime:asc
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: {ORG_ID}'
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
La risposta include una records
oggetto contenente i processi di esportazione creati dall’organizzazione.
{
"records": [
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"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": "{ORG_ID}",
"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": "{ORG_ID}",
"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
Per visualizzare i dettagli di un processo di esportazione specifico o monitorarne lo stato durante l'elaborazione, è possibile effettuare una richiesta di GET al /export/jobs
e includere id
del processo di esportazione nel percorso. Il processo di esportazione viene completato una volta che status
restituisce il valore "SUCCESSEDED".
Formato API
GET /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
del processo di esportazione a cui desideri 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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"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": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
batchId
Annullare un processo di esportazione
Experienci Platform consente di annullare un processo di esportazione esistente. Ciò può essere utile per diversi motivi, tra cui se il processo di esportazione non è stato completato o si è bloccato nella fase di elaborazione. Per annullare un processo di esportazione, è possibile eseguire una richiesta DELETE al /export/jobs
e includere id
del processo di esportazione che desideri annullare nel percorso della richiesta.
Formato API
DELETE /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
del processo di esportazione a cui desideri accedere.Richiesta
curl -X POST \
https://platform.adobe.io/data/core/ups/export/jobs/726 \
-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}'
Risposta
In caso di esito positivo, la richiesta di eliminazione restituisce lo stato HTTP 204 (nessun contenuto) e un corpo di risposta vuoto, a indicare che l’operazione di annullamento è riuscita.
Passaggi successivi
Una volta completata correttamente l’esportazione, i dati sono disponibili all’interno del Data Lake in Experienci Platform. È quindi possibile utilizzare API di accesso ai dati per accedere ai dati utilizzando batchId
associato all’esportazione. A seconda delle dimensioni dell’esportazione, i dati possono essere in blocchi e il batch può essere costituito da diversi file.
Per istruzioni dettagliate sull’utilizzo dell’API di accesso ai dati per accedere e scaricare file batch, segui la Tutorial sull’accesso ai dati.
Puoi anche accedere ai dati Real-Time Customer Profile 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 sezione Documentazione di Query Service.
Appendice
La sezione seguente contiene informazioni aggiuntive relative ai processi di esportazione nell’API di profilo.
Ulteriori esempi di payload di esportazione
L’esempio di chiamata API mostrato nella sezione su avvio di un processo di esportazione crea un processo che contiene sia dati di profilo (record) che dati di evento (serie temporali). Questa sezione fornisce ulteriori esempi di payload di richiesta per limitare l’esportazione in modo che contenga un tipo di dati o l’altro.
Il seguente payload crea un processo di esportazione che contiene solo dati di profilo (nessun evento):
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
Per creare un processo di esportazione che contenga solo dati evento (senza attributi di profilo), il payload potrebbe essere simile al seguente:
{
"fields": "identityMap",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
Esportazione di tipi di pubblico
Puoi anche utilizzare l’endpoint dei processi di esportazione per esportare i tipi di pubblico anziché Profile dati. Consulta la guida su processi di esportazione nell’API di segmentazione per ulteriori informazioni.