Esta documentación le ayudará a responder a las preguntas más frecuentes sobre Adobe Experience Platform Batch Data Ingestion API.
El 200 OK
La respuesta de la API significa que el lote se ha aceptado para el procesamiento; no estará activo hasta que pase a su estado final, como Activo o Fallo.
Sí, es seguro volver a intentar la llamada de API. A pesar del error, es posible que la operación se haya realizado correctamente y que el lote se haya aceptado correctamente. Sin embargo, se espera que los clientes tengan mecanismos de reintento en caso de que falle la API y, de hecho, se les anima a volver a intentarlo. Si la operación se realiza correctamente, la API devolverá el resultado correcto, incluso después de volver a intentarlo.
El tamaño de archivo recomendado para utilizar la API de carga de archivos grandes es de 256 MB o más. Puede encontrar más información sobre cómo utilizar la API de carga de archivos grandes aquí.
Si se encuentran fragmentos de un archivo grande superpuestos o no se encuentran, el servidor responde con una petición HTTP 400 incorrecta. Esto puede ocurrir porque es posible cargar fragmentos superpuestos, ya que las validaciones de rango se realizan en el momento de finalizar el archivo, cuando los fragmentos del archivo se vinculan entre sí.
Actualmente, se admiten tanto Parquet como JSON. El CSV se admite en versiones anteriores: aunque los datos se promocionarán a formato principal y se realizarán comprobaciones preliminares, no se admitirán funciones modernas, como conversión, partición o validación de filas.
El formato de entrada debe especificarse en el momento de la creación del lote dentro de la carga útil. A continuación se muestra un ejemplo de cómo especificar el formato de entrada por lotes:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
Para que los datos aparezcan en el conjunto de datos, el lote debe marcarse como completado. Todos los archivos que desee introducir deben cargarse antes de marcar el lote como completado. A continuación puede ver un ejemplo de cómo marcar un lote como completado:
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}'
Para ingerir JSON de varias líneas, la variable isMultiLineJson
debe establecerse el indicador en el momento de la creación del lote. A continuación puede ver un ejemplo de esto:
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json",
"isMultiLineJson": true
}
}'
Para las líneas JSON, hay un objeto JSON por línea. Por ejemplo:
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}
Para JSON de varias líneas, un objeto puede ocupar varias líneas, mientras que todos los objetos se agrupan en una matriz JSON. Por ejemplo:
[
{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
{
"string": "string3",
"int": 3,
"array": [
3,
6,
9
],
"dict": {
"key": "value3",
"extra_key": "extra_value3"
}
}
]
De forma predeterminada, Batch Data Ingestion utiliza JSON de una sola línea.
La ingesta de CSV solo se admite para esquemas planos. Actualmente no se admite la ingesta de datos jerárquicos en CSV.
Para obtener todas las funciones de ingesta de datos, es necesario utilizar los formatos JSON o Parquet.
Se realizan tres niveles de validación en los datos:
Un lote ya introducido se puede reemplazar mediante la función Reproducción por lotes. Puede encontrar más información sobre la reproducción por lotes aquí.
Una vez que se ha indicado un lote para la promoción por lotes, el progreso de la ingesta por lotes se puede monitorizar con la siguiente solicitud:
curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
Con esta solicitud, obtendrá una respuesta similar a la siguiente:
200 OK
{
"{BATCH_ID}":{
"imsOrg":"{ORG_ID}",
"created":1494349962314,
"createdClient":"{API_KEY}",
"createdUser":"{USER_ID}",
"updatedUser":"{USER_ID}",
"completed":1494349963467,
"externalId":"{EXTERNAL_ID}",
"status":"staging",
"errors":[],
}
}
Un lote puede, en su ciclo de vida, pasar por los siguientes estados:
Estado | Datos escritos en Principal | Descripción |
---|---|---|
Abandonado | El cliente no ha podido completar el lote en el periodo de tiempo esperado. | |
Anulado | El cliente ha llamado explícitamente a través de Batch Data Ingestion API, una operación de anulación para el lote especificado. Una vez que un lote se encuentra en el estado Cargado, el lote no se puede cancelar. | |
Activo/Con éxito | x | El lote se ha promocionado correctamente de fase a maestro y ahora está disponible para el consumo descendente. Nota: Activo y de éxito se utilizan indistintamente. |
Archivado | El lote se ha archivado en almacenamiento en frío. | |
Fallido/Fallo | Un estado de terminal que resulta de una configuración incorrecta o de datos incorrectos. Se registra un error procesable, junto con el lote, para permitir a los clientes corregir y volver a enviar los datos. Nota: Error y Error se utilizan indistintamente. | |
Inactivo | x | El lote se ha promocionado correctamente, pero se ha revertido o ha caducado. El lote ya no estará disponible para el consumo descendente, pero los datos subyacentes permanecerán en Principal hasta que se hayan retenido, archivado o eliminado de otra forma. |
Cargando | El cliente está escribiendo datos para el lote. El lote es no listo para la promoción, en este momento. | |
Cargado | El cliente ha completado la escritura de datos para el lote. El lote está listo para la promoción. | |
Retenido | Los datos se han sacado de Principal y en un archivo designado en el lago de datos de Adobe. | |
Ensayo | El cliente ha indicado correctamente el lote para la promoción y los datos se están almacenando en zona intermedia para su consumo descendente. | |
Reintentando | El cliente ha indicado el lote para su promoción, pero debido a un error, un servicio de monitorización de lotes está reintentando el lote. Este estado se puede utilizar para indicar a los clientes que puede haber un retraso en la ingesta de los datos. | |
Parado | El cliente ha indicado el lote para la promoción, pero después de n reintentos de un servicio de Monitorización por lotes, la promoción por lotes se ha detenido. |
Cuando un lote está en "Ensayo", significa que el lote se marcó correctamente para su promoción y que los datos se están almacenando en zona intermedia para su consumo descendente.
Cuando un lote está en "Reintentando", significa que la ingesta de datos del lote se ha detenido temporalmente debido a problemas intermitentes. Cuando esto sucede, no requiere la intervención del cliente.
Cuando un lote está en "Parado", significa que Data Ingestion Services tiene dificultades para ingerir el lote y se han agotado todos los reintentos.
Cuando un lote está en "Cargando", significa que no se ha llamado al API CompleteBatch para promocionar el lote.
Una vez que el estado del lote es "Activo", el lote se ha introducido correctamente. Para averiguar el estado del lote, siga los pasos detallados anterior.
Cuando falla un lote, el motivo por el que falla se puede identificar en la variable errors
de la carga útil. A continuación se muestran ejemplos de errores:
"errors":[
{
"code":"106",
"description":"Dataset file is empty. Please upload file with data.",
"rows":[]
},
{
"code":"118",
"description":"CSV file contains empty header row.",
"rows":[]
}
]
Una vez corregidos los errores, se puede volver a cargar el lote.
En lugar de eliminar directamente de Catalog, los lotes deben eliminarse utilizando cualquiera de los métodos siguientes:
Las siguientes métricas de nivel de lote están disponibles para lotes en el estado Activo/Correcto:
Métrica | Descripción |
---|---|
inputByteSize | Número total de bytes clasificados para Data Ingestion Services para procesar. |
inputRecordSize | Número total de filas organizadas para Data Ingestion Services para procesar. |
outputByteSize | Número total de bytes generados por Data Ingestion Services hasta Data Lake. |
outputRecordSize | Número total de filas generadas por Data Ingestion Services hasta Data Lake. |
partitionCount | Número total de particiones escritas en Data Lake. |
Existen dos razones por las que las métricas pueden no estar disponibles en el lote:
Código de estado | Descripción |
---|---|
106 | El archivo del conjunto de datos está vacío. |
118 | El archivo CSV contiene una fila de encabezado vacía. |
200 | El lote se ha aceptado para su procesamiento y pasará a un estado final, como Activo o Error. Una vez enviado, el lote se puede monitorizar utilizando GetBatch punto final. |
400 | Solicitud incorrecta. Se devuelve si faltan fragmentos o si hay trozos superpuestos en un lote. |