Exportar extremo de trabajos

Los trabajos de exportación son procesos asincrónicos que se utilizan para mantener a los miembros del segmento de audiencia en conjuntos de datos. Puede utilizar el extremo /export/jobs en la API de segmentación de Adobe Experience Platform, que le permite recuperar, crear y cancelar trabajos de exportación mediante programación.

NOTA

Esta guía cubre el uso de trabajos de exportación en Segmentation API. Para obtener información sobre cómo administrar los trabajos de exportación para datos Real-time Customer Profile, consulte la guía sobre trabajos de exportación en la API de perfil

Primeros pasos

Los extremos utilizados en esta guía forman parte de la API Adobe Experience Platform Segmentation Service. Antes de continuar, consulte la guía de introducción para obtener información importante que debe conocer para realizar llamadas correctamente a la API, incluidos los encabezados necesarios y cómo leer llamadas de API de ejemplo.

Recuperar una lista de trabajos de exportación

Puede recuperar una lista de todos los trabajos de exportación para su organización IMS realizando una solicitud de GET al extremo /export/jobs .

Formato de API

El extremo /export/jobs admite varios parámetros de consulta para ayudar a filtrar los resultados. Aunque estos parámetros son opcionales, se recomienda encarecidamente su uso para ayudar a reducir los costes generales. Al realizar una llamada a este extremo sin parámetros, se recuperarán todos los trabajos de exportación disponibles para su organización. Se pueden incluir varios parámetros, separados por el símbolo "&".

GET /export/jobs
GET /export/jobs?limit={LIMIT}
GET /export/jobs?offset={OFFSET}
GET /export/jobs?status={STATUS}
Parámetro Descripción
{LIMIT} Especifica el número de trabajos de exportación devueltos.
{OFFSET} Especifica el desplazamiento de las páginas de resultados.
{STATUS} Filtra los resultados según el estado. Los valores admitidos son "NEW", "SUCCEEDED" y "FAILED".

Solicitud

La siguiente solicitud recuperará los dos últimos trabajos de exportación dentro de la organización 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}'

Respuesta

La siguiente respuesta devuelve el estado HTTP 200 con una lista de trabajos de exportación completados correctamente, en función del parámetro de consulta proporcionado en la ruta de solicitud.

{
    "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"
    }
}
Propiedad Descripción
destination Información de destino de los datos exportados:
  • datasetId: ID del conjunto de datos donde se exportaron los datos.
  • segmentPerBatch: Un valor booleano que muestra si los ID de segmento se consolidan o no. Un valor de "false" significa que todos los ID de segmento se exportan a un único ID de lote. Un valor "true" significa que se exporta un ID de segmento a un ID de lote. Nota: Si se establece el valor en true , puede afectar al rendimiento de la exportación de lotes.
fields Una lista de los campos exportados, separados por comas.
schema.name Nombre del esquema asociado con el conjunto de datos donde se exportan los datos.
filter.segments Los segmentos que se exportan. Se incluyen los siguientes campos:
  • segmentId: El ID de segmento al que se exportarán los perfiles.
  • segmentNs: Área de nombres del segmento para el segmentID dado.
  • status: Matriz de cadenas que proporciona un filtro de estado para segmentID. De forma predeterminada, status tendrá el valor ["realized", "existing"] que representa todos los perfiles que entran en el segmento en el momento actual. Los valores posibles incluyen: “realizada”, “existente” y “abandonada”. Un valor de “realizada” significa que el perfil está entrando en el segmento. Un valor de “existente” significa que el perfil sigue estando en el segmento. Un valor de “salir” significa que el perfil está saliendo del segmento.
mergePolicy Información de directiva de combinación para los datos exportados.
metrics.totalTime Campo que indica el tiempo total que tardó en ejecutarse el trabajo de exportación.
metrics.profileExportTime Campo que indica el tiempo que tardan los perfiles en exportarse.
page Información sobre la paginación de los trabajos de exportación solicitados.
link.next Un vínculo a la siguiente página de trabajos de exportación.

Crear un nuevo trabajo de exportación

Puede crear un nuevo trabajo de exportación realizando una solicitud de POST al extremo /export/jobs .

Formato de API

POST /export/jobs

Solicitud

La siguiente solicitud crea un nuevo trabajo de exportación, configurado por los parámetros proporcionados en la carga útil.

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
    }
}'
Propiedad Descripción
fields Una lista de los campos exportados, separados por comas. Si se deja en blanco, se exportan todos los campos.
mergePolicy Especifica la directiva de combinación que debe regir los datos exportados. Incluya este parámetro cuando se exporten varios segmentos. Si no se proporciona, la exportación tendrá la misma política de combinación que el segmento dado.
filter Un objeto que especifica los segmentos que se van a incluir en el trabajo de exportación por ID, tiempo de calificación o tiempo de ingesta, según las subpropiedades que se enumeran a continuación. Si se deja en blanco, se exportan todos los datos.
filter.segments Especifica los segmentos que se van a exportar. Si se omite este valor, se exportarán todos los datos de todos los perfiles. Acepta una matriz de objetos de segmento, cada uno de los cuales contiene los siguientes campos:
  • segmentId: (Necesario si se utiliza segments) ID de segmento para perfiles que se van a exportar.
  • segmentNs (Opcional) Área de nombres de segmento para el segmentIDsegmento dado.
  • status (Opcional) Matriz de cadenas que proporciona un filtro de estado para segmentID. De forma predeterminada, status tendrá el valor ["realized", "existing"] que representa todos los perfiles que entran en el segmento en el momento actual. Los valores posibles incluyen: "realized", "existing" y "exited". Un valor de “realizada” significa que el perfil está entrando en el segmento. Un valor de “existente” significa que el perfil sigue estando en el segmento. Un valor de “salir” significa que el perfil está saliendo del segmento.
filter.segmentQualificationTime Filtre en función del tiempo de calificación del segmento. Se puede proporcionar la hora de inicio y/o de finalización.
filter.segmentQualificationTime.startTime Hora de inicio de la calificación del segmento para un ID de segmento para un estado determinado. No se proporciona, no habrá ningún filtro en la hora de inicio para la calificación de ID de segmento. La marca de tiempo debe proporcionarse en formato RFC 3339.
filter.segmentQualificationTime.endTime Hora de finalización de la calificación de segmentos para un ID de segmento para un estado determinado. No se proporciona, no habrá filtro en la hora de finalización para la calificación de ID de segmento. La marca de tiempo debe proporcionarse en formato RFC 3339.
filter.fromIngestTimestamp Limita los perfiles exportados para incluir solo los que se han actualizado después de esta marca de tiempo. La marca de tiempo debe proporcionarse en formato RFC 3339.
  • fromIngestTimestamp para perfiles, si se proporciona: Incluye todos los perfiles combinados en los que la marca de tiempo actualizada combinada es buena que la marca de tiempo determinada. Admite greater_than operando.
  • fromIngestTimestamp para eventos: Todos los eventos incorporados después de esta marca de tiempo se exportarán según el resultado del perfil resultante. No es la hora del evento en sí, sino la hora de ingesta de los eventos.
filter.emptyProfiles Un valor booleano que indica si se desea filtrar por perfiles vacíos. Los perfiles pueden contener registros de perfil, registros de ExperienceEvent o ambos. Los perfiles sin registros de perfil y solo los registros de ExperienceEvent se denominan "emptyProfiles". Para exportar todos los perfiles del almacén de perfiles, incluido "emptyProfiles", establezca el valor de emptyProfiles en true. Si emptyProfiles se establece en false, solo se exportan los perfiles con registros de perfil en el almacén. De forma predeterminada, si no se incluye el atributo emptyProfiles , solo se exportan los perfiles que contienen registros de perfil.
additionalFields.eventList Controla los campos de evento de serie temporal exportados para objetos secundarios o asociados proporcionando una o más de las siguientes configuraciones:
  • fields: Controle los campos que desea exportar.
  • filter: Especifica criterios que limitan los resultados incluidos de objetos asociados. Espera un valor mínimo necesario para la exportación, normalmente una fecha.
  • filter.fromIngestTimestamp: Filtra los eventos de series temporales a los que se han introducido después de la marca de tiempo proporcionada. No es la hora del evento en sí, sino la hora de ingesta de los eventos.
  • filter.toIngestTimestamp: Filtra la marca de tiempo a las que se han introducido antes de la marca de tiempo proporcionada. No es la hora del evento en sí, sino la hora de ingesta de los eventos.
destination (Obligatorio) Información sobre los datos exportados:
  • datasetId: (Obligatorio) El ID del conjunto de datos donde se exportan los datos.
  • segmentPerBatch: (Opcional) Un valor booleano que, si no se proporciona, toma el valor predeterminado "false". El valor "false" exporta todos los ID de segmento en un único ID de lote. El valor "true" exporta un ID de segmento en un ID de lote. Tenga en cuenta que configurar el valor como "true" puede afectar al rendimiento de la exportación por lotes.
schema.name (Obligatorio) El nombre del esquema asociado con el conjunto de datos donde se exportan los datos.
evaluationInfo.segmentation (Opcional) Un valor booleano que, si no se proporciona, toma el valor predeterminado false. Un valor de true indica que la segmentación debe realizarse en el trabajo de exportación.

Respuesta

Una respuesta correcta devuelve el estado HTTP 200 con detalles del trabajo de exportación recién creado.

{
    "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"
}
Propiedad Descripción
id Un valor de solo lectura generado por el sistema que identifica el trabajo de exportación que acaba de crearse.

Alternativamente, si destination.segmentPerBatch se hubiera configurado en true, el objeto destination anterior tendría una matriz batches, como se muestra a continuación:

    "destination": {
        "dataSetId" : "{DATASET_ID}",
        "segmentPerBatch": true,
        "batches" : [
            {
                "segmentId": "segment1",
                "segmentNs": "ups",
                "status": ["realized"],
                "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
            },
            {
                "segmentId": "segment2",
                "segmentNs": "AdCloud",
                "status": "exited",
                "batchId": "df4gssdfb93a09f7e37fa53ad52"
            }
        ]
    }

Recuperar un trabajo de exportación específico

Puede recuperar información detallada sobre un trabajo de exportación específico realizando una solicitud de GET al extremo /export/jobs y proporcionando el ID del trabajo de exportación que desea recuperar en la ruta de solicitud.

Formato de API

GET /export/jobs/{EXPORT_JOB_ID}
Parámetro Descripción
{EXPORT_JOB_ID} El id del trabajo de exportación al que desea acceder.

Solicitud

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}'

Respuesta

Una respuesta correcta devuelve el estado HTTP 200 con información detallada sobre el trabajo de exportación especificado.

{
    "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"
}
Propiedad Descripción
destination Información de destino de los datos exportados:
  • datasetId: ID del conjunto de datos donde se exportaron los datos.
  • segmentPerBatch: Un valor booleano que muestra si los ID de segmento se consolidan o no. Un valor de false significa que todos los ID de segmento se incluyeron en un único ID de lote. Un valor de true significa que se exporta un ID de segmento en un ID de lote.
fields Una lista de los campos exportados, separados por comas.
schema.name Nombre del esquema asociado con el conjunto de datos donde se exportan los datos.
filter.segments Los segmentos que se exportan. Se incluyen los siguientes campos:
  • segmentId: ID de segmento para perfiles que se van a exportar.
  • segmentNs: Área de nombres del segmento para el segmentID dado.
  • status: Matriz de cadenas que proporciona un filtro de estado para segmentID. De forma predeterminada, status tendrá el valor ["realized", "existing"] que representa todos los perfiles que entran en el segmento en el momento actual. Los valores posibles incluyen: “realizada”, “existente” y “abandonada”. Un valor de “realizada” significa que el perfil está entrando en el segmento. Un valor de “existente” significa que el perfil sigue estando en el segmento. Un valor de “salir” significa que el perfil está saliendo del segmento.
mergePolicy Información de directiva de combinación para los datos exportados.
metrics.totalTime Campo que indica el tiempo total que tardó en ejecutarse el trabajo de exportación.
metrics.profileExportTime Campo que indica el tiempo que tardan los perfiles en exportarse.
totalExportedProfileCounter Número total de perfiles exportados en todos los lotes.

Cancelar o eliminar un trabajo de exportación específico

Puede solicitar la eliminación del trabajo de exportación especificado realizando una solicitud de DELETE al extremo /export/jobs y proporcionando el ID del trabajo de exportación que desea eliminar en la ruta de solicitud.

Formato de API

DELETE /export/jobs/{EXPORT_JOB_ID}
Parámetro Descripción
{EXPORT_JOB_ID} El id del trabajo de exportación que desea eliminar.

Solicitud

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}'

Respuesta

Una respuesta correcta devuelve el estado HTTP 204 con el siguiente mensaje:

{
  "status": true,
  "message": "Export job has been marked for cancelling"
}

Pasos siguientes

Después de leer esta guía, ahora puede comprender mejor cómo funcionan los trabajos de exportación.

En esta página