E/S administrada de Dataflow

La E/S administrada permite que Dataflow administre conectores de E/S específicos que se usan en las canalizaciones de Apache Beam. La E/S administrada simplifica la administración de las canalizaciones que se integran con las fuentes y los receptores compatibles.

La E/S administrada consta de dos componentes que funcionan juntos:

  • Es una transformación de Apache Beam que proporciona una API común para crear conectores de E/S (fuentes y receptores).

  • Un servicio de Dataflow que administra estos conectores de E/S en tu nombre, incluida la capacidad de actualizarlos de forma independiente de la versión de Apache Beam.

Entre las ventajas de la E/S administrada, se incluyen las siguientes:

  • Actualizaciones automáticas. Dataflow actualiza automáticamente los conectores de E/S administrados en tu canalización. Esto significa que tu canalización recibe correcciones de seguridad, mejoras de rendimiento y correcciones de errores para estos conectores, sin necesidad de realizar cambios en el código. Para obtener más información, consulta Actualizaciones automáticas.

  • API coherente. Tradicionalmente, los conectores de E/S en Apache Beam tienen APIs distintas, y cada conector se configura de una manera diferente. La E/S administrada proporciona una sola API de configuración que usa propiedades de par clave-valor, lo que genera un código de canalización más simple y coherente. Para obtener más información, consulta la API de Configuration.

Requisitos

  • Los siguientes SDKs admiten la E/S administrada:

    • SDK de Apache Beam para Java, versión 2.58.0 o posterior.
    • SDK de Apache Beam para Python, versión 2.61.0 o posterior.
  • El servicio de backend requiere Dataflow Runner v2. Si Runner v2 no está habilitado, tu canalización se seguirá ejecutando, pero no obtendrá los beneficios del servicio de E/S administrado.

Actualizaciones automáticas

Las canalizaciones de Dataflow con conectores de E/S administrados usan automáticamente la versión confiable más reciente del conector. Las actualizaciones automáticas se producen en los siguientes puntos del ciclo de vida del trabajo:

  • Envío de trabajos. Cuando envías un trabajo por lotes o de transmisión, Dataflow usa la versión más reciente del conector de E/S administrado que se probó y funciona bien.

  • Actualizaciones progresivas. En el caso de los trabajos de transmisión, Dataflow actualiza tus conectores de E/S administrada en las canalizaciones en ejecución a medida que haya nuevas versiones disponibles. No tienes que preocuparte por actualizar de forma manual el conector ni la versión de Apache Beam de tu canalización.

    De forma predeterminada, las actualizaciones progresivas se realizan en un período de 30 días, es decir, aproximadamente cada 30 días. Puedes ajustar el período o inhabilitar las actualizaciones progresivas por trabajo. Para obtener más información, consulta Configura el período de actualización progresiva.

    Una semana antes de la actualización, Dataflow escribe un mensaje de notificación en los registros de mensajes del trabajo.

  • Trabajos de reemplazo. En el caso de los trabajos de transmisión, Dataflow busca actualizaciones cada vez que inicias un trabajo de reemplazo y usa automáticamente la versión más reciente que se sabe que funciona. Dataflow realiza esta verificación incluso si no cambias ningún código en el trabajo de reemplazo.

En el siguiente diagrama, se muestra el proceso de actualización. El usuario crea una canalización de Apache Beam con la versión X del SDK. Dataflow actualiza la versión de E/S administrada a la versión compatible más reciente. La actualización se produce cuando el usuario envía el trabajo, después de la ventana de actualización progresiva o cuando el usuario envía un trabajo de reemplazo.

Diagrama que muestra el proceso de actualización de la E/S administrada.

El proceso de actualización agrega alrededor de dos minutos al tiempo de inicio del primer trabajo (por proyecto) que usa E/S administrada y puede ser de aproximadamente medio minuto para los trabajos posteriores. Para las actualizaciones progresivas, el servicio de Dataflow inicia un trabajo de reemplazo. Esto puede provocar un tiempo de inactividad temporal para tu canalización, ya que el grupo de trabajadores existente se cierra y se inicia uno nuevo. Para verificar el estado de las operaciones de E/S administradas, busca entradas de registro que incluyan la cadena "Managed Transform(s)".

Establece el período de actualización progresiva

Para especificar el período de actualización de un trabajo de transmisión de Dataflow, configura la opción de servicio managed_transforms_rolling_upgrade_window igual a la cantidad de días. El valor debe estar entre 10 y 90 días (ambas cifras incluidas).

Java

--dataflowServiceOptions=managed_transforms_rolling_upgrade_window=DAYS

Python

--dataflow_service_options=managed_transforms_rolling_upgrade_window=DAYS

gcloud

Usa el comando gcloud dataflow jobs run con la opción additional-experiments. Si usas una plantilla de Flex que usa E/S administrada, usa el comando gcloud dataflow flex-template run.

--additional-experiments=managed_transforms_rolling_upgrade_window=DAYS

Para inhabilitar las actualizaciones progresivas, configura la opción de servicio managed_transforms_rolling_upgrade_window en never. Aún puedes activar una actualización si inicias un trabajo de reemplazo.

Java

--dataflowServiceOptions=managed_transforms_rolling_upgrade_window=never

Python

--dataflow_service_options=managed_transforms_rolling_upgrade_window=never

Go

--dataflow_service_options=managed_transforms_rolling_upgrade_window=never

gcloud

Usa el comando gcloud dataflow jobs run con la opción additional-experiments. Si usas plantillas de Flex, usa el comando gcloud dataflow flex-template run.

--additional-experiments=managed_transforms_rolling_upgrade_window=never

API de configuración

La E/S administrada es una transformación de Apache Beam lista para usar que proporciona una API coherente para configurar fuentes y receptores.

Java

Para crear cualquier fuente o receptor compatible con Managed I/O, usa la clase Managed. Especifica qué fuente o receptor se debe crear una instancia, y pasa un conjunto de parámetros de configuración, similar al siguiente:

Map config = ImmutableMap.<String, Object>builder()
    .put("config1", "abc")
    .put("config2", 1);

pipeline.apply(Managed.read(/*Which source to read*/).withConfig(config))
    .getSinglePCollection();

También puedes pasar parámetros de configuración como un archivo YAML. Para ver un ejemplo de código completo, consulta Lee desde Apache Iceberg.

Python

Importa el módulo apache_beam.transforms.managed y llama al método managed.Read o managed.Write. Especifica qué fuente o receptor se debe instanciar y pasa un conjunto de parámetros de configuración, similar a lo siguiente:

pipeline
| beam.managed.Read(
    beam.managed.SOURCE, # Example: beam.managed.KAFKA
    config={
      "config1": "abc",
      "config2": 1
    }
)

También puedes pasar parámetros de configuración como un archivo YAML. Para ver un ejemplo de código completo, consulta Lee desde Apache Kafka.

Destinos dinámicos

Para algunos receptores, el conector de E/S administrado puede seleccionar de forma dinámica un destino en función de los valores de los campos de los registros entrantes.

Para usar destinos dinámicos, proporciona una cadena de plantilla para el destino. La cadena de plantilla puede incluir nombres de campos entre llaves, como "tables.{field1}". En el entorno de ejecución, el conector sustituye el valor del campo para cada registro entrante, a fin de determinar el destino de ese registro.

Por ejemplo, supongamos que tus datos tienen un campo llamado airport. Puedes establecer el destino en "flights.{airport}". Si airport=SFO, el registro se escribe en flights.SFO. Para los campos anidados, usa la notación de puntos. Por ejemplo: {top.middle.nested}.

Para ver un código de ejemplo que muestra cómo usar destinos dinámicos, consulta Escribe con destinos dinámicos.

Filtros

Es posible que quieras filtrar ciertos campos antes de que se escriban en la tabla de destino. En el caso de los receptores que admiten destinos dinámicos, puedes usar el parámetro drop, keep o only para este propósito. Estos parámetros te permiten incluir metadatos de destino en los registros de entrada, sin escribir los metadatos en el destino.

Puedes establecer como máximo uno de estos parámetros para un receptor determinado.

Parámetro de configuración Tipo de datos Descripción
drop lista de cadenas Es una lista de nombres de campos que se deben descartar antes de escribir en el destino.
keep lista de cadenas Es una lista de nombres de campos que se conservarán cuando se escriba en el destino. Se descartan los demás campos.
only cadena Es el nombre de exactamente un campo que se usará como el registro de nivel superior que se escribirá en el destino. Se descartan todos los demás campos. Este campo debe ser del tipo fila.

Fuentes y receptores compatibles

La E/S administrada admite las siguientes fuentes y receptores.

Para obtener más información, consulta Conectores de E/S administrados en la documentación de Apache Beam.