Extremo de trabajos de exportación de perfil
Real-Time Customer Profile permite crear una única vista de clientes individuales reuniendo datos de varias fuentes, incluidos datos de atributos y datos de comportamiento. A continuación, los datos de perfil se pueden exportar a un conjunto de datos para un procesamiento posterior. Por ejemplo, Profile los datos se pueden exportar para su activación mediante la creación de audiencias y los atributos de perfil se pueden exportar para su creación en informes.
Este documento proporciona instrucciones paso a paso para crear y administrar trabajos de exportación mediante API de perfil.
Además de crear un trabajo de exportación, también puede acceder a Profile datos con el /entities
extremo, también conocido como "Profile Access". Consulte la guía de extremo de entidades para obtener más información. Para ver los pasos de cómo acceder a Profile datos mediante la interfaz de usuario, consulte la guía del usuario.
Introducción
Los extremos de API utilizados en esta guía forman parte de la variable Real-Time Customer Profile API. Antes de continuar, consulte la guía de introducción para obtener vínculos a documentación relacionada, una guía para leer las llamadas de API de ejemplo en este documento e información importante sobre los encabezados necesarios para realizar correctamente llamadas a cualquier Experience Platform API.
Creación de un trabajo de exportación
Exportando Profile data requiere crear primero un conjunto de datos al que se exportarán los datos e iniciar después un nuevo trabajo de exportación. Ambos pasos se pueden lograr mediante las API de Experience Platform, la primera con la API de servicio de catálogo y la segunda con la API de perfil del cliente en tiempo real. En las secciones siguientes se describen instrucciones detalladas para completar cada paso.
Crear un conjunto de datos de destinatario
Al exportar Profile , primero se debe crear un conjunto de datos de destinatario. Es importante que el conjunto de datos esté configurado correctamente para garantizar que la exportación se realice correctamente.
Una de las consideraciones clave es el esquema en el que se basa el conjunto de datos (schemaRef.id
en la solicitud de ejemplo de API que aparece a continuación). Para exportar datos de perfil, el conjunto de datos debe basarse en la variable XDM Individual Profile Esquema de unión (https://ns.adobe.com/xdm/context/profile__union
). Un esquema de unión es un esquema de solo lectura generado por el sistema que agrega los campos de esquemas que comparten la misma clase. En este caso, es la variable XDM Individual Profile clase. Para obtener más información sobre los esquemas de vista de unión, consulte la sección unión en la guía conceptos básicos de composición de esquemas.
Los pasos siguientes en este tutorial describen cómo crear un conjunto de datos que haga referencia a la variable XDM Individual Profile Esquema de unión con Catalog API. También puede utilizar el Platform interfaz de usuario para crear un conjunto de datos que haga referencia al esquema de unión. Los pasos para utilizar la interfaz de usuario se describen en Este tutorial de interfaz de usuario para exportar audiencias pero también son aplicables aquí. Una vez finalizado, puede volver a este tutorial para continuar con los pasos de inicio de un nuevo trabajo de exportación.
Si ya tiene un conjunto de datos compatible y conoce su ID, puede continuar directamente con el paso de inicio de un nuevo trabajo de exportación.
Formato de API
POST /dataSets
Solicitud
La siguiente solicitud crea un nuevo conjunto de datos, que proporciona parámetros de configuración en la carga útil.
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Profile Data Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
name
schemaRef.id
Respuesta
Una respuesta correcta devuelve una matriz que contiene el ID único de solo lectura generado por el sistema del conjunto de datos recién creado. Se requiere un ID de conjunto de datos configurado correctamente para exportar correctamente los datos del perfil.
[
"@/datasets/5b020a27e7040801dedba61b"
]
Iniciar trabajo de exportación initiate
Una vez que tenga un conjunto de datos que persista en la unión, puede crear un trabajo de exportación para conservar los datos del perfil en el conjunto de datos realizando una solicitud del POST a /export/jobs
en la API de Perfil del cliente en tiempo real y proporciona los detalles de los datos que desea exportar en el cuerpo de la solicitud.
Formato de API
POST /export/jobs
Solicitud
La siguiente solicitud crea un nuevo trabajo de exportación, que proporciona parámetros de configuración en la carga útil.
curl -X POST \
https://platform.adobe.io/data/core/ups/export/jobs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
}
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}'
fields
mergePolicy
mergePolicy.id
mergePolicy.version
additionalFields.eventList
(Opcional) Controla los campos de eventos de series temporales exportados para los objetos secundarios o asociados proporcionando una o más de las siguientes configuraciones:
eventList.fields
: controle los campos que desea exportar.eventList.filter
: especifica criterios que limitan los resultados incluidos de los objetos asociados. Espera un valor mínimo requerido para la exportación, normalmente una fecha.eventList.filter.fromIngestTimestamp
: Filtra los eventos de series temporales por 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.
destination
(Obligatorio) Información de destino para los datos exportados:
destination.datasetId
: (Obligatorio) El ID del conjunto de datos donde se exportarán los datos.destination.segmentPerBatch
: (Opcional) Un valor booleano que, si no se proporciona, toma el valor predeterminadofalse
. Un valor defalse
exporta todos los ID de definición de segmento a un único ID de lote. Un valor detrue
exporta un ID de definición de segmento a un ID de lote. Tenga en cuenta que configurar el valor para que seatrue
puede afectar al rendimiento de la exportación por lotes.
schema.name
Respuesta
Una respuesta correcta devuelve un conjunto de datos rellenado con datos de perfil como se especifica en la solicitud.
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 24115,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"version": 1
},
"status": "NEW",
"requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
"computeGatewayJobId": {},
"metrics": {
"totalTime": {
"startTimeInMs": 1559674261657
}
},
"destination": {
"dataSetId": "5cf6bcf79ecc7c14530fe436",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
Enumerar todos los trabajos de exportación
Puede devolver una lista de todos los trabajos de exportación de una organización determinada realizando una solicitud de GET a export/jobs
punto final. La solicitud también admite los parámetros de consulta limit
y offset
, como se muestra a continuación.
Formato de API
GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
start
start=4
limit
limit=10
page
page=2
sort
asc
) o descendente ( desc
) pedido. El parámetro sort no funciona cuando se devuelven varias páginas de resultados. Ejemplo: sort=updateTime:asc
Solicitud
curl -X GET \
https://platform.adobe.io/data/core/ups/export/jobs/ \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}'
-H 'x-sandbox-name: {SANDBOX_NAME}'
Respuesta
La respuesta incluye una records
que contiene los trabajos de exportación creados por su organización.
{
"records": [
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 726,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"status": "SUCCEEDED",
"requestId": "d995479c-8a08-4240-903b-af469c67be1f",
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
"pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1538615973895,
"endTimeInMs": 1538616233239,
"totalTimeInMs": 259344
},
"profileExportTime": {
"startTimeInMs": 1538616067445,
"endTimeInMs": 1538616139576,
"totalTimeInMs": 72131
},
"aCPDatasetWriteTime": {
"startTimeInMs": 1538616195172,
"endTimeInMs": 1538616195715,
"totalTimeInMs": 543
}
},
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1538616233239,
"imsOrgId": "{ORG_ID}",
"creationTime": 1538615973895
},
{
"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": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
}
]
},
"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",
"batchId": ""
},
"updateTime": 1538573922551,
"imsOrgId": "{ORG_ID}",
"creationTime": 1538573416687
}
],
"page": {
"sortField": "createdTime",
"sort": "desc",
"pageOffset": "1538573416687_722",
"pageSize": 2
},
"link": {
"next": "/export/jobs/?limit=2&offset=1538573416687_722"
}
}
Monitorización del progreso de exportación
Para ver los detalles de un trabajo de exportación específico o monitorizar su estado mientras se procesa, puede realizar una solicitud de GET al /export/jobs
e incluir el id
del trabajo de exportación en la ruta. El trabajo de exportación se completa una vez que status
devuelve el valor "SUCCEEDED".
Formato de API
GET /export/jobs/{EXPORT_JOB_ID}
{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/24115 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Respuesta
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 24115,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"version": 1
},
"status": "SUCCEEDED",
"requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
"computeGatewayJobId": {
"exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
"pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1547053539564,
"endTimeInMs": 1547054743929,
"totalTimeInMs": 1204365
},
"profileExportTime": {
"startTimeInMs": 1547053667591,
"endTimeInMs": 1547053778195,
"totalTimeInMs": 110604
},
"aCPDatasetWriteTime": {
"startTimeInMs": 1547054660416,
"endTimeInMs": 1547054698918,
"totalTimeInMs": 38502
}
},
"destination": {
"dataSetId": "5cf6bcf79ecc7c14530fe436",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
batchId
Cancelar un trabajo de exportación
Experience Platform permite cancelar un trabajo de exportación existente, lo que puede resultar útil por varios motivos, incluso si el trabajo de exportación no se ha completado o se ha quedado atascado en la fase de procesamiento. Para cancelar un trabajo de exportación, puede realizar una solicitud de DELETE a /export/jobs
e incluir el id
del trabajo de exportación que desea cancelar en la ruta de solicitud.
Formato de API
DELETE /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
del trabajo de exportación al que desea acceder.Solicitud
curl -X POST \
https://platform.adobe.io/data/core/ups/export/jobs/726 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Respuesta
Una solicitud de eliminación correcta devuelve el estado HTTP 204 (sin contenido) y un cuerpo de respuesta vacío, lo que indica que la operación de cancelación se realizó correctamente.
Pasos siguientes
Una vez que la exportación haya finalizado correctamente, los datos estarán disponibles en el lago de datos en Experience Platform. A continuación, puede utilizar la variable API de acceso a datos para acceder a los datos utilizando batchId
asociado con la exportación. Según el tamaño de la exportación, los datos pueden estar en fragmentos y el lote puede constar de varios archivos.
Para obtener instrucciones paso a paso sobre cómo utilizar la API de acceso a datos para acceder y descargar archivos por lotes, siga los Tutorial de acceso a datos.
También puede acceder a los datos del perfil del cliente en tiempo real exportados correctamente mediante el servicio de consultas de Adobe Experience Platform. Al usar la interfaz de usuario o la API de RESTful, el servicio de consultas le permite escribir, validar y ejecutar consultas sobre datos dentro del lago de datos.
Para obtener más información sobre cómo consultar los datos de audiencia, consulte la Documentación del servicio de consultas.
Apéndice
La siguiente sección contiene información adicional sobre los trabajos de exportación en la API de perfil.
Ejemplos adicionales de carga útil de exportación
La llamada de API de ejemplo que se muestra en la sección sobre inicio de un trabajo de exportación crea un trabajo que contiene datos de perfil (registro) y de evento (series temporales). Esta sección proporciona ejemplos de carga útil de solicitud adicionales para limitar la exportación a contener un tipo de datos u otro.
La siguiente carga útil crea un trabajo de exportación que solo contiene datos de perfil (sin eventos):
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
Para crear un trabajo de exportación que solo contenga datos de evento (sin atributos de perfil), la carga útil puede tener un aspecto similar al siguiente:
{
"fields": "identityMap",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
Exportación de audiencias
También puede utilizar el extremo de trabajos de exportación para exportar audiencias en lugar de Profile datos. Consulte la guía de exportar trabajos en la API de segmentación para obtener más información.