Administra el código con los repositorios de Git de BigQuery Studio

Puedes administrar secuencias de comandos de SQL y notebooks con los repositorios de Git de BigQuery Studio. Esta función integra el control de versión directamente en el navegador de archivos de BigQuery Studio, lo que te permite clonar repositorios, administrar ramas y realizar operaciones de Git sin salir de la Cloud de Confiance consola.

Los repositorios de Git de BigQuery Studio ofrecen una experiencia más optimizada y basada en carpetas en comparación con los repositorios clásicos repositories. Los repositorios de Git de BigQuery Studio aparecen directamente en el panel izquierdo, en la carpeta raíz del usuario.

Si usas los repositorios de Git de BigQuery Studio, puedes interactuar con tus recursos de código como si fueran archivos y directorios estándar, mientras mantienes una conexión a 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 del usuario, que es una representación virtual de tus recursos en el proyecto, se crean técnicamente a nivel del proyecto.
  • No se admite el uso de un conector de cuenta de Developer Connect con un proxy de Git.
  • 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, tamaños de archivo grandes, 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.
  • El tamaño de los archivos de notebook almacenados en una unidad montada del repositorio de Git de BigQuery Studio no puede exceder los 30 MB. Si tus archivos son más grandes que 30 MB, guárdalos en el almacenamiento local del entorno de ejecución de Colab fuera de la ubicación de la unidad montada.

  • Cuando realizas cambios en un repositorio de Git fuera de la unidad montada, por ejemplo, si editas o cambias el nombre de los archivos en el panel izquierdo, esos cambios pueden tardar hasta 60 segundos en hacerse visibles dentro de la unidad montada 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 durante los que la caché debe seguir siendo válida. Si disminuyes este valor, aumenta la frecuencia de sincronización y se consume la cuota de Dataform más rápido.

Antes de comenzar

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

Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para administrar el código con los 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 el código con los 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 otros roles predefinidos.

Consideraciones de seguridad para los repositorios

Dado que los recursos de código en BigQuery funcionan con 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 trabajo de BigQuery, Usuario de BigQuery Studio y Usuario de BigQuery, pueden ver todos los recursos de código en el panel Explorador del Cloud de Confiance proyecto, 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 la creación y el acceso de edición a usuarios de confianza, y limita los secretos accesibles para 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.

Crea un repositorio de Git de BigQuery Studio

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

Para crear un repositorio de Git, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en la carpeta 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 disponible un conector de cuenta de Developer Connect existente. Tienes las siguientes opciones:

    • Si se encuentra un conector de cuenta, el nombre visible del repositorio de Git se completa previamente. Puedes editar estos valores.
    • Si no existe un conector de cuenta, haz clic en Crear conector de cuenta para crear uno nuevo.
    • Si prefieres no usar un conector de cuenta de Developer Connect, haz clic en Usar un tipo de conexión diferente para conectarte con HTTPS o SSH.

  6. 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 pestaña nueva del editor.

Los cambios que realices 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 Abrir 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, incluidas consultas de SQL, notebooks, lienzos de datos, preparaciones de datos, archivos o subdirectorios.
  • Subir al repositorio: Importa archivos existentes desde tu máquina local a l directorio seleccionado.
  • Cambiar nombre: Cambia el nombre del directorio.
  • Mover: Cambia la ubicación del directorio. Solo puedes mover un directorio a otra ubicación dentro del mismo repositorio de Git. Para obtener más información, consulta Mueve o copia archivos y directorios.
  • Borrar: Quita de forma permanente el directorio y todo su contenido de tu espacio de trabajo local.

A nivel del 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.
  • Mover: Cambia la ubicación del archivo a otro directorio dentro del mismo repositorio de Git. Para obtener más información, consulta Mueve o copia archivos y directorios.
  • Descargar: Guarda una copia del archivo en tu máquina local.
  • Borrar: Quita el archivo de tu espacio de trabajo.

Mueve o copia archivos y directorios

Puedes mover o copiar archivos y directorios, pero deben permanecer dentro del mismo repositorio de Git.

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

    Ir a BigQuery

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

  3. Busca el archivo o el directorio que quieras mover o copiar.

  4. Haz clic en Abrir acciones > Mover o Copiar.

  5. En el diálogo que aparece, selecciona el directorio de destino dentro del mismo repositorio de Git.

  6. Haz clic en Mover o en Copiar.

Confirma y envía los cambios

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

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Repositorio.

  3. Opcional: Coloca el cursor sobre un archivo modificado y haz clic en Ver diferencias 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 tus cambios.

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

  6. Haz clic en Enviar a la rama remota. Los cambios se sincronizan con el repositorio remoto.

Revisa una rama nueva

Puedes administrar ramas locales y crear una rama local nueva basada en una rama de seguimiento local o remota existente.

En la pestaña Repositorio, en la sección Ramas, puedes ver tus ramas locales revisadas. La etiqueta ACTUAL indica tu rama activa, y la etiqueta PREDETERMINADA indica la rama predeterminada del repositorio.

Para revisar una rama nueva, haz lo siguiente:

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

    Ir a BigQuery

  2. En el panel izquierdo, haz clic en Repositorio.

  3. Expande la sección Ramas.

  4. Haz clic en Abrir acciones junto a una rama y, luego, en Revisar una rama nueva.

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

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

  7. Haz clic en Revisar. BigQuery Studio primero revisa 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 revisada.

Accede a los archivos de notebook en una unidad montada del repositorio de Git

Cuando accedes a un notebook desde un repositorio de Git de BigQuery Studio, puedes montar el repositorio de Git host en el entorno de ejecución de tu notebook. Una unidad montada 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.

Monta el repositorio de Git

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

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Cuando el notebook está conectado a la unidad montada, se producen los siguientes cambios:

  • Se actualiza el directorio de trabajo actual de la sesión del notebook 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 instrucciones de importación de Python estándar para cargar secuencias de comandos de consulta y archivos desde tu repositorio de Git directamente en tu notebook.

Administra la unidad montada y la conexión

Usa los siguientes controles para administrar tu espacio de trabajo:

  • Montar espacio de trabajo: Inicia el proceso de montaje del repositorio de Git. La unidad montada 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 unidad montada.
  • Desmontar espacio de trabajo: Detiene el proceso de montaje del repositorio de Git. Si desmontas el espacio de trabajo, la unidad montada dejará de estar disponible para todos los notebooks de ese entorno de ejecución de Colab que la usaban.
  • Conectar espacio de trabajo: Inicia la conexión a una unidad montada activa para la sesión actual del notebook. 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 importarlos.
  • Desconectar espacio de trabajo: Finaliza la conexión de la unidad montada para la sesión actual del notebook y la restablece al estado predeterminado. La desconexión no afecta el estado de conexión de la unidad montada 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.
  • Reparar: Restablece una unidad montada o una conexión a un estado correcto si se vuelve inutilizable.

Después de inicializar la unidad montada, consulta la barra de Estado para conocer el estado en tiempo real y la ruta de acceso activa de la unidad montada. Los estados posibles son Conectado, Montado, Detenido y Incorrecto.

¿Qué sigue?