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.

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.