Administra código con repositorios de Git de BigQuery Studio

Vista previa

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Para enviar comentarios o hacer preguntas relacionadas con esta función de versión preliminar, comunícate con [e-mail].

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 explorador 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 tu 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.
• 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, 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 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. 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 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 los secretos durante la instalación del paquete.

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 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 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é 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:

   • Si se encuentra un conector de cuenta, se completa previamente el nombre visible del repositorio de Git. 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 otro tipo de conexión 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 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, 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 o copia archivos y directorios.
• Borrar: Quita de forma permanente el directorio y todo su contenido de tu espacio de trabajo local.

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.
• Mover: Reubica el archivo en 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.

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 de la izquierda, 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 los cambios.

5. Haz clic en Confirmar. Tus cambios se guardarán 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.

Revisa 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 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 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 de la izquierda, haz clic en Repositorio.

3. Expande la sección Ramas.

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

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.

   Nota: Si seleccionaste una rama de seguimiento remoto como fuente, el campo Branch name se completará previamente con el nombre de la rama correspondiente.

7. Haz clic en Finalizar compra. 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.

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 de la izquierda, haz clic en Repositorio.

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 adicionales de 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 recuperan confirmaciones históricas adicionales, pero BigQuery Studio realiza 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 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()

Nota: Te recomendamos que ejecutes este código en una celda de borrador de Colab que no se guarde con el notebook. Para crear una celda de borrador, haz clic en Insertar > Celda de código de borrador.

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 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 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 el 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 de 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?

• Obtén más información para crear notebooks.
• Obtén información para crear consultas guardadas.
• Obtén más información para crear y administrar repositorios.
• Obtén más información para organizar los recursos de código con carpetas.