DocumentazioneExperience PlatformGuida al servizio di segmentazione

Endpoint "segment export jobs"

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Argomenti:

Creato per:

  • Sviluppatore

I processi di esportazione sono processi asincroni utilizzati per rendere persistenti i membri del segmento di pubblico nei set di dati. È possibile utilizzare l'endpoint /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.

NOTE
Questa guida descrive l'utilizzo dei processi di esportazione in Segmentation API. Per informazioni su come gestire i processi di esportazione per i dati Real-Time Customer Profile, vedere la guida relativa ai processi di esportazione nell'API di profilo

Introduzione

Gli endpoint utilizzati in questa guida fanno parte dell'API Adobe Experience Platform Segmentation Service. Prima di continuare, consulta la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all'API, incluse le intestazioni richieste e la lettura delle chiamate API di esempio.

Recuperare un elenco di processi di esportazione retrieve-list

Per recuperare un elenco di tutti i processi di esportazione per l'organizzazione, eseguire una richiesta GET all'endpoint /export/jobs.

Formato API

L'endpoint /export/jobs supporta diversi parametri di query per 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}
Parametro
Descrizione
{LIMIT}
Specifica il numero di processi di esportazione restituiti.
{OFFSET}
Specifica l'offset delle pagine dei risultati.
{STATUS}
Filtra i risultati in base allo stato. I valori supportati sono "NEW", "SUCCESSEDED" e "FAILED".

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"
    }
}
Proprietà
Descrizione
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 di esportazione batch.
fields
Elenco dei campi esportati, separati da virgole.
schema.name
Nome dello schema associato al set di dati in cui devono essere esportati i dati.
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 segmentID specificato.
  • status: un array di stringhe che fornisce un filtro di stato per segmentID. Per impostazione predefinita, status avrà il valore ["realized"] che rappresenta tutti i profili che rientrano nel segmento al momento. I valori possibili includono: realized e exited. Il valore realized indica che il profilo è idoneo per il segmento. Il valore exiting indica che il profilo sta uscendo dal segmento.
mergePolicy
Informazioni sui criteri di unione per i dati esportati.
metrics.totalTime
Campo che indica il tempo totale richiesto per l'esecuzione del processo di esportazione.
metrics.profileExportTime
Un campo che indica il tempo necessario per l’esportazione dei profili.
page
Informazioni sull’impaginazione dei processi di esportazione richiesti.
link.next
Un collegamento alla pagina successiva dei processi di esportazione.

Crea un nuovo processo di esportazione create

È possibile creare un nuovo processo di esportazione effettuando una richiesta POST all'endpoint /export/jobs.

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
    }
}'
Proprietà
Descrizione
fields
Elenco dei campi esportati, separati da virgole. Se questo campo viene lasciato vuoto, verranno esportati tutti i campi.
mergePolicy
Specifica il criterio di unione da applicare ai dati esportati. Includi questo parametro quando vengono esportati più segmenti. Se non specificato, l’esportazione accetta lo stesso criterio di unione del segmento specificato.
filter
Oggetto che specifica i segmenti da includere nel processo di esportazione in base all’ID, al tempo di qualifica o al tempo di acquisizione, a seconda delle sottoproprietà elencate di seguito. Se questo campo viene lasciato vuoto, verranno esportati tutti i dati.
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 utilizza segments) ID segmento per i profili da esportare.
  • segmentNs (Facoltativo) Spazio dei nomi del segmento per il segmentID specificato.
  • status (Facoltativo) Matrice di stringhe che fornisce un filtro di stato per segmentID. Per impostazione predefinita, status avrà il valore ["realized"] che rappresenta tutti i profili che rientrano nel segmento al momento. I valori possibili includono: realized e exited. Il valore realized indica che il profilo è idoneo per il segmento. Il valore exiting indica che il profilo sta uscendo dal segmento.
filter.segmentQualificationTime
Filtra in base al tempo di qualifica 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 determinato stato. Se non specificato, non sarà presente alcun filtro sull’ora di inizio per la qualifica di un ID segmento. Il timestamp deve essere fornito nel formato RFC 3339.
filter.segmentQualificationTime.endTime
Ora di fine della qualifica del segmento per un ID segmento per un determinato stato. Se non specificato, non sarà presente alcun filtro sull’ora di fine per la qualifica di un ID segmento. Il timestamp deve essere fornito nel formato RFC 3339.
filter.fromIngestTimestamp

Limita i profili esportati a includere solo quelli che sono stati aggiornati dopo questa marca temporale. Il timestamp deve essere fornito nel formato RFC 3339.

  • fromIngestTimestamp per profili, se fornito: include tutti i profili uniti in cui la marca temporale aggiornata unita è maggiore della marca temporale specificata. Supporta operando greater_than.
  • fromIngestTimestamp per eventi: tutti gli eventi acquisiti dopo questa marca temporale verranno esportati in base al risultato del profilo risultante. Non è l’ora dell’evento in sé, ma il tempo di acquisizione degli eventi.
filter.emptyProfiles
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", impostare il valore di emptyProfiles su true. Se emptyProfiles è impostato su false, vengono esportati solo i profili con record di profilo nell'archivio. Per impostazione predefinita, se l'attributo 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 il timestamp in base a quelli che sono stati acquisiti prima del timestamp fornito. 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
(Obbligatorio) Il nome dello schema associato al set di dati in cui devono essere esportati i dati.
evaluationInfo.segmentation
(Facoltativo) Valore booleano che, se non specificato, viene impostato automaticamente su false. Il valore 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"
}
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'oggetto destination di cui sopra avrebbe un array batches, 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 get

Per recuperare informazioni dettagliate su un processo di esportazione specifico, eseguire una richiesta GET all'endpoint /export/jobs e specificare l'ID del processo di esportazione che si desidera recuperare nel percorso della richiesta.

Formato API

GET /export/jobs/{EXPORT_JOB_ID}
Parametro
Descrizione
{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"
}
Proprietà
Descrizione
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 erano in un singolo ID batch. Il 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 set di dati in cui devono essere esportati i dati.
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 segmentID specificato.
  • status: un array di stringhe che fornisce un filtro di stato per segmentID. Per impostazione predefinita, status avrà il valore ["realized"] che rappresenta tutti i profili che rientrano nel segmento al momento. I valori possibili includono: realized e exited. Il valore realized indica che il profilo è idoneo per il segmento. Il valore exiting indica che il profilo sta uscendo dal segmento.
mergePolicy
Informazioni sui criteri di unione per i dati esportati.
metrics.totalTime
Campo che indica il tempo totale richiesto per l'esecuzione del processo di esportazione.
metrics.profileExportTime
Un 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 delete

È possibile richiedere l'eliminazione del processo di esportazione specificato effettuando una richiesta DELETE all'endpoint /export/jobs e fornendo l'ID del processo di esportazione che si desidera eliminare nel percorso della richiesta.

Formato API

DELETE /export/jobs/{EXPORT_JOB_ID}
Parametro
Descrizione
{EXPORT_JOB_ID}
id del processo di esportazione che si desidera 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.

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871