Show Menu
ARGOMENTI×

Endpoint processi di esportazione

I processi di esportazione sono processi asincroni utilizzati per mantenere i membri del segmento di pubblico nei set di dati. Potete utilizzare l' /export/jobs endpoint nell'API di segmentazione di Adobe Experience Platform, che consente di recuperare, creare e annullare i processi di esportazione a livello di programmazione.
Questa guida descrive l’utilizzo dei processi di esportazione nel Segmentation API. Per informazioni su come gestire i processi di esportazione per Real-time Customer Profile i dati, consultate la guida sui processi di esportazione nell'API di profilo

Introduzione

Gli endpoint utilizzati in questa guida fanno parte dell' Adobe Experience Platform Segmentation Service API. Prima di continuare, controllate la guida Getting started with Segmentation Service introduttiva per informazioni importanti che dovete conoscere per effettuare correttamente le chiamate all'API, comprese le intestazioni richieste e come leggere le chiamate API di esempio.

Recuperare un elenco di processi di esportazione

È possibile recuperare un elenco di tutti i processi di esportazione per l'organizzazione IMS effettuando una richiesta di GET all' /export/jobs endpoint.
Formato API
L' /export/jobs endpoint supporta diversi parametri di query per facilitare il filtraggio dei risultati. Anche se questi parametri sono opzionali, il loro utilizzo è fortemente consigliato per ridurre i costi di sovraccarico. Effettuando una chiamata a questo endpoint senza parametri, tutti i processi di esportazione disponibili per la vostra organizzazione verranno recuperati. È possibile includere più parametri, separati da e-mail ( & ).
GET /export/jobs
GET /export/jobs?limit={LIMIT}
GET /export/jobs?offset={OFFSET}
GET /export/jobs?status={STATUS}

Parametro
Descrizione
{LIMIT}
Specifica il numero di processi di esportazione restituiti.
{OFFSET}
Specifica l'offset delle pagine di risultati.
{STATUS}
Filtra i risultati in base allo stato. I valori supportati sono "NEW", "SUCCEEDED" e "FAILED".
Richiesta
Nella seguente richiesta vengono recuperati gli ultimi due processi di esportazione all’interno dell’organizzazione IMS.
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: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta
La risposta seguente restituisce lo stato HTTP 200 con un elenco di 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", "existing"]
                    }
                ]
            },
            "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"
    }
}

Proprietà
Descrizione
destination
Informazioni sulla destinazione dei dati esportati:
  • datasetId : ID del set di dati in cui sono stati esportati i dati.
  • segmentPerBatch : Un valore booleano che mostra se gli ID del segmento sono consolidati o meno. Il valore "false" indica che tutti gli ID del segmento vengono esportati in un unico 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
Elenco dei campi esportati, separati da virgole.
schema.name
Nome dello schema associato al dataset in cui devono essere esportati i dati.
filter.segments
I segmenti esportati. Sono inclusi i campi seguenti:
  • segmentId : L’ID del segmento in cui verranno esportati i profili.
  • segmentNs : Spazio dei nomi del segmento per il dato segmentID .
  • status : 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: "realizzate", "esistenti" e "uscite".
mergePolicy
Unisci informazioni sul criterio per i dati esportati.
metrics.totalTime
Campo che indica il tempo totale di esecuzione del processo di esportazione.
metrics.profileExportTime
Campo che indica il tempo necessario per l'esportazione dei profili.
page
Informazioni sull’impaginazione dei processi di esportazione richiesti.
link.next
Collegamento alla pagina successiva dei processi di esportazione.

Creare un nuovo processo di esportazione

Potete creare un nuovo processo di esportazione effettuando una richiesta di POST all’ /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: {IMS_ORG}' \
 -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
    }
}'

Proprietà
Descrizione
fields
Elenco dei campi esportati, separati da virgole. Se lasciato vuoto, verranno esportati tutti i campi.
mergePolicy
Specifica il criterio di unione da applicare ai dati esportati. Includete questo parametro quando vi sono più segmenti da esportare. Se non viene fornito, l'esportazione avrà lo stesso criterio di unione del segmento specificato.
filter
Un oggetto che specifica i segmenti che verranno inclusi nel processo di esportazione per ID, tempo di qualifica o tempo di caricamento, a seconda delle proprietà secondarie elencate di seguito. Se lasciato vuoto, tutti i dati verranno esportati.
filter.segments
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:
  • segmentId : (Obbligatorio se si utilizza segments ) ID segmento per i profili da esportare.
  • segmentNs (Facoltativo) Spazio dei nomi del segmento per il dato segmentID .
  • 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
Filtra in base al tempo di qualificazione del segmento. È possibile specificare l'ora di inizio e/o di fine.
filter.segmentQualificationTime.startTime
Ora di inizio della qualifica del 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
Ora 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
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 .
  • 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.
  • fromIngestTimestamp 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
Un valore booleano che indica se filtrare i profili vuoti. I profili possono contenere record di profilo, record ExperienceEvent o entrambi. I profili senza record di profilo e solo i record ExperienceEvent sono denominati "emptyProfiles". Per esportare tutti i profili nell’archivio profili, inclusi i "emptyProfiles", impostate il valore di emptyProfiles su true . Se emptyProfiles è impostato su false , vengono esportati solo i profili con record di profilo nello store. Per impostazione predefinita, se emptyProfiles l'attributo non è incluso, vengono esportati solo i profili che contengono record di profilo.
additionalFields.eventList
Controlla i campi evento delle serie temporali esportati per oggetti secondari o associati fornendo una o più delle seguenti impostazioni:
  • fields : Controllare i campi da esportare.
  • 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.
  • filter.fromIngestTimestamp : Filtra gli eventi della serie temporale 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.
  • filter.toIngestTimestamp : Filtra la marca temporale a quelle che sono state caricate prima della marca temporale specificata. Questo non è il momento dell’evento stesso ma il momento dell’inserimento degli eventi.
destination
(Obbligatorio) Informazioni sui dati esportati:
  • datasetId : (Obbligatorio) L'ID del set di dati in cui devono essere esportati i dati.
  • segmentPerBatch : (Facoltativo) Un valore booleano che, se non viene fornito, per impostazione predefinita è "false". Il valore "false" esporta tutti gli ID segmento in un unico ID batch. Il valore "true" esporta un ID segmento in un ID batch. Tenete presente che l’impostazione del valore su "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.
evaluationInfo.segmentation
(Facoltativo) Un valore booleano che, se non viene fornito, utilizza per impostazione predefinita false . Un valore di true indica che la segmentazione deve essere eseguita nel processo di esportazione.
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con i dettagli del processo di esportazione appena creato.
{
    "id": 100,
    "jobType": "BATCH",
    "destination": {
        "datasetId": "5b7c86968f7b6501e21ba9df",
        "segmentPerBatch": false,
        "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "fields": "identities.id,personalEmail.address",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "imsOrgId": "{IMS_ORG}",
    "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"
}

Proprietà
Descrizione
id
Valore di sola lettura generato dal sistema che identifica il processo di esportazione appena creato.
In alternativa, se destination.segmentPerBatch fosse stato impostato su true , l' destination oggetto sopra avrebbe una batches matrice, come illustrato 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

Potete recuperare informazioni dettagliate su un processo di esportazione specifico eseguendo una richiesta di GET all’ /export/jobs endpoint e fornendo l’ID del processo di esportazione che desiderate recuperare nel percorso della richiesta.
Formato API
GET /export/jobs/{EXPORT_JOB_ID}

Parametro
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/11037 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta
Una risposta corretta 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": "{IMS_ORG}",
    "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"
}

Proprietà
Descrizione
destination
Informazioni sulla destinazione dei dati esportati:
  • datasetId : ID del set di dati in cui sono stati esportati i dati.
  • segmentPerBatch : Un valore booleano che mostra se gli ID del segmento sono consolidati o meno. Un valore di false indica che tutti gli ID del segmento erano in un unico ID batch. Un valore true indica che un ID segmento viene esportato in un ID batch.
fields
Elenco dei campi esportati, separati da virgole.
schema.name
Nome dello schema associato al dataset in cui devono essere esportati i dati.
filter.segments
I segmenti esportati. Sono inclusi i campi seguenti:
  • segmentId : ID segmento per i profili da esportare.
  • segmentNs : Spazio dei nomi del segmento per il dato segmentID .
  • status : 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: "realizzate", "esistenti" e "uscite".
mergePolicy
Unisci informazioni sul criterio per i dati esportati.
metrics.totalTime
Campo che indica il tempo totale di esecuzione del processo di esportazione.
metrics.profileExportTime
Campo che indica il tempo necessario per l'esportazione dei profili.
totalExportedProfileCounter
Numero totale di profili esportati in tutti i batch.

Annullare o eliminare un processo di esportazione specifico

Potete richiedere di eliminare il processo di esportazione specificato eseguendo una richiesta di DELETE all’ /export/jobs endpoint e fornendo l’ID del processo di esportazione da eliminare nel percorso della richiesta.
Formato API
DELETE /export/jobs/{EXPORT_JOB_ID}

Parametro
Descrizione
{EXPORT_JOB_ID}
Indica id il processo di esportazione da 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: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta
Una risposta corretta 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 possibile comprendere meglio come funzionano i processi di esportazione.