Programa canalizaciones

En este documento, se describe cómo programar canalizaciones de BigQuery, lo que incluye cómo programar canalizaciones y cómo inspeccionar las ejecuciones de canalizaciones programadas.

Las canalizaciones funcionan con Dataform. Cada programa de canalización se ejecuta con las credenciales de usuario de tu Cuenta de Google o una cuenta de servicio personalizada que seleccionas cuando configuras el programa.

Los cambios que realices en una canalización se guardarán automáticamente, pero solo estarán disponibles para ti y para los usuarios a los que se les otorgue el rol de administrador de Dataform en el proyecto. Para actualizar el programa con una versión nueva de la canalización, debes implementar la canalización. La implementación actualiza el programa para usar tu versión actual de la canalización. Los programas siempre ejecutan la versión implementada más reciente.

Las programaciones de las canalizaciones que contienen notebooks usan una especificación de tiempo de ejecución predeterminada. Durante una ejecución programada de una canalización que contiene notebooks, BigQuery escribe el resultado del notebook en el bucket de Cloud Storage seleccionado durante la creación de la programación.

Antes de comenzar

Antes de comenzar, crea una canalización.

Habilita la programación de canalizaciones

Para programar canalizaciones, debes otorgar el siguiente rol a las cuentas de servicio personalizadas que planeas usar para las programaciones de canalizaciones:

Usuario de cuenta de servicio (roles/iam.serviceAccountUser)

Sigue los pasos de Otorga un solo rol en una cuenta de servicio para agregar tu cuenta de servicio como principal a sí misma. En otras palabras, agrega la cuenta de servicio como principal a la misma cuenta de servicio. Luego, otorga el rol de usuario de cuenta de servicio a este principal.

Si tu canalización contiene consultas SQL, debes otorgar los siguientes roles a las cuentas de servicio personalizadas o a las Cuentas de Google que planeas usar para las programaciones de canalizaciones:

Usuario de trabajo de BigQuery (roles/bigquery.jobUser)

Sigue los pasos de Cómo otorgar un solo rol en un proyecto para otorgar el rol de usuario de trabajo de BigQuery a las cuentas de servicio personalizadas o a las Cuentas de Google en los proyectos desde los que tus canalizaciones leen datos.

Visualizador de datos de BigQuery (roles/bigquery.dataViewer)

Sigue los pasos de Cómo otorgar un solo rol en un proyecto para otorgar el rol de visualizador de datos de BigQuery a las cuentas de servicio personalizadas o a las Cuentas de Google en los proyectos desde los que tus canalizaciones leen datos.

Editor de datos de BigQuery (roles/bigquery.dataEditor)

Sigue los pasos de Cómo otorgar un solo rol en un proyecto para otorgar el rol de editor de datos de BigQuery a las cuentas de servicio personalizadas o a las Cuentas de Google en los proyectos en los que tus canalizaciones escriben datos.

Si tu canalización contiene notebooks, debes otorgar los siguientes roles a las cuentas de servicio personalizadas o a las Cuentas de Google que planeas usar para las programaciones de canalizaciones:

Usuario del ejecutor de notebooks (roles/aiplatform.notebookExecutorUser)

Sigue los pasos de Cómo otorgar un solo rol en un proyecto para otorgar el rol de usuario de ejecutor de notebooks a las cuentas de servicio personalizadas o a las Cuentas de Google en el proyecto seleccionado.

Administrador de almacenamiento (roles/storage.admin)

Sigue las instrucciones de Agrega un principal a una política a nivel del bucket para agregar las cuentas de servicio personalizadas o las Cuentas de Google como principales al bucket de Cloud Storage que planeas usar para almacenar el resultado de los notebooks ejecutados en ejecuciones programadas de canalizaciones y, luego, otorga el rol de administrador de almacenamiento a estos principales.

Además, debes otorgar los siguientes roles al agente de servicio de Dataform predeterminado:

Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator)

Sigue los pasos de Otorga acceso de creación de tokens a una cuenta de servicio para agregar el agente de servicio predeterminado de Dataform como principal a tu cuenta de servicio y otorgar el rol de creador de tokens de cuentas de servicio a esta principal.

Usuario de cuenta de servicio (roles/iam.serviceAccountUser)

Sigue los pasos paraotorgar o revocar varios roles de IAM con la consola de Cloud de Confiance para otorgar el rol de usuario de cuenta de servicio al agente de servicio de Dataform predeterminado en la cuenta de servicio personalizada.

Para habilitar el enriquecimiento de metadatos en Knowledge Catalog (versión preliminar), debes habilitar la API de Dataplex. Además, debes otorgar el siguiente rol en el proyecto o en el grupo de entrada de @bigquery a las cuentas de servicio personalizadas o a las Cuentas de Google que planeas usar para las programaciones de canalizaciones:

Rol de editor del catálogo de Dataplex (roles/dataplex.catalogEditor)

Sigue los pasos de Cómo otorgar un solo rol en un proyecto para otorgar el rol de editor del catálogo de Dataplex a las cuentas de servicio personalizadas o a las Cuentas de Google en el proyecto o el grupo de entrada @bigquery.

Para obtener más información sobre las cuentas de servicio en Dataform, consulta Acerca de las cuentas de servicio en Dataform.

Requisitos de los Controles del servicio de VPC

Si usas los Controles del servicio de VPC para proteger tus canalizaciones, debes saber que Dataform impulsa las ejecuciones programadas. Cuando configures los Controles del servicio de VPC para ejecuciones programadas, asegúrate de que se cumplan los siguientes requisitos:

• Debes configurar el dataform.restrictGitRemotes servicio de políticas de la organización.
• Dataform y BigQuery deben estar restringidos por el mismo perímetro de servicio de los Controles del servicio de VPC.
• Para permitir que los usuarios se autentiquen con las credenciales de usuario de su Cuenta de Google cuando programen o activen ejecuciones de forma manual, debes agregar sus identidades de usuario a tus reglas de entrada. Para obtener más información, consulta Actualiza las políticas de entrada y salida de un perímetro de servicio y Referencia de las reglas de entrada.

Para conocer los pasos de configuración detallados y las consideraciones de seguridad, consulta Configura los Controles del servicio de VPC para Dataform.

Roles obligatorios

Para obtener los permisos que necesitas para administrar canalizaciones, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Consulta y administra los programas:
  • Administrador de Dataform (roles/dataform.admin) en la canalización
  • Editor de Dataform (roles/dataform.editor) en el proyecto
• Visualiza y ejecuta canalizaciones:
  • Visualizador de Dataform (roles/dataform.viewer) en el proyecto
  • Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto
• Ejecutar una programación de canalización con credenciales de usuario para una Cuenta de Google: Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto
• Ejecuta una programación de canalización con una cuenta de servicio personalizada: Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio personalizada
• Administra las programaciones de canalizaciones en las carpetas de usuarios:
  • Propietario del código (roles/dataform.codeOwner) en la carpeta
  • Editor de código (roles/dataform.codeEditor) en la carpeta
• Administra las programaciones de canalizaciones en carpetas de equipo:
  • Propietario de la carpeta de equipo (roles/dataform.teamFolderOwner) en la carpeta de equipo
  • Colaborador de carpetas de equipo (roles/dataform.teamFolderContributor) en la carpeta de equipo
• Administrar canalizaciones en repositorios de Git: Usuario de OAuth de Developer Connect (roles/developerconnect.oauthUser) en el proyecto
• Habilita el enriquecimiento de metadatos: Editor de Dataplex Catalog (roles/dataplex.catalogEditor) en el proyecto o el grupo de entradas @bigquery

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para mejorar la seguridad de la programación, consulta Implementa permisos de programación mejorados.

Para obtener más información sobre la IAM de Dataform, consulta Controla el acceso con IAM.

Para obtener más información sobre los roles de las carpetas, consulta Crea y administra carpetas.

Para obtener más información sobre los roles de los repositorios de Git, consulta Administra código con repositorios de Git de BigQuery Studio.

Para usar plantillas de entorno de ejecución de notebooks de Colab cuando programes canalizaciones, necesitas el rol de usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser).

Crea una programación de canalización

También puedes usar la página Pipelines & Connections para programar una canalización de Dataform con un flujo de trabajo optimizado y específico de BigQuery. Esta función está en vista previa.

Para crear una programación de la canalización, sigue estos pasos:

Autoriza tu Cuenta de Google

Para autenticar el recurso con las credenciales de usuario de tu Cuenta de Google, debes otorgar permiso de forma manual a las canalizaciones de BigQuery para obtener el token de acceso de tu Cuenta de Google y acceder a los datos de origen en tu nombre. Puedes otorgar la aprobación manual con la interfaz del diálogo de OAuth. Si seleccionas alguna de las opciones de acceso extendido, debes otorgar acceso a esos servicios, por ejemplo, Google Drive o Knowledge Catalog.

Solo debes otorgar permiso a las canalizaciones de BigQuery una vez.

Para revocar el permiso que otorgaste, sigue estos pasos:

1. Ve a la página de tu Cuenta de Google.
2. Haz clic en BigQuery Pipelines.
3. Haga clic en Quitar acceso.

Cambiar el propietario de la programación de la canalización actualizando las credenciales también requiere aprobación manual si el nuevo propietario de la Cuenta de Google nunca antes creó una programación.

Si tu canalización contiene un notebook, también debes otorgar permiso de forma manual para que Colab Enterprise obtenga el token de acceso a tu Cuenta de Google y acceda a los datos de origen en tu nombre. Solo debes otorgar el permiso una vez. Puedes revocar este permiso en la página de la Cuenta de Google.

Programación basada en activadores

Puedes configurar canalizaciones de BigQuery para que se activen automáticamente las ejecuciones según las actualizaciones de las tablas de BigQuery especificadas. Puedes crear programas basados en activadores para automatizar las ejecuciones de la canalización en respuesta a los cambios en tus datos de BigQuery, en lugar de hacerlo en un programa fijo.

Cuando la canalización detecta cambios en la tabla o las tablas especificadas, activa una nueva ejecución del flujo de trabajo asociado. Puedes definir condiciones basadas en actualizaciones de una sola tabla, de todas las tablas de un conjunto o de cualquiera de las tablas de un conjunto.

También puedes ajustar la configuración opcional de tus programas basados en activadores para controlar el intervalo mínimo entre los activadores de la canalización. Por ejemplo, ajusta el valor de Min Execution Duration para asegurarte de que los programas basados en activadores no se activen con más frecuencia de lo previsto. También puedes ajustar el valor de Duración máxima de espera para asegurarte de que la programación basada en activadores se active una vez dentro de ese período, incluso si no se detectaron actualizaciones de la tabla.

Limitaciones

Las programaciones basadas en activadores están sujetas a las siguientes limitaciones:

• Los programas basados en activadores no son instantáneos. Cuando configuras un programa basado en activadores, la canalización verifica el estado de la tabla de BigQuery aproximadamente una vez cada 3 minutos. Este período se denomina intervalo de sondeo y puede generar una demora entre la modificación de una tabla y la activación del activador.
• Cada tabla supervisada genera llamadas a la API de BigQuery durante cada intervalo de sondeo. Supervisar una gran cantidad de tablas puede contribuir al consumo de cuota de la API de BigQuery.

Crear un activador

Para crear un activador, sigue estos pasos:

1. En la consola de Cloud de Confiance , ve a la página BigQuery.

   Ir a BigQuery

2. Para abrir tu canalización en el Visor de canalizaciones, realiza una de las siguientes acciones:

   • En el panel izquierdo, haz clic en folder Archivos, expande tu carpeta Usuario o una carpeta de equipo y, luego, selecciona una canalización.
   • En el panel izquierdo, haz clic en explore Explorador, expande tu proyecto, haz clic en Canalizaciones y, luego, selecciona una canalización.

3. En la barra de herramientas del Visualizador de canalización, haz clic en Trigger.

4. En el campo Activador, ingresa un nombre para el activador.

5. En la sección Authentication, autoriza la canalización con las credenciales de usuario de tu Cuenta de Google o una cuenta de servicio.

   • Para usar las credenciales de usuario de tu Cuenta de Google (versión preliminar), selecciona Ejecutar con mis credenciales de usuario.
   • Para usar una cuenta de servicio, selecciona Ejecutar con la cuenta de servicio seleccionada y, luego, elige una cuenta de servicio.

6. Si tu canalización contiene un notebook, en la sección Opciones de notebook, en el campo Plantilla de entorno de ejecución, selecciona una plantilla de entorno de ejecución de notebook de Colaboratory o las especificaciones de entorno de ejecución predeterminadas. Para obtener detalles sobre cómo crear una plantilla de entorno de ejecución de un notebook de Colab, consulta Crea una plantilla de entorno de ejecución.

7. Si tu canalización contiene un notebook, en la sección Opciones del notebook, en el campo Bucket de Cloud Storage, haz clic en Explorar y selecciona o crea un bucket de Cloud Storage para almacenar el resultado de los notebooks en tu canalización.

   A la cuenta de servicio seleccionada se le debe otorgar el rol de IAM de administrador de almacenamiento en el bucket seleccionado. Para obtener más información, consulta Habilita la programación de canalizaciones.

8. En Tipo de configuración, selecciona Activador (ejecución basada en eventos).

9. En el campo Search tables, agrega una o más tablas para supervisar el activador.

10. En Condición del activador, selecciona una de las siguientes opciones:

    • Esperar a que se actualicen TODAS las tablas: Activa el flujo de trabajo solo cuando se hayan actualizado todas las tablas enumeradas desde la última verificación.
    • Activar si se actualiza CUALQUIER tabla: Activa este flujo de trabajo si se actualiza alguna de las tablas enumeradas desde la última verificación.

11. (Opcional) En Duración máxima de espera, ingresa una duración para forzar la activación de un activador si no se detectan actualizaciones de la tabla dentro de este período. Admite valores entre 1 segundo y 7 días. Si no se especifica, el flujo de trabajo solo se ejecutará si se actualiza la tabla supervisada y se cumple la duración mínima de ejecución.

12. (Opcional) En Min Execution Duration, selecciona una duración para evitar que los activadores se activen con mayor frecuencia que esta duración mínima. Admite valores entre 3 minutos y 24 horas. Si no se especifica, el valor predeterminado es de 3 minutos.

13. Haz clic en Crear programación. Si seleccionaste Ejecutar con mis credenciales de usuario como método de autenticación, debes autorizar tu Cuenta de Google (versión preliminar).

Soluciona problemas de los programas basados en activadores

En esta sección, se describen los problemas comunes con los programas basados en activadores y cómo resolverlos.

Problema: No se activa el disparador

Resolución: Prueba uno de los siguientes pasos:

• Verifica que las credenciales del usuario o la cuenta de servicio tengan todos los permisos necesarios.
• Verifica que se esté modificando la tabla de BigQuery especificada.
• Comprueba que el activador no se vea afectado por el intervalo de sondeo.
• Verifica si la duración mínima de ejecución, o el valor de Min Execution Duration, impide ejecuciones más frecuentes. Puedes disminuir este valor para aumentar la frecuencia de activación del disparador.
• Verifica si la opción de condición del activador (ALL o ANY) afecta la activación del activador.
• Examina los registros de auditoría para verificar si hay errores cuando Dataform intenta llamar a la API de BigQuery para verificar el estado de la tabla supervisada.

Problema: El activador se activa con demasiada frecuencia

Resolución: Ajusta la duración mínima de ejecución o el valor de Duración mín. de ejecución. Puedes aumentar este valor para disminuir la frecuencia de activación del disparador.

Implementa una canalización

Cuando se implementa una canalización, se actualiza su programa o configuración de orquestación con la versión actual de la canalización. Las ejecuciones programadas siempre ejecutan la versión implementada más reciente de la canalización.

Implementa canalizaciones almacenadas en carpetas

Para implementar canalizaciones independientes y canalizaciones almacenadas en carpetas, sigue estos pasos:

1. En la consola de Cloud de Confiance , ve a la página BigQuery.

   Ir a BigQuery

2. Para abrir tu canalización en el Visor de canalizaciones, realiza una de las siguientes acciones:

   • En el panel izquierdo, haz clic en folder Archivos, expande tu carpeta Usuario o una carpeta de equipo y, luego, selecciona una canalización.
   • En el panel izquierdo, haz clic en explore Explorador, expande tu proyecto, haz clic en Canalizaciones y, luego, selecciona una canalización.

3. En la barra de herramientas del Visualizador de canalizaciones, haz clic en Implementar.

El programa correspondiente se actualiza con la versión actual de la canalización. La versión implementada más reciente de la canalización se ejecuta a la hora programada.

Implementa canalizaciones almacenadas en repositorios de Git

Las canalizaciones almacenadas en carpetas de Git usan implementaciones de Dataform para la organización y la programación. Las implementaciones te permiten configurar parámetros de configuración de lanzamiento, parámetros de configuración de flujo de trabajo, anulaciones de compilación y organización de varios entornos.

Para implementar una canalización almacenada en un repositorio de Git, haz lo siguiente:

1. En la consola de Cloud de Confiance , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel izquierdo, haz clic en folder Archivos.

3. En el árbol de archivos, expande la carpeta del repositorio de Git conectado y selecciona una canalización o haz clic en la carpeta del repositorio de Git si es una canalización de nivel raíz.

4. En la barra de herramientas del Visualizador de canalizaciones, haz clic en Implementar.

5. En el diálogo de implementación, establece los parámetros de configuración de lanzamiento, los parámetros de configuración de flujo de trabajo y la configuración de ejecución.

6. Haz clic en Implementar.

Para obtener más información sobre la configuración de implementaciones, versiones y flujos de trabajo, consulta Implementaciones de Dataform.

Cómo inhabilitar un programa

Para pausar las ejecuciones programadas de una canalización seleccionada sin borrar el programa, puedes inhabilitarlo.

Para inhabilitar una programación para un canal seleccionado, sigue estos pasos:

Cómo habilitar un programa

Para reanudar las ejecuciones programadas de una programación de canalización inhabilitada, sigue estos pasos:

Ejecuta manualmente una canalización implementada

Cuando ejecutas manualmente una canalización implementada en un programa seleccionado, BigQuery ejecuta la canalización implementada una vez, independientemente del programa.

Para ejecutar manualmente una canalización implementada, sigue estos pasos:

1. En la consola de Cloud de Confiance , ve a la página Scheduling.

   Ir a Programación

2. Haz clic en el nombre de la programación de la canalización seleccionada.

3. En la página Detalles de la programación, haz clic en Ejecutar.

Visualiza todos los programas de canalización

Para ver todas las programaciones de canalizaciones en tu proyecto Cloud de Confiance , sigue estos pasos:

1. En la consola de Cloud de Confiance , ve a la página Scheduling.

   Ir a Programación

2. Opcional: Para mostrar columnas adicionales con detalles de la programación de la canalización, haz clic en view_column Opciones de visualización de columnas, selecciona las columnas y, luego, haz clic en Aceptar.

Visualiza los detalles de la programación de la canalización

Para ver los detalles de una programación de canalización seleccionada, sigue estos pasos:

Cómo ver las ejecuciones programadas anteriores

Para ver las ejecuciones anteriores de una programación de canalización seleccionada, sigue estos pasos:

Cómo editar una programación de canalización

Para editar la programación de una canalización, sigue estos pasos:

Borra una programación de canalización

Para borrar de forma permanente una programación de la canalización, sigue estos pasos:

1. En la consola de Cloud de Confiance , ve a la página Scheduling.

   Ir a Programación

2. Elige una de las siguientes opciones:

   • Haz clic en el nombre del programa de canalización seleccionado y, luego, en Borrar en la página Detalles del programa.

   • En la fila que contiene la programación de la canalización seleccionada, haz clic en more_vert Ver acciones en la columna Acciones y, luego, en Borrar.

3. En el cuadro de diálogo que aparece, haz clic en Borrar.

¿Qué sigue?

• Obtén más información sobre las canalizaciones en BigQuery.
• Obtén más información para crear canalizaciones.
• Obtén más información para administrar canalizaciones.
• Obtén información para administrar código con repositorios de Git de BigQuery Studio.
• Obtén más información para organizar activos de código con carpetas.
• Obtén más información sobre las implementaciones de Dataform.