Guía para desarrolladores de ingesta por lotes
Este documento proporciona una guía completa para utilizar extremos de API de ingesta por lotes en Adobe Experience Platform. Para obtener una descripción general de las API de ingesta por lotes, incluidos los requisitos previos y las prácticas recomendadas, comience por leer el información general de API de ingesta por lotes.
En el apéndice del presente documento se proporciona información sobre datos de formato que se utilizarán para la ingesta, incluidos archivos de datos CSV y JSON de ejemplo.
Primeros pasos
Los extremos de API utilizados en esta guía forman parte de la variable API de ingesta por lotes. La ingesta por lotes se proporciona a través de una API RESTful, donde puede realizar operaciones básicas de CRUD con los tipos de objetos admitidos.
Antes de continuar, consulte la información general de API de ingesta por lotes y el guía de introducción.
Ingesta de archivos JSON
Crear lote
En primer lugar, debe crear un lote, con JSON como formato de entrada. Al crear el lote, deberá proporcionar un ID de conjunto de datos. También deberá asegurarse de que todos los archivos cargados como parte del lote se ajusten al esquema XDM vinculado al conjunto de datos proporcionado.
isMultiLineJson
será necesario establecer el indicador. Para obtener más información, lea la guía de solución de problemas de ingesta por lotes.Formato de API
POST /batches
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-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 '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
{DATASET_ID}
Respuesta
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
Cargar archivos
Ahora que ha creado un lote, puede utilizar el ID de lote de la respuesta de creación de lotes para cargar archivos en el lote. Puede cargar varios archivos en el lote.
Formato de API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'content-type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Respuesta
200 OK
Completar lote
Una vez que haya terminado de cargar todas las diferentes partes del archivo, deberá indicar que los datos se han cargado completamente y que el lote está listo para la promoción.
Formato de API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitud
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-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
200 OK
Ingesta de archivos de Parquet ingest-parquet-files
Crear lote
En primer lugar, deberá crear un lote, con Parquet como formato de entrada. Al crear el lote, deberá proporcionar un ID de conjunto de datos. También deberá asegurarse de que todos los archivos cargados como parte del lote se ajusten al esquema XDM vinculado al conjunto de datos proporcionado.
Solicitud
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-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 '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Respuesta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Cargar archivos
Ahora que ha creado un lote, puede utilizar el batchId
desde antes de cargar los archivos en el lote. Puede cargar varios archivos en el lote.
Formato de API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.parquet
.Respuesta
200 OK
Completar lote
Una vez que haya terminado de cargar todas las diferentes partes del archivo, deberá indicar que los datos se han cargado completamente y que el lote está listo para la promoción.
Formato de API
POST /batches/{BATCH_ID}?action=complete
{BATCH_ID}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-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
200 OK
Ingesta de archivos grandes de Parquet
Crear lote
En primer lugar, deberá crear un lote, con Parquet como formato de entrada. Al crear el lote, deberá proporcionar un ID de conjunto de datos. También deberá asegurarse de que todos los archivos cargados como parte del lote se ajusten al esquema XDM vinculado al conjunto de datos proporcionado.
Formato de API
POST /batches
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-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 '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Respuesta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Inicializar archivo grande
Después de crear el lote, deberá inicializar el archivo grande antes de cargar los fragmentos en el lote.
Formato de API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=INITIALIZE \
-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
201 Created
Cargar fragmentos de archivo grandes
Ahora que se ha creado el archivo, se pueden cargar todos los fragmentos posteriores realizando solicitudes repetidas al PATCH, una para cada sección del archivo.
Formato de API
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X PATCH https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Range: bytes {CONTENT_RANGE}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{CONTENT_RANGE}
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Respuesta
200 OK
Archivo grande completo
Ahora que ha creado un lote, puede utilizar el batchId
desde antes de cargar los archivos en el lote. Puede cargar varios archivos en el lote.
Formato de API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=COMPLETE \
-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
201 Created
Completar lote
Una vez que haya terminado de cargar todas las diferentes partes del archivo, deberá indicar que los datos se han cargado completamente y que el lote está listo para la promoción.
Formato de API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-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
200 OK
Ingesta de archivos CSV
Para introducir archivos CSV, deberá crear una clase, un esquema y un conjunto de datos que admita CSV. Para obtener información detallada sobre cómo crear la clase y el esquema necesarios, siga las instrucciones que se proporcionan en la tutorial de creación de esquemas ad hoc.
Crear conjunto de datos
Después de seguir las instrucciones anteriores para crear la clase y el esquema necesarios, debe crear un conjunto de datos compatible con CSV.
Formato de API
POST /catalog/dataSets
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "{DATASET_NAME}",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
{TENANT_ID}
{SCHEMA_ID}
Crear lote
A continuación, debe crear un lote con CSV como formato de entrada. Al crear el lote, deberá proporcionar un ID de conjunto de datos. También deberá asegurarse de que todos los archivos cargados como parte del lote se ajusten al esquema vinculado al conjunto de datos proporcionado.
Formato de API
POST /batches
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-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 '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "csv"
}
}'
{DATASET_ID}
Respuesta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Cargar archivos
Ahora que ha creado un lote, puede utilizar el batchId
desde antes de cargar los archivos en el lote. Puede cargar varios archivos en el lote.
Formato de API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.csv \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.csv"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.csv
.Respuesta
200 OK
Completar lote
Una vez que haya terminado de cargar todas las diferentes partes del archivo, deberá indicar que los datos se han cargado completamente y que el lote está listo para la promoción.
Formato de API
POST /batches/{BATCH_ID}?action=COMPLETE
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-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
200 OK
Cancelar un lote
Mientras el lote se está procesando, aún se puede cancelar. Sin embargo, una vez finalizado un lote (como un estado correcto o fallido), el lote no se puede cancelar.
Formato de API
POST /batches/{BATCH_ID}?action=ABORT
{BATCH_ID}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=ABORT \
-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
200 OK
Eliminar un lote delete-a-batch
Un lote se puede eliminar realizando la siguiente solicitud de POST con el action=REVERT
parámetro de consulta al ID del lote que desea eliminar. El lote está marcado como "inactivo", por lo que es apto para la recolección de basura. El lote se recopilará asincrónicamente, momento en el que se marcará como "eliminado".
Formato de API
POST /batches/{BATCH_ID}?action=REVERT
{BATCH_ID}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=REVERT \
-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
200 OK
Parche de un lote
En ocasiones puede ser necesario actualizar los datos en el almacén de perfiles de su organización. Por ejemplo, es posible que tenga que corregir registros o cambiar un valor de atributo. Adobe Experience Platform admite la actualización o el parche de datos del Almacenamiento de perfiles mediante una acción de actualización o "aplicación de parches a un lote".
Para aplicar parches a un lote, es necesario lo siguiente:
- Un conjunto de datos habilitado para actualizaciones de perfiles y atributos. Esto se realiza mediante etiquetas de conjuntos de datos y requiere un
isUpsert:true
se añadirá a la etiquetaunifiedProfile
matriz. Para obtener más información sobre los pasos que muestran cómo crear un conjunto de datos o configurar uno existente para su actualización, siga el tutorial de habilitar un conjunto de datos para actualizaciones de perfil. - Archivo de parquet que contiene los campos a los que se va a aplicar el parche y los campos de identidad del perfil. El formato de datos para aplicar parches a un lote es similar al proceso normal de introducción por lotes. La entrada requerida es un archivo de Parquet. Además de los campos que se van a actualizar, los datos cargados deben contener los campos de identidad para que coincidan con los datos del almacén de perfiles.
Una vez que tenga un conjunto de datos habilitado para Perfil y actualización, y un archivo de Parquet que contenga los campos a los que desee aplicar parches, así como los campos de identidad necesarios, puede seguir los pasos para ingesta de archivos de Parquet para completar el parche mediante la ingesta por lotes.
Reproducción de un lote
Si desea reemplazar un lote ya introducido, puede hacerlo con "reproducción por lotes": esta acción equivale a eliminar el lote antiguo e ingerir uno nuevo en su lugar.
Crear lote
En primer lugar, debe crear un lote, con JSON como formato de entrada. Al crear el lote, deberá proporcionar un ID de conjunto de datos. También deberá asegurarse de que todos los archivos cargados como parte del lote se ajusten al esquema XDM vinculado al conjunto de datos proporcionado. Además, deberá proporcionar los lotes antiguos como referencia en la sección de reproducción. En el siguiente ejemplo, se reproducen lotes con ID batchIdA
y batchIdB
.
Formato de API
POST /batches
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-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 '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
},
"replay": {
"predecessors": ["${batchIdA}","${batchIdB}"],
"reason": "replace"
}
}'
{DATASET_ID}
Respuesta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"replay": {
"predecessors": [
"batchIdA", "batchIdB"
],
"reason": "replace"
},
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Cargar archivos
Ahora que ha creado un lote, puede utilizar el batchId
desde antes de cargar los archivos en el lote. Puede cargar varios archivos en el lote.
Formato de API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Solicitud
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Respuesta
200 OK
Completar lote
Una vez que haya terminado de cargar todas las diferentes partes del archivo, deberá indicar que los datos se han cargado completamente y que el lote está listo para la promoción.
Formato de API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Solicitud
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-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
200 OK
Apéndice
La siguiente sección contiene información adicional para la ingesta de datos en Experience Platform mediante la ingesta por lotes.
Transformación de datos para la ingesta por lotes
Para introducir un archivo de datos en Experience Platform, la estructura jerárquica del archivo debe cumplir con el Modelo de datos de experiencia (XDM) esquema asociado con el conjunto de datos que se carga en.
Encontrará información sobre cómo asignar un archivo CSV para cumplir con un esquema XDM en la transformaciones de muestra , junto con un ejemplo de un archivo de datos JSON con el formato correcto. Los archivos de ejemplo proporcionados en el documento se pueden encontrar aquí: