DocumentaciónExperience PlatformGuía del servicio de segmentación

Extremo de trabajos de exportación de segmentos

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

Creado para:

  • Desarrollador

Los trabajos de exportación son procesos asincrónicos que se utilizan para mantener los miembros de segmentos 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 mediante programación los trabajos de exportación.

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

Introducción

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

Recuperación de una lista de trabajos de exportación retrieve-list

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

Formato de API

El extremo /export/jobs admite varios parámetros de consulta para filtrar los resultados. Aunque estos parámetros son opcionales, se recomienda encarecidamente su uso para ayudar a reducir los costes generales. Si realiza 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 et (&).

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 su organización.

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

Respuesta

La siguiente respuesta devuelve el estado HTTP 200 con una lista de los trabajos de exportación completados correctamente, según el 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"]
                    }
                ]
            },
            "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 para los datos exportados:

  • datasetId: ID del conjunto de datos donde se exportaron los datos.
  • segmentPerBatch: Valor booleano que muestra si los ID de segmento están consolidados o no. El valor "false" significa que todos los ID de segmento se exportan a un único ID de lote. El valor "true" significa que se exporta un ID de segmento a un ID de lote. Nota: Si establece el valor en true, puede afectar al rendimiento de la exportación por lotes.
fields
Una lista de los campos exportados, separados por comas.
schema.name
Nombre del esquema asociado al conjunto de datos donde se exportarán los datos.
filter.segments

Los segmentos que se exportan. Se incluyen los siguientes campos:

  • segmentId: ID del segmento al que se exportarán los perfiles.
  • segmentNs: área de nombres de segmento para el objeto segmentID dado.
  • status: matriz de cadenas que proporciona un filtro de estado para segmentID. De manera predeterminada, status tendrá el valor ["realized"], que representa todos los perfiles que pertenecen al segmento en el momento actual. Los valores posibles incluyen: realized y exited. Un valor de realized significa que el perfil califica para el segmento. Un valor de exiting significa que el perfil está saliendo del segmento.
mergePolicy
Combinar información de directivas 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 exportar.
page
Información sobre la paginación de los trabajos de exportación solicitados.
link.next
Un vínculo a la página siguiente de los trabajos de exportación.

Creación de un nuevo trabajo de exportación create

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: {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
    }
}'
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 política de combinación que rige los datos exportados. Incluya este parámetro cuando se exporten varios segmentos. Si no se proporciona, la exportación sigue 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 exportarán 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: (obligatorio si se usa segments) ID de segmento para los perfiles que se van a exportar.
  • segmentNs (Opcional) espacio de nombres de segmento para el segmentID dado.
  • status (Opcional) Una matriz de cadenas que proporciona un filtro de estado para segmentID. De manera predeterminada, status tendrá el valor ["realized"], que representa todos los perfiles que pertenecen al segmento en el momento actual. Los valores posibles incluyen: realized y exited. Un valor de realized significa que el perfil califica para el segmento. Un valor de exiting significa que el perfil está saliendo del segmento.
filter.segmentQualificationTime
Filtro basado en el tiempo de calificación de segmentos. Se puede proporcionar la hora de inicio o la hora de finalización.
filter.segmentQualificationTime.startTime
Hora de inicio de calificación de segmentos para un ID de segmento para un estado determinado. Si no se proporciona, no habrá ningún filtro en la hora de inicio para una calificación de ID de segmento. La marca de tiempo debe proporcionarse en formato RFC 3339.
filter.segmentQualificationTime.endTime
Hora de finalización de calificación de segmentos para un ID de segmento para un estado determinado. Si no se proporciona, no habrá ningún filtro en el momento de finalización para una 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 mayor que la marca de tiempo dada. Admite el operando greater_than.
  • fromIngestTimestamp para eventos: todos los eventos introducidos después de esta marca de tiempo se exportarán correspondiente al 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 filtran los perfiles vacíos. Los perfiles pueden contener registros de perfil, registros de ExperienceEvent o ambos. Los perfiles sin registros de perfil y solo 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 el atributo emptyProfiles no se incluye, solo se exportan los perfiles que contienen registros de perfil.
additionalFields.eventList

Controla los campos de eventos de series temporales exportados para los 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 en los objetos asociados. Espera un valor mínimo requerido 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 aquellas 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) ID del conjunto de datos donde se exportarán 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 a un único ID de lote. El valor "true" exporta un ID de segmento a 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 exportarán los datos.
evaluationInfo.segmentation
(opcional) Un valor booleano que, si no se proporciona, toma el valor predeterminado false. El valor true indica que es necesario realizar la segmentación 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": "{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"
}
Propiedad
Descripción
id
Un valor de solo lectura generado por el sistema que identifica el trabajo de exportación que se acaba de crear.

Alternativamente, si destination.segmentPerBatch se hubiera establecido en true, el objeto destination de arriba 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"
            }
        ]
    }

Recuperación de un trabajo de exportación específico get

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

Formato de API

GET /export/jobs/{EXPORT_JOB_ID}
Parámetro
Descripción
{EXPORT_JOB_ID}
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: {ORG_ID}' \
 -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": "{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"
}
Propiedad
Descripción
destination

Información de destino para los datos exportados:

  • datasetId: ID del conjunto de datos donde se exportaron los datos.
  • segmentPerBatch: Valor booleano que muestra si los ID de segmento están consolidados o no. Un valor de false significa que todos los ID de segmento estaban en un único ID de lote. Un valor de true significa que se exporta un ID de segmento a un ID de lote.
fields
Una lista de los campos exportados, separados por comas.
schema.name
Nombre del esquema asociado al conjunto de datos donde se exportarán los datos.
filter.segments

Los segmentos que se exportan. Se incluyen los siguientes campos:

  • segmentId: ID del segmento para los perfiles que se van a exportar.
  • segmentNs: área de nombres de segmento para el objeto segmentID dado.
  • status: matriz de cadenas que proporciona un filtro de estado para segmentID. De manera predeterminada, status tendrá el valor ["realized"], que representa todos los perfiles que pertenecen al segmento en el momento actual. Los valores posibles incluyen: realized y exited. Un valor de realized significa que el perfil califica para el segmento. Un valor de exiting significa que el perfil está saliendo del segmento.
mergePolicy
Combinar información de directivas 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 exportar.
totalExportedProfileCounter
Número total de perfiles exportados en todos los lotes.

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

Puede solicitar que se elimine el trabajo de exportación especificado realizando una solicitud de DELETE al extremo /export/jobs y proporcionando el identificador 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: {ORG_ID}' \
 -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 tiene una mejor comprensión de cómo funcionan los trabajos de exportación.

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