Endpoint "segment export jobs"
I processi di esportazione sono processi asincroni utilizzati per rendere persistenti i membri del segmento di pubblico nei set di dati. È possibile utilizzare /export/jobs
nell’API di segmentazione di Adobe Experience Platform, che consente di recuperare, creare e annullare a livello di programmazione i processi di esportazione.
Introduzione
Gli endpoint utilizzati in questa guida fanno parte del Adobe Experience Platform Segmentation Service API. Prima di continuare, controlla guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all’API, incluse le intestazioni richieste e la lettura di esempi di chiamate API.
Recuperare un elenco di processi di esportazione retrieve-list
Per recuperare un elenco di tutti i processi di esportazione per la tua organizzazione, effettua una richiesta GET al /export/jobs
endpoint.
Formato API
Il /export/jobs
l’endpoint supporta diversi parametri di query per aiutare a filtrare i risultati. Anche se questi parametri sono facoltativi, si consiglia vivamente di utilizzarli per ridurre i costi generali. Effettuando una chiamata a questo endpoint senza parametri, verranno recuperati tutti i processi di esportazione disponibili per la tua organizzazione. È possibile includere più parametri, separati da e commerciali (&
).
GET /export/jobs
GET /export/jobs?limit={LIMIT}
GET /export/jobs?offset={OFFSET}
GET /export/jobs?status={STATUS}
{LIMIT}
{OFFSET}
{STATUS}
Richiesta
La richiesta seguente recupererà gli ultimi due processi di esportazione all’interno della tua organizzazione.
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs?limit=2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
La seguente risposta restituisce lo stato HTTP 200 con un elenco dei processi di esportazione completati correttamente, in base al parametro di query fornito nel percorso della richiesta.
{
"records": [
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52",
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"errors": [
{
"code": "0100000003",
"msg": "Error in Export Job",
"callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
}
],
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
},
{
"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": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "AAM",
"status": ["realized"]
}
]
},
"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",
"segmentPerBatch": false,
"batchId": "IWEQ6920712f9475762D"
},
"updateTime": 1538573922551,
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"creationTime": 1538573416687
}
],
"page":{
"sortField": "createdTime",
"sort": "desc",
"pageOffset": "1540974701302_96",
"pageSize": 2
},
"link":{
"next": "/export/jobs/?limit=2&offset=1538573416687_722"
}
}
destination
Informazioni sulla destinazione dei dati esportati:
datasetId
: ID del set di dati in cui sono stati esportati i dati.segmentPerBatch
: valore booleano che indica se gli ID segmento sono consolidati o meno. Il valore "false" indica che tutti gli ID segmento vengono esportati in un singolo ID batch. Il valore "true" indica che un ID segmento viene esportato in un ID batch. Nota: L'impostazione del valore su true può influire sulle prestazioni dell'esportazione batch.
fields
schema.name
filter.segments
I segmenti esportati. Sono inclusi i seguenti campi:
segmentId
: ID segmento in cui verranno esportati i profili.segmentNs
: spazio dei nomi del segmento per il datosegmentID
.status
: array di stringhe che fornisce un filtro di stato persegmentID
. Per impostazione predefinita,status
avrà il valore["realized"]
che rappresenta tutti i profili che rientrano nel segmento al momento corrente. I valori possibili includono:realized
eexited
. Un valore direalized
indica che il profilo è idoneo per il segmento. Un valore diexiting
significa che il profilo sta uscendo dal segmento.
mergePolicy
metrics.totalTime
metrics.profileExportTime
page
link.next
Crea un nuovo processo di esportazione create
Per creare un nuovo processo di esportazione, devi effettuare una richiesta POST al /export/jobs
endpoint.
Formato API
POST /export/jobs
Richiesta
La richiesta seguente crea un nuovo processo di esportazione, configurato dai parametri forniti nel payload.
curl -X POST https://platform.adobe.io/data/core/ups/export/jobs \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "string",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"toIngestTimestamp": "2020-01-01T00:00:00Z"
}
}
},
"destination":{
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false
},
"schema":{
"name": "_xdm.context.profile"
},
"evaluationInfo": {
"segmentation": true
}
}'
fields
mergePolicy
filter
filter.segments
Specifica i segmenti da esportare. Omettendo questo valore, tutti i dati di tutti i profili vengono esportati. Accetta un array di oggetti segmento, ciascuno contenente i seguenti campi:
segmentId
: (Obbligatorio se si utilizzasegments
) ID segmento per i profili da esportare.segmentNs
(Facoltativo) Spazio dei nomi del segmento per il datosegmentID
.status
(Facoltativo) Matrice di stringhe che fornisce un filtro di stato persegmentID
. Per impostazione predefinita,status
avrà il valore["realized"]
che rappresenta tutti i profili che rientrano nel segmento al momento corrente. I valori possibili includono:realized
eexited
. Un valore direalized
indica che il profilo è idoneo per il segmento. Un valore diexiting
significa che il profilo sta uscendo dal segmento.
filter.segmentQualificationTime
filter.segmentQualificationTime.startTime
filter.segmentQualificationTime.endTime
filter.fromIngestTimestamp
Limita i profili esportati a includere solo quelli che sono stati aggiornati dopo questa marca temporale. La marca temporale deve essere fornita in RFC 3339 formato.
fromIngestTimestamp
per profili, se fornito: include tutti i profili uniti in cui la marca temporale aggiornata unita è maggiore della marca temporale specificata. Supportigreater_than
operando.fromIngestTimestamp
per Eventi: tutti gli eventi acquisiti dopo questa marca temporale verranno esportati in modo corrispondente al risultato del profilo risultante. Non è l’ora dell’evento in sé, ma il tempo di acquisizione degli eventi.
filter.emptyProfiles
emptyProfiles
a true
. Se emptyProfiles
è impostato su false
, vengono esportati solo i profili con record di profilo nell’archivio. Per impostazione predefinita, se emptyProfiles
non è incluso, vengono esportati solo i profili contenenti record di profilo.additionalFields.eventList
Controlla i campi evento della serie temporale esportati per gli oggetti figlio o associati fornendo una o più delle seguenti impostazioni:
fields
: controlla i campi da esportare.filter
: specifica i criteri che limitano i risultati inclusi dagli oggetti associati. Prevede un valore minimo richiesto per l'esportazione, in genere una data.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.filter.toIngestTimestamp
: filtra la marca temporale in base a quelle che sono state acquisite prima della marca temporale fornita. Non è l’ora dell’evento in sé, ma il tempo di acquisizione degli eventi.
destination
(Obbligatorio) Informazioni sui dati esportati:
datasetId
: (Obbligatorio) ID del set di dati in cui devono essere esportati i dati.segmentPerBatch
: (Facoltativo) Valore booleano che, se non specificato, viene impostato automaticamente su "false". Il valore "false" esporta tutti gli ID segmento in un singolo ID batch. Il valore "true" esporta un ID segmento in un ID batch. L'impostazione del valore su "true" può influire sulle prestazioni di esportazione batch.
schema.name
evaluationInfo.segmentation
false
. Un valore di true
indica che è necessario eseguire la segmentazione sul processo di esportazione.Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli del nuovo processo di esportazione creato.
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{ORG_ID}",
"status": "NEW",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "_id, _experience",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z"
}
}
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
}
},
"computeGatewayJobId": {
"exportJob": ""
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
id
In alternativa, se destination.segmentPerBatch
è stato impostato su true
, il destination
l'oggetto di cui sopra avrebbe un batches
come mostrato di seguito:
"destination": {
"dataSetId": "{DATASET_ID}",
"segmentPerBatch": true,
"batches": [
{
"segmentId": "segment1",
"segmentNs": "ups",
"status": ["realized"],
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
{
"segmentId": "segment2",
"segmentNs": "AdCloud",
"status": "exited",
"batchId": "df4gssdfb93a09f7e37fa53ad52"
}
]
}
Recuperare un processo di esportazione specifico get
Per recuperare informazioni dettagliate su un processo di esportazione specifico, devi effettuare una richiesta GET al /export/jobs
e fornendo l’ID del processo di esportazione che desideri recuperare nel percorso della richiesta.
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/11037 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni dettagliate sul processo di esportazione specificato.
{
"id": 11037,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{ORG_ID}",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status":[
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
destination
Informazioni sulla destinazione dei dati esportati:
datasetId
: ID del set di dati in cui sono stati esportati i dati.segmentPerBatch
: valore booleano che indica se gli ID segmento sono consolidati o meno. Un valore difalse
significa che tutti gli ID del segmento erano in un singolo ID batch. Un valore ditrue
significa che un ID segmento viene esportato in un ID batch.
fields
schema.name
filter.segments
I segmenti esportati. Sono inclusi i seguenti campi:
segmentId
: ID segmento per i profili da esportare.segmentNs
: spazio dei nomi del segmento per il datosegmentID
.status
: array di stringhe che fornisce un filtro di stato persegmentID
. Per impostazione predefinita,status
avrà il valore["realized"]
che rappresenta tutti i profili che rientrano nel segmento al momento corrente. I valori possibili includono:realized
eexited
. Un valore direalized
indica che il profilo è idoneo per il segmento. Un valore diexiting
significa che il profilo sta uscendo dal segmento.
mergePolicy
metrics.totalTime
metrics.profileExportTime
totalExportedProfileCounter
Annullare o eliminare un processo di esportazione specifico delete
Per richiedere l’eliminazione del processo di esportazione specificato, effettua una richiesta DELETE al /export/jobs
e fornendo l’ID del processo di esportazione da eliminare nel percorso della richiesta.
Formato API
DELETE /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
del processo di esportazione che desideri eliminare.Richiesta
curl -X DELETE https://platform.adobe.io/data/core/ups/export/jobs/{EXPORT_JOB_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 204 con il seguente messaggio:
{
"status": true,
"message": "Export job has been marked for cancelling"
}
Passaggi successivi
Dopo aver letto questa guida ora hai una migliore comprensione di come funzionano i processi di esportazione.