Información general de API de ingesta por lotes

La API de ingesta por lotes de Adobe Experience Platform le permite introducir datos en Platform como archivos por lotes. Los datos que se están ingiriendo pueden ser datos de perfil de un archivo plano (como un archivo Parquet) o datos que se ajusten a un esquema conocido en el registro Experience Data Model (XDM).

La referencia de API de ingesta por lotes proporciona información adicional sobre estas llamadas de API.

El diagrama siguiente describe el proceso de ingesta por lotes:

Introducción

Los extremos de API utilizados en esta guía forman parte de la API de ingesta por lotes. Antes de continuar, revisa la guía de introducción para ver 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 API de Experience Platform.

Data Ingestion requisitos previos

Prácticas recomendadas de ingesta por lotes

Restricciones de ingesta por lotes

La ingesta de datos por lotes tiene algunas restricciones:

Tipos

Al ingerir datos, es importante comprender cómo funcionan los esquemas XDM (Experience Data Model). Para obtener más información sobre cómo se asignan los tipos de campo XDM a diferentes formatos, lea la Guía para desarrolladores de Schema Registry.

Existe cierta flexibilidad a la hora de ingerir datos: si un tipo no coincide con lo que hay en el esquema de destino, los datos se convertirán al tipo de destino expresado. Si no puede, se producirá un error en el lote con un TypeCompatibilityException.

Por ejemplo, ni JSON ni CSV tienen un tipo date o date-time. Como resultado, estos valores se expresan mediante cadenas con formato ISO 8601 ("2018-07-10T15:05:59.000-08:00") o Tiempo Unix formateado en milisegundos (1531263959000) y se convierten en el momento de la ingesta al tipo XDM de destino.

La tabla siguiente muestra las conversiones admitidas al ingerir datos.

Uso de la API

La API Data Ingestion le permite ingerir datos por lotes (una unidad de datos que consta de uno o más archivos que se van a ingerir como una sola unidad) en Experience Platform en tres pasos básicos:

Crear un lote

Para poder agregar datos a un conjunto de datos, deben vincularlos a un lote, que se cargará posteriormente en un conjunto de datos especificado.

POST /batches

Solicitud

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "Content-Type: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{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}"
}

Carga de archivo

Después de crear correctamente un nuevo lote para cargar, los archivos se pueden cargar en un conjunto de datos específico.

Puede cargar archivos mediante la API de carga de archivos pequeños. Sin embargo, si los archivos son demasiado grandes y se supera el límite de la puerta de enlace (como tiempos de espera prolongados, solicitudes de tamaño de cuerpo excedidos y otras restricciones), puede cambiar a la API de carga de archivos grandes. Esta API carga el archivo en fragmentos y vincula los datos mediante la llamada de API Large File Upload Complete.

Carga de archivo pequeño

Una vez creado un lote, los datos se pueden cargar a un conjunto de datos preexistente. El archivo que se está cargando debe coincidir con su esquema XDM al que se hace referencia.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Solicitud

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Respuesta

#Status 200 OK, with empty response body

Carga de archivo grande: crear archivo

Para cargar un archivo grande, debe dividirse en fragmentos más pequeños y cargarse de uno en uno.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize

Solicitud

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Respuesta

#Status 201 CREATED, with empty response body

Carga de archivo grande: cargar partes posteriores

Una vez creado el archivo, se pueden cargar todos los fragmentos posteriores realizando solicitudes repetidas al PATCH, una para cada sección del archivo.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Solicitud

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Respuesta

#Status 200 OK, with empty response

Finalización de lote de señal

Una vez cargados todos los archivos en el lote, se puede marcar el lote para su finalización. Al hacerlo, se crean las entradas de DataSetFile Catalog para los archivos completados y asociados con el lote generado anteriormente. El lote Catalog se ha marcado como correcto, lo que déclencheur los flujos descendentes para introducir los datos disponibles.

Solicitud

POST /batches/{BATCH_ID}?action=COMPLETE

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Respuesta

#Status 200 OK, with empty response

Comprobar estado del lote

Mientras se espera a que se carguen los archivos en el lote, se puede comprobar el estado del lote para ver su progreso.

Formato de API

GET /batch/{BATCH_ID}

Solicitud

curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Respuesta

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}

El campo "status" es el que muestra el estado actual del lote solicitado. Los lotes pueden tener uno de los siguientes estados:

Estados de ingesta por lotes