Administra código con repositorios de Git de BigQuery Studio

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

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. Los repositorios de Git de BigQuery Studio aparecen directamente en el panel izquierdo, debajo de la carpeta raíz del usuario.

Si usas repositorios de Git de BigQuery Studio, puedes interactuar con tus recursos de código como si fueran archivos y directorios estándar, y mantener 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. Si bien estos repositorios aparecen en la carpeta raíz del usuario, que es una representación virtual de tus recursos en el proyecto, técnicamente se crean a nivel del proyecto.
  • No se admite el uso de un conector de cuentas de Developer Connect con un proxy de Git.
  • Las operaciones del sistema de archivos dentro de la ubicación de activación consumen la 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. Es posible que la operación de clonación exceda el tiempo de espera de la operación, lo que impide que se cree el repositorio correctamente.
  • El tamaño de los archivos de notebook almacenados en un punto de montaje del repositorio de Git de BigQuery Studio no puede superar 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 de almacenamiento externa.

  • Cuando realizas cambios en un repositorio de Git fuera del montaje (por ejemplo, cuando editas o cambias el nombre de los archivos en el panel izquierdo), esos cambios pueden tardar hasta 60 segundos en hacerse visibles dentro del montaje en el tiempo de ejecución de tu notebook. Puedes ajustar esta duración pasando 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é seguirá siendo válida. Si disminuyes este valor, aumentarás la frecuencia de sincronización y consumirás la cuota de Dataform más rápido.

Antes de comenzar

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

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 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 código con 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.

Crea un repositorio de Git de BigQuery Studio

Cuando crees un repositorio de Git, ten en cuenta los siguientes 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 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 necesarios 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é en la lista de entidades permitidas de la política de la organización dataform.restrictGitRemotes, primero agrega el repositorio de Git remoto a la lista allowedValues en la política y, luego, crea el repositorio de Git. Para obtener más información, consulta Cómo restringir 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 disponible un conector de cuenta de Developer Connect existente. Tienes las siguientes opciones:

    • Si se encuentra un conector de cuenta, se completará previamente el nombre visible del repositorio de Git. Puedes editar estos valores.
    • Si no existe ningún 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 otro tipo de conexión para conectarte con HTTPS o SSH.

  6. Haz clic en Conectar.

Cómo editar un archivo

Para editar un archivo, haz clic en un nodo de archivo, como una secuencia de comandos o un notebook de SQL, para abrirlo 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 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 en SQL, notebooks, lienzos de datos, preparaciones de datos, archivos o subdirectorios.
  • Upload to repository: 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 Cómo mover o copiar 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: Ve 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 a directorios dentro del mismo repositorio de Git.
  • Mover: Reubica el archivo en otro directorio dentro del mismo repositorio de Git. Para obtener más información, consulta Cómo mover o copiar archivos y directorios.
  • Descargar: Guarda una copia del archivo en tu máquina local.
  • Borrar: Quita el archivo de tu espacio de trabajo.

Cómo mover o copiar archivos y directorios

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

  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. Busca el archivo o 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 Copiar.

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 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 Commit message, 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. Tus cambios se sincronizan con el repositorio remoto.

Revisar una rama nueva

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

En la pestaña Repository, en la sección Branches, puedes ver tus ramas locales confirmadas. La etiqueta CURRENT indica tu rama activa, y la etiqueta DEFAULT indica la rama predeterminada del repositorio.

Para confirmar 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 Repositorio.

  3. Expande la sección Ramas.

  4. Haz clic en Abrir acciones junto a una rama y, luego, en Extraer 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 Finalizar compra. BigQuery Studio primero extrae la rama de origen. Si el nombre de 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 extraída.

Accede a archivos de notebook en un punto de montaje 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 del notebook. Una conexión de montaje es una conexión que hace que tu repositorio de Git remoto aparezca como si fuera un repositorio local en el tiempo 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.

Cómo montar 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 el notebook se conecta al dispositivo de montaje, 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 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 archivos y secuencias de comandos de consulta desde tu repositorio de Git directamente en tu notebook.

Cómo administrar la conexión y la estructura de soporte

Usa los siguientes controles para administrar tu espacio de trabajo:

  • Mount workspace: Inicia el proceso de activación del repositorio de Git. El montaje 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, usarán el mismo montaje.
  • Unmount workspace: Detiene el proceso de montaje del repositorio de Git. Si desmontas el espacio de trabajo, el montaje dejará de estar disponible para todos los notebooks que lo usaban en ese entorno de ejecución de Colab.
  • Conectar espacio de trabajo: Inicia la conexión a un montaje activo para la sesión actual del notebook. La conexión actualiza el directorio de trabajo y la ruta del sistema del notebook para incluir el repositorio de Git, lo que te permite acceder a los archivos e importarlos.
  • Desconectar el espacio de trabajo: Finaliza la conexión de la unidad de la sesión actual del notebook y la restablece al estado predeterminado. Desconectar no afecta el estado de conexión de la unidad de otras sesiones de notebook activas. Para finalizar la conexión de tu sesión, te recomendamos que uses el botón Desconectar el espacio de trabajo.
  • Reparar: Restaura una conexión o un punto de montaje a un estado de buen funcionamiento si se vuelve inutilizable.

Después de inicializar el montaje, consulta la barra de Estado para ver el estado en tiempo real y la ruta activa del montaje. Los estados de salud posibles son Connected, Mounted, Stopped y Unhealthy.

¿Qué sigue?