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 Google Cloud 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.

Cuando 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, técnicamente se crean 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. 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 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 activada.

  • Cuando realizas cambios en un repositorio de Git fuera de la activación, 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 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. 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 Google Cloud 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 Google Cloud 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 los usuarios de confianza, y limita los secretos accesibles al 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:

  • 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 requeridos 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 en 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 Restringe los repositorios remotos.

Para crear un repositorio de Git, haz lo siguiente:

  1. En la Google Cloud 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. 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 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 Google Cloud 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 Google Cloud 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 Google Cloud 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 Finalizar compra. 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.

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 Google Cloud consola de, ve a la página BigQuery.

    Ir a BigQuery

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

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

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

  4. Opcional: Para recuperar confirmaciones adicionales para un repositorio de clonación superficial, en el panel Historial de confirmaciones de la rama, haz clic en Recuperar.

    1. En el 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 recuperarán confirmaciones históricas adicionales, pero BigQuery Studio realizará una recuperación estándar para sincronizar las referencias y los metadatos remotos.

    2. Haz clic en Recuperar.

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

Accede a los archivos de notebook en una activación del 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 el notebook está conectado a la activación, 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 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 espacio de trabajo: Detiene el proceso de activación del repositorio de Git. Si desactivas el espacio de trabajo, la activación 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 activación 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 activación para la sesión actual del notebook y la restablece al estado predeterminado. La desconexión no afecta el estado de 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.
  • Reparar: 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 conocer el estado en tiempo real y la ruta de acceso activa de la activación. Los estados posibles son Conectado, Activado, Detenido y Incorrecto.

¿Qué sigue?