Administra código con repositorios de Git de BigQuery Studio

Los repositorios de Git de BigQuery Studio te permiten control de versión de las secuencias de comandos de SQL, los notebooks y otros recursos de código directamente en el navegador de archivos de BigQuery Studio. Puedes clonar repositorios de Git remotos, administrar ramas y realizar operaciones de Git sin salir de la consola de Google Cloud .

En comparación con los repositorios clásicos, esta integración proporciona una experiencia optimizada basada en carpetas en la carpeta raíz del usuario en el panel izquierdo. Puedes interactuar con tus recursos de código como archivos y directorios estándar mientras mantienes una conexión con un repositorio de Git remoto.

Limitaciones

  • Los repositorios de Git de BigQuery Studio están restringidos al contexto de la carpeta raíz del usuario y están destinados para uso privado. No compartas estos repositorios con otros usuarios. Aunque estos repositorios aparecen en la carpeta raíz de usuario, que es una representación virtual de tus recursos en el proyecto, técnicamente se crean a nivel del proyecto.
  • Las operaciones del sistema de archivos dentro de la ubicación de activación consumen cuota de Dataform.
  • Los repositorios con una gran cantidad de archivos, archivos de gran tamaño, muchas ramas o un historial de confirmaciones profundo y complejo tardan más en clonarse. La operación de clonación puede exceder el tiempo de espera de la operación, lo que impide que el repositorio se cree correctamente. Para reducir el tiempo de clonación de los repositorios con historiales de confirmaciones profundos, puedes crear una clonación superficial. Puedes recuperar más confirmaciones más adelante según sea necesario.
  • El tamaño de los archivos de notebook almacenados en una activación de repositorio de Git de BigQuery Studio no puede superar los 30 MB. Si tus archivos superan los 30 MB, guárdalos en el almacenamiento local del entorno de ejecución de Colab, fuera de la ubicación activada.

  • Cuando realizas cambios en un repositorio de Git fuera de la activación, por ejemplo, editando o cambiando el nombre de los archivos en el panel izquierdo, esos cambios pueden tardar hasta 60 segundos en hacerse visibles dentro de la activación en el entorno de ejecución de tu notebook. Para ajustar esta duración, pasa el parámetro CACHE_TTL_SECONDS al constructor:

      FuseWidget(CACHE_TTL_SECONDS=NUMBER)

    Reemplaza NUMBER por la cantidad de segundos que la caché debe permanecer válida. Disminuir este valor aumenta la frecuencia de sincronización y consume la cuota de Dataform más rápido.

Antes de comenzar

Habilita la API de Developer Connect en tu proyecto de Google Cloud .

Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para administrar código con repositorios de Git de BigQuery Studio, pídele a tu administrador que te otorgue el rol de IAM de usuario de OAuth de Developer Connect (roles/developerconnect.oauthUser) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para administrar código con repositorios de Git de BigQuery Studio. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para administrar el código con los repositorios de Git de BigQuery Studio:

  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • developerconnect.operations.list
  • developerconnect.operations.get
  • developerconnect.locations.list
  • developerconnect.locations.get
  • developerconnect.users.startOAuth
  • developerconnect.users.finishOAuth
  • developerconnect.users.fetchAccessToken
  • developerconnect.users.getSelf
  • developerconnect.users.deleteSelf
  • developerconnect.accountConnectors.get
  • developerconnect.accountConnectors.list
  • developerconnect.accountConnectors.gitProxyUse
  • developerconnect.accountConnectors.httpProxyUse
  • developerconnect.accountConnectors.gitProxyRead
  • developerconnect.accountConnectors.gitProxyWrite
  • developerconnect.accountConnectors.httpProxyRead
  • developerconnect.accountConnectors.httpProxyWrite
  • developerconnect.accountConnectors.fetchUserRepositories

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Consideraciones de seguridad para los repositorios

Debido a que los recursos de código en BigQuery se basan en Dataform, debes tener en cuenta las siguientes implicaciones de seguridad para los usuarios con acceso a estos recursos:

  • La visibilidad de los recursos de código se rige por los permisos de Dataform a nivel del proyecto. Los usuarios con el permiso dataform.repositories.list, que se incluye en los roles estándar de BigQuery, como Usuario de trabajos de BigQuery, Usuario de BigQuery Studio y Usuario de BigQuery, pueden ver todos los recursos de código en el panel Explorador del proyecto de Google Cloud , independientemente de si crearon estos recursos o si se compartieron con ellos. Para restringir la visibilidad, puedes crear roles personalizados que excluyan el permiso dataform.repositories.list.
  • Los usuarios que pueden editar estos recursos pueden acceder a cualquier secreto compartido con el agente de servicio de Dataform. Para proteger tus credenciales, restringe el acceso de creación y edición a los usuarios de confianza, y limita los secretos a los que puede acceder el agente de servicio de Dataform. Para obtener más información, consulta Acceso a secretos durante la instalación de paquetes.

Si deseas obtener más información, consulta Consideraciones de seguridad para los permisos de Dataform.

Recomendaciones de seguridad para los permisos de Developer Connect

Los repositorios de Git de BigQuery Studio usan Developer Connect para conectarse a repositorios remotos. Además, los roles predefinidos de BigQuery y Dataform incluyen permisos de Developer Connect. Debido a estas funciones de seguridad, te recomendamos que hagas lo siguiente:

  • Usa roles personalizados para aplicar la separación de funciones: Si tu organización requiere una separación estricta entre las tareas de análisis de datos y la administración del código fuente, implementa roles personalizados que omitan los permisos de Developer Connect. Los roles predefinidos, como Usuario de BigQuery (roles/bigquery.user) y Usuario de BigQuery Studio (roles/bigquery.studioUser), incluyen permisos de Developer Connect, que permiten que los usuarios con estos roles inicien flujos de OAuth y dirijan el tráfico de Git a través de un proxy.
  • Aplica protecciones con políticas de denegación de IAM: Aplica políticas de denegación a nivel de la organización para evitar acciones sensibles en grupos de análisis amplios. Considera denegar el permiso developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken para evitar la extracción de tokens y el permiso developerconnect.googleapis.com/accountConnectors.gitProxyWrite para evitar el acceso de escritura no deseado a los repositorios. Los roles administrativos, como Administrador de BigQuery (roles/bigquery.admin) y Administrador de BigQuery Studio (roles/bigquery.studioAdmin), incluyen permisos de descriptor de acceso de tokens que permiten a las principales recuperar tokens activos de administración de código fuente (SCM) de terceros en texto simple, como los tokens de instalación de la app de GitHub.
  • Aísla los proyectos de CI/CD sensibles: Mantén las canalizaciones de CI/CD sensibles, como Cloud Build o Vertex AI, en proyectos de Google Cloud dedicados que estén separados de los entornos de análisis de datos generales. Debido a que los permisos de Developer Connect se limitan a nivel del proyecto, un usuario de BigQuery en un proyecto compartido de varios usuarios puede enumerar y usar cualquier conexión de Developer Connect en ese proyecto para enviar solicitudes de Git mediante proxy, lo que podría otorgar acceso a los repositorios configurados para la automatización de la infraestructura o de CI/CD.
  • Restringe el acceso a los recursos con las condiciones de IAM: Adjunta condiciones de IAM a las vinculaciones de roles para restringir los permisos de Developer Connect a recursos específicos. Puedes limitar el acceso según los prefijos de nombre de los recursos o restringir el acceso a recursos específicos de Connection y GitRepositoryLink. Esto garantiza que los usuarios solo puedan interactuar con las conexiones de Developer Connect que están destinadas a sus flujos de trabajo.
  • Protege los metadatos sensibles en los nombres de los recursos: No incorpores credenciales sensibles, nombres internos de proyectos ni información confidencial en los nombres de los repositorios, los nombres de las ramas ni los IDs de conexión. Los permisos necesarios para enumerar estos recursos (developerconnect.connections.list y developerconnect.accountConnectors.list) se otorgan a los roles estándar de BigQuery. Cualquier persona con acceso básico al proyecto puede enumerar estos recursos y descubrir metadatos sensibles.

Crea un repositorio de Git de BigQuery Studio

Cuando crees un repositorio de Git, ten en cuenta estos requisitos:

  • La conexión de un repositorio de Git remoto a un repositorio de Git puede fallar si el repositorio remoto no está abierto a la Internet pública, por ejemplo, si está detrás de un firewall. En este caso, agrega los rangos de direcciones IP de salida de Dataform obligatorios a tus reglas de firewall para habilitar las conexiones a repositorios remotos protegidos.
  • Para crear un repositorio de Git conectado a un repositorio de Git remoto que no esté incluido en la lista de entidades permitidas de la política de la organización de dataform.restrictGitRemotes, primero agrega el repositorio de Git remoto a la lista de allowedValues en la política y, luego, crea el repositorio de Git. Para obtener más información, consulta Restringe los repositorios remotos.

Para crear un repositorio de Git, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Archivos para abrir el navegador de archivos.

    Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

  3. Junto al nodo raíz del usuario, haz clic en Ver acciones > Crear > Repositorio de Git.

  4. Ingresa la URL de tu repositorio de Git remoto.

  5. BigQuery Studio detecta si hay un conector de cuenta de Developer Connect existente disponible. Tienes las siguientes opciones:

  6. Opcional: Para crear un repositorio de clonación superficial con un historial de confirmaciones limitado, haz clic en Opciones avanzadas y, luego, selecciona la casilla de verificación Clonación superficial.

    1. En el campo Profundidad, ingresa la cantidad de confirmaciones que se recuperarán en el historial de confirmaciones limitado.

  7. Haz clic en Conectar.

Edita un archivo

Para editar un archivo, haz clic en un nodo de archivo, como una secuencia de comandos de SQL o un notebook, para abrir el archivo en una nueva pestaña del editor.

Los cambios que hagas se guardarán automáticamente.

Administrar archivos

Puedes realizar tareas de administración estándar con el menú de acciones asociado a cada elemento. Para acceder a estas opciones, haz clic en Ver acciones junto a cualquier directorio o archivo.

A nivel del directorio, puedes realizar las siguientes tareas:

  • Crear en el repositorio: Crea recursos de código nuevos, como consultas en SQL, notebooks, lienzos de datos, preparaciones de datos, archivos o subdirectorios.
  • Subir al repositorio: Importa archivos existentes desde tu máquina local al directorio seleccionado.
  • Cambiar nombre: Cambia el nombre del directorio.
  • Mover: Reubica el directorio. Solo puedes mover un directorio a otra ubicación dentro del mismo repositorio de Git. Para obtener más información, consulta Mueve un directorio o archivo.
  • Borrar: Quita de forma permanente el directorio y todo su contenido de tu espacio de trabajo local. Para obtener más información, consulta Borra un directorio o archivo.

A nivel de archivo, puedes realizar las siguientes tareas:

  • Abrir o Abrir en: Visualiza el archivo en el editor predeterminado o en una aplicación específica, por ejemplo, un entorno de notebook específico.
  • Cambiar nombre: Cambia el nombre del archivo.
  • Copiar: Crea un duplicado del archivo. Solo puedes copiar archivos en directorios dentro del mismo repositorio de Git. Para obtener más información, consulta Cómo copiar un archivo.
  • Mover: Reubica el archivo en otro directorio dentro del mismo repositorio de Git. Para obtener más información, consulta Mueve un directorio o archivo.
  • Descargar: Guarda una copia del archivo en tu máquina local.
  • Borrar: Quita el archivo de tu espacio de trabajo. Para obtener más información, consulta Borra un directorio o archivo.

Mover un directorio o archivo

Para mover un directorio o archivo en un repositorio de Git de BigQuery Studio, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Archivos para abrir el navegador de archivos.

  3. Según la cantidad de recursos que quieras mover, realiza una de las siguientes acciones:

    • Para mover un solo recurso, en el navegador de archivos, selecciona el directorio o el archivo que deseas mover y, luego, haz clic en Ver acciones > Mover.
    • Para mover varios recursos, en la vista de carpetas, selecciona la casilla de verificación junto a cada recurso que quieras mover y, luego, haz clic en Mover.

  4. En el diálogo para mover recursos, selecciona el directorio de destino dentro del mismo repositorio de Git. Solo puedes mover recursos a ubicaciones dentro del mismo repositorio de Git.

  5. Haz clic en Mover.

Cómo copiar un archivo

Para copiar un archivo en un repositorio de Git de BigQuery Studio, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Archivos para abrir el navegador de archivos.

  3. Selecciona el archivo que quieras copiar.

  4. Haz clic en Ver acciones > Copiar.

  5. En el diálogo de copia de recursos, selecciona el directorio de destino dentro del mismo repositorio de Git. Solo puedes copiar archivos en ubicaciones dentro del mismo repositorio de Git.

  6. Haz clic en Copiar.

Borra un directorio o un archivo

Para borrar un directorio o archivo en un repositorio de Git de BigQuery Studio, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Archivos para abrir el navegador de archivos.

  3. Según la cantidad de recursos que quieras borrar, realiza una de las siguientes acciones:

    • Para borrar un solo recurso, en el navegador de archivos, selecciona el directorio o el archivo que deseas borrar y, luego, haz clic en Ver acciones > Borrar.
    • Para borrar varios recursos, en la vista de carpetas, selecciona la casilla de verificación junto a cada recurso que quieras borrar y, luego, haz clic en Borrar.

  4. En el diálogo de confirmación de eliminación, haz clic en Borrar.

Confirma y envía los cambios

Para sincronizar tus ediciones locales con tu repositorio remoto, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Control de código fuente.

  3. Opcional: Coloca el cursor sobre un archivo modificado y haz clic en Show diff para ver una comparación línea por línea entre tu versión local y la última versión confirmada.

  4. En el campo Mensaje de confirmación, ingresa una descripción de los cambios.

  5. Haz clic en Confirmar. Los cambios se guardan en el historial de Git de tu rama local.

  6. Haz clic en Push to remote. Tus cambios se sincronizan con el repositorio remoto.

Cómo revisar una rama nueva

Puedes administrar las ramas locales y crear una nueva en función de una rama de seguimiento local o remota existente.

En el panel Control de código fuente, en la sección Ramas, puedes ver tus ramas locales confirmadas. La etiqueta CURRENT indica tu rama activa, y la etiqueta DEFAULT indica la rama predeterminada del repositorio.

Para revisar una rama nueva, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Control de código fuente.

  3. En la sección Ramas, junto a Ramas, haz clic en Acciones > Confirmar nueva rama.

  4. En el menú Rama de origen, selecciona la rama en la que deseas basar tu rama nueva, por ejemplo, origin/main.

  5. En el campo Nombre de la rama, ingresa un nombre para la rama nueva.

  6. Haz clic en Cambiar de rama. BigQuery Studio primero verifica la rama de origen. Si el nombre de la rama proporcionado indica una rama nueva, se crea en función de esa fuente. La rama nueva se convierte en la rama activa, y el contenido de tu repositorio de Git se actualiza automáticamente para reflejar el estado de la rama que se extrajo.

Para cambiar a una rama existente, haz lo siguiente:

  1. En el panel Control de código fuente, expande la sección Ramas.
  2. Junto a la rama a la que quieres cambiar, haz clic en Acciones > Cambiar a BRANCH_NAME.

Ver historial de confirmaciones

Puedes ver el historial de confirmaciones de tu rama activa. Si tu repositorio se creó como una clonación superficial, el panel Historial de confirmaciones de la rama muestra un banner informativo que indica que el repositorio tiene un historial de confirmaciones limitado. Puedes expandir tu historial local recuperando más confirmaciones.

Para ver el historial de confirmaciones, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Control de código fuente.

  3. Junto al botón de acción principal de control de versión, haz clic en la flecha desplegable y, luego, en Ver historial de confirmaciones.

    Se abrirá el panel Historial de confirmaciones de la rama, en el que se mostrará el historial de confirmaciones de tu rama activa.

  4. Opcional: Para recuperar confirmaciones del repositorio remoto, realiza una de las siguientes acciones:

    • Junto al botón de acción principal del control de versión, haz clic en el menú desplegable de flecha y, luego, en Fetch from remote.
    • En el panel Historial de confirmaciones de la rama, haz clic en Recuperar.

    En el caso de los repositorios de clonación superficial, en el cuadro de diálogo Recuperar (clonación superficial), en el campo Confirmaciones adicionales para recuperar, ingresa la cantidad de confirmaciones adicionales que se recuperarán del historial del repositorio.

    Si ingresas 0, no se recuperan confirmaciones históricas adicionales, pero BigQuery Studio realiza una recuperación estándar para sincronizar las referencias y los metadatos remotos.

  5. Haz clic en Recuperar.

    Puedes repetir la recuperación según sea necesario hasta que se recuperen todas las confirmaciones.

Borra un repositorio de Git

Si borras un repositorio de Git de BigQuery Studio, se quitará el repositorio y todo su contenido de tu entorno de BigQuery Studio.

Para borrar un repositorio de Git, haz lo siguiente:

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

    Ir a BigQuery

  2. Borra el repositorio con uno de los siguientes métodos:

    • Para borrar el repositorio del navegador de archivos, en el panel izquierdo, haz clic en Archivos. Junto al repositorio de Git que quieres borrar, haz clic en Ver acciones > Borrar.
    • Para borrar el repositorio del panel de control, en el encabezado del panel Control de código fuente, haz clic en Opciones de control de código fuente > Borrar REPOSITORY_NAME.

  3. En el diálogo de confirmación de eliminación, haz clic en Borrar.

Accede a los archivos de notebook en una activación de repositorio de Git

Cuando accedes a un notebook desde un repositorio de Git de BigQuery Studio, puedes activar el repositorio de Git del host en el entorno de ejecución de tu notebook. Una activación es una conexión que hace que tu repositorio de Git remoto aparezca como si fuera un repositorio local en el entorno de ejecución de tu notebook. Esto permite que tu notebook acceda, lea y escriba directamente en otros archivos y secuencias de comandos de consulta dentro del mismo repositorio.

Activa el repositorio de Git

Para activar el repositorio de Git, ejecuta el siguiente código de Python en tu notebook:

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Cuando la notebook se conecta al soporte, se producen los siguientes cambios:

  • El directorio de trabajo actual de la sesión del notebook se actualiza para reflejar su ruta de acceso relativa dentro del repositorio de Git. Esto garantiza que el acceso a archivos basado en rutas de acceso funcione automáticamente.
  • La ruta de acceso del repositorio de Git en el entorno de ejecución del notebook se agrega a la ruta de acceso del sistema de Python, lo que te permite usar sentencias de importación estándar de Python para cargar secuencias de comandos y archivos de consulta desde tu repositorio de Git directamente en tu notebook.

Administra la activación y la conexión

Usa los siguientes controles para administrar tu espacio de trabajo:

  • Activar espacio de trabajo: Inicia el proceso de activación del repositorio de Git. La activación es un recurso compartido, por lo que, si varios notebooks en el mismo entorno de ejecución de Colab usan el mismo repositorio de Git, usan la misma activación.
  • Desactivar el espacio de trabajo: Detiene el proceso de activación del repositorio de Git. Si desmontas el espacio de trabajo, la activación no estará disponible para todos los notebooks en ese entorno de ejecución de Colab que lo usaban.
  • Conectar espacio de trabajo: Inicia la conexión a una activación activa para la sesión de notebook actual. La conexión actualiza el directorio de trabajo y la ruta de acceso del sistema del notebook para incluir el repositorio de Git, lo que te permite acceder a los archivos y, también, importarlos.
  • Desconectar espacio de trabajo: Finaliza la conexión de activación para la sesión de notebook actual y la restablece al estado predeterminado. La desconexión no afecta el estado de la conexión de activación para otras sesiones de notebook activas. Para finalizar la conexión de tu sesión, te recomendamos que uses el botón Desconectar espacio de trabajo.
  • Reparación: Restablece una activación o conexión a un estado correcto si se vuelve inutilizable.

Después de inicializar la activación, consulta la barra de Estado para ver el estado en tiempo real y la ruta activa de la activación. Los estados posibles son Conectado, Activado, Detenido y En mal estado.

¿Qué sigue?