Ingesta parcial por lotes

La ingesta parcial por lotes es la capacidad de ingerir datos que contengan errores, hasta un determinado umbral. Con esta capacidad, los usuarios pueden introducir correctamente todos sus datos correctos en Adobe Experience Platform, mientras que todos sus datos incorrectos se agrupan por separado, junto con los detalles de por qué no es válido.

Este documento proporciona un tutorial para administrar la ingesta parcial por lotes.

Introducción

Este tutorial requiere un conocimiento práctico de los distintos servicios de Adobe Experience Platform implicados en la ingesta parcial por lotes. Antes de comenzar este tutorial, revise la documentación de los siguientes servicios:

Las secciones siguientes proporcionan información adicional que necesitará saber para poder realizar llamadas exitosas a Experience Platform API.

Lectura de llamadas de API de muestra

Esta guía proporciona ejemplos de llamadas de API para mostrar cómo dar formato a las solicitudes. Estas incluyen rutas, encabezados obligatorios y cargas de solicitud con el formato correcto. También se proporciona el JSON de muestra devuelto en las respuestas de la API. Para obtener información sobre las convenciones utilizadas en la documentación de las llamadas de API de muestra, consulte la sección sobre cómo leer llamadas de API de ejemplo en la guía de solución de problemas de Experience Platform.

Recopilación de valores para los encabezados obligatorios

Para realizar llamadas a las API de Experience Platform, primero debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados obligatorios en todas las llamadas de API de Experience Platform, como se muestra a continuación:

Todos los recursos de Experience Platform están aislados en zonas protegidas virtuales específicas. Todas las solicitudes a las API de Experience Platform requieren un encabezado que especifique el nombre de la zona protegida en la que se realizará la operación:

Habilite un lote para la ingesta parcial por lotes en la API enable-api

Puede crear un nuevo lote con la ingesta parcial habilitada.

Para crear un nuevo lote, siga los pasos de la guía para desarrolladores de ingesta por lotes. Una vez que llegue al paso Create batch, agregue el siguiente campo dentro del cuerpo de la solicitud:

{
    "enableErrorDiagnostics": true,
    "partialIngestionPercent": 5
}

Habilitar un lote para la ingesta parcial por lotes en la IU enable-ui

Para habilitar un lote para la ingesta parcial a través de la interfaz de usuario Experience Platform, puede crear un nuevo lote a través de conexiones de origen, crear un nuevo lote en un conjunto de datos existente o crear un nuevo lote a través de "Map CSV to XDM flow".

Crear una nueva conexión de origen new-source

Para crear una nueva conexión de origen, siga los pasos indicados en Resumen de orígenes. Una vez que llegue al paso Dataflow detail, tome nota de los campos Partial ingestion y Error diagnostics.

La opción Partial ingestion le permite habilitar o deshabilitar el uso de la ingesta parcial por lotes.

La opción Error diagnostics solo aparece cuando la opción Partial ingestion está desactivada. Esta característica permite que Experience Platform genere mensajes de error detallados acerca de los lotes ingeridos. Si se activa la opción Partial ingestion, se aplican automáticamente los diagnósticos de error mejorados.

Error threshold le permite establecer el porcentaje de errores aceptables antes de que falle todo el lote. De forma predeterminada, este valor se establece en 5%.

Usar un conjunto de datos existente existing-dataset

Para utilizar un conjunto de datos existente, comience seleccionando un conjunto de datos. La barra lateral de la derecha se rellena con información sobre el conjunto de datos.

La opción Partial ingestion le permite habilitar o deshabilitar el uso de la ingesta parcial por lotes.

La opción Error diagnostics solo aparece cuando la opción Partial ingestion está desactivada. Esta característica permite que Experience Platform genere mensajes de error detallados acerca de los lotes ingeridos. Si se activa la opción Partial ingestion, se aplican automáticamente los diagnósticos de error mejorados.

Error threshold le permite establecer el porcentaje de errores aceptables antes de que falle todo el lote. De forma predeterminada, este valor se establece en 5%.

Ahora puede cargar datos usando el botón Agregar datos y se incorporarán mediante la ingesta parcial.

Usar el flujo "Map CSV to XDM schema" map-flow

Para usar el flujo "Map CSV to XDM schema", siga los pasos indicados en el tutorial Asignar un archivo CSV. Una vez que llegue al paso Add data, tome nota de los campos Partial ingestion y Error diagnostics.

La opción Partial ingestion le permite habilitar o deshabilitar el uso de la ingesta parcial por lotes.

La opción Error diagnostics solo aparece cuando la opción Partial ingestion está desactivada. Esta característica permite que Experience Platform genere mensajes de error detallados acerca de los lotes ingeridos. Si se activa la opción Partial ingestion, se aplican automáticamente los diagnósticos de error mejorados.

Error threshold le permite establecer el porcentaje de errores aceptables antes de que falle todo el lote. De forma predeterminada, este valor se establece en 5%.

Habilitar los diagnósticos de ingesta parcial y error para un flujo de datos existente

Si se creó un flujo de datos en Experience Platform sin habilitar la ingesta parcial o los diagnósticos de error, aún se pueden habilitar estas funciones sin volver a crear el flujo. Al habilitar la ingesta parcial y los sólidos diagnósticos de error, puede mejorar en gran medida la fiabilidad y la facilidad de la resolución de problemas en los flujos de trabajo de ingesta de datos. Lea las secciones siguientes para aprender a habilitar la ingesta parcial y los diagnósticos de error para un flujo de datos existente mediante la API Flow Service.

De forma predeterminada, es posible que los flujos de datos no tengan habilitados los diagnósticos de ingesta parcial o error. Estas funciones son útiles para identificar y aislar problemas durante la ingesta de datos. Con la API Flow Service, puede recuperar la configuración actual del flujo de datos y aplicar los cambios necesarios mediante una petición PATCH.

Siga los pasos a continuación para habilitar la ingesta parcial y los diagnósticos de error para un flujo de datos existente.

Recuperar detalles de flujo

Para recuperar las configuraciones del flujo de datos, realice una petición GET al extremo /flows/{FLOW_ID} y proporcione el ID del flujo de datos. Para obtener más información sobre cómo recuperar detalles del flujo de datos, consulte Actualizar flujos de datos mediante la guía de Flow Service API.

Asegúrese de guardar el valor del campo etag devuelto en la respuesta. Esto es necesario para que la solicitud de actualización garantice la coherencia de la versión.

Actualizar configuración de flujo

A continuación, realice una petición PATCH al extremo /flows/ y proporcione el ID del flujo de datos para el que desea habilitar la ingesta parcial y los diagnósticos de error.

Formato de API

PATCH /flows/{FLOW_ID}

Solicitud

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
    -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}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
        {
            "op": "add",
            "path": "/options",
            "value": {
                "partialIngestionPercent": "10"
            }
        },
        {
            "op": "add",
            "path": "/options/errorDiagnosticsEnabled",
            "value": true
        }
    ]'

Respuesta

Una respuesta correcta devuelve id del flujo de datos y un etag actualizado.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"2c000802-0000-0200-0000-613976440000\""
}

Verificar la actualización

Una vez completado PATCH, realice una petición GET y recupere el flujo de datos para comprobar que los cambios se hayan completado correctamente.

Formato de API

GET /flows/{FLOW_ID}

Solicitud

La siguiente solicitud recupera información actualizada sobre el ID de flujo.

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
  -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 respuesta correcta devuelve los detalles del flujo de datos, confirmando que los diagnósticos de ingesta parcial y error ahora están habilitados en la sección options.

"options": {
    "partialIngestionPercent": 10,
    "errorDiagnosticsEnabled": true
}

Próximos pasos next-steps

En este tutorial se explica cómo crear o modificar un conjunto de datos para habilitar la ingesta parcial por lotes. Para obtener más información sobre la ingesta por lotes, lea la guía para desarrolladores de ingesta por lotes.

Para obtener información sobre la supervisión de los errores de ingesta parcial, lea la guía de diagnóstico de errores de ingesta por lotes.