Crear notebooks

En este documento se describe cómo administrar notebooks de Colab Enterprise en BigQuery. Los notebooks son recursos de código de BigQuery Studio con tecnología de Dataform.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Permisos necesarios

Configura los permisos adecuados para crear, editar o ver notebooks.

Todos los usuarios con el rol de administrador de Dataform (roles/dataform.admin) tienen acceso de propietario a todos los notebooks creados en el proyecto.

Para obtener más información sobre Identity and Access Management (IAM) de BigQuery, consulta Control de acceso con IAM.

Permisos para crear notebooks

Para obtener los permisos que necesitas para crear y ejecutar notebooks, pídele a tu administrador que te otorgue el rol de IAM de usuario de BigQuery Studio (roles/bigquery.studioUser) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Nota: Los usuarios con el rol Creador de código en un proyecto pueden enumerar los nombres de los recursos de código de ese proyecto con la API de Dataform o la interfaz de línea de comandos (CLI) de Dataform.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido. Para ver los permisos exactos que se necesitan para crear y ejecutar notebooks, expande la sección Permisos necesarios:

Permisos necesarios

• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.list
• dataform.repositories.create
• dataform.repositories.list
• dataform.collections.create
• dataform.collections.list
• aiplatform.notebookRuntimeTemplates.apply
• aiplatform.notebookRuntimeTemplates.get
• aiplatform.notebookRuntimeTemplates.list
• aiplatform.notebookRuntimeTemplates.getIamPolicy
• aiplatform.notebookRuntimes.assign
• aiplatform.notebookRuntimes.get
• aiplatform.notebookRuntimes.list
• aiplatform.operations.list

Nota: Cuando creas un notebook, BigQuery te otorga el rol de administrador de Dataform (roles/dataform.admin) en ese notebook. Todos los usuarios con el rol de administrador de Dataform otorgado en el proyecto de Google Cloud tienen acceso de propietario a todos los notebooks creados en el proyecto. Para anular este comportamiento, consulta Otorga un rol específico cuando se crea un recurso.

Roles para editar notebooks

Para editar y ejecutar notebooks, necesitas los siguientes roles de IAM:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)
• Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser)
• Editor de código (roles/dataform.codeEditor)

Roles para ver notebooks

Para ver y ejecutar notebooks, necesitas los siguientes roles de IAM:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)
• Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser)
• Vista de código (roles/dataform.codeViewer)

Consideraciones de seguridad para los notebooks

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.

Crear notebooks

Usa las siguientes secciones para aprender a crear un notebook.

Configura la región predeterminada para los elementos de código

Todos los elementos de código nuevos de tu proyecto de Google Cloud usan una región predeterminada. Después de crear el recurso, no puedes cambiar su región.

Importante: Si cambias la región mientras creas un elemento de código, esa región se convertirá en la predeterminada para todos los elementos de código posteriores. Los recursos de código existentes no se ven afectados.

Para establecer la región predeterminada de los elementos de código nuevos, haz lo siguiente:

1. Ve a la página de BigQuery.

   Ir a BigQuery

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

   

3. Junto al nombre del proyecto, haz clic en Ver acciones del panel de archivos > Cambiar región de código.

4. Selecciona la región de código que quieres usar como predeterminada.

5. Haz clic en Guardar.

Para obtener una lista de las regiones admitidas, consulta Ubicaciones de BigQuery Studio.

Crea un notebook con la galería de notebooks

La galería de notebooks en la consola de Google Cloud para BigQuery es tu centro principal para descubrir y usar plantillas de notebooks compiladas previamente.

Para crear un notebook a partir de una plantilla de la galería de notebooks, sigue estos pasos:

1. En la consola de Google Cloud , ve a BigQuery Studio.

   Ir a BigQuery Studio

2. Para abrir la galería, en la barra de pestañas del panel del editor, haz clic en la flecha junto a Consulta en SQL y, luego, en Notebook > Todas las plantillas.

3. En la galería de notebooks, selecciona una plantilla. Por ejemplo, puedes seleccionar Comienza a usar BigQuery DataFrames.

   Se abrirá el notebook nuevo, el cual contiene celdas que muestran consultas de ejemplo en el conjunto de datos públicos bigquery-public-data.ml_datasets.penguins.

4. Como alternativa, puedes hacer clic en la flecha junto a Consulta en SQL y, luego, en Notebook > Notebook vacío, Notebook > Plantilla de BigQuery o Notebook > Plantilla de Spark para abrir estas plantillas específicas.

5. Para crear un notebook ejecutable a partir de la plantilla, haz clic en Usar esta plantilla.

6. Opcional: Para ver los detalles del notebook o el historial de versiones, agregar comentarios nuevos, responder un comentario existente o conseguir un vínculo a él, usa la siguiente barra de herramientas:

   

   La función de la barra de herramientas Comentarios está en versión preliminar. Para enviar comentarios o solicitar asistencia para esta función, envía un correo electrónico a [e-mail].

7. Opcional: En la barra de herramientas Comentarios, puedes usar el panel Referencia para obtener una vista previa de los detalles del esquema de tablas, instantáneas, vistas o vistas materializadas, o abrirlas en una pestaña nueva. El panel también tiene una lista de recursos recientes y destacados.

Crea un notebook a partir de una tabla

Para crear un notebook que contenga una consulta predeterminada para una tabla específica, sigue estos pasos:

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 Explorar.

   

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

3. En el panel Explorador, expande tu proyecto, haz clic en Conjuntos de datos y, luego, en tu conjunto de datos.

4. Haz clic en Descripción general > Tablas y busca la tabla que deseas consultar.

5. Junto a la tabla, haz clic en Acciones y, luego, en Abrir en > Notebook de Python.

   Se abrirá el notebook nuevo que contiene celdas que muestran consultas de ejemplo en la tabla seleccionada.

Crea un notebook para explorar el conjunto de resultados de una consulta

Para crear un notebook que explore el conjunto de resultados de una consulta, sigue estos pasos:

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

   Ir a BigQuery

2. En el panel del editor, ejecuta una consulta que genere un resultado.

3. En el panel Resultados de la consulta, haz clic en Abrir en > Notebook.

   Se abrirá el notebook nuevo, que contiene celdas con código para devolver el SQL de la consulta y los resultados de la consulta.

Crea un notebook a partir de uno ya existente

Para abrir cualquier versión de un notebook existente como nuevo, sigue estos pasos:

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 Explorar.

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Selecciona un notebook

5. Haz clic en Historial de versiones.

6. Haz clic en Ver acciones junto a la versión de un notebook y, luego, en Abrir como notebook nuevo de Python.

   Se abrirá una copia del notebook como un notebook nuevo.

Subir notebooks

Puedes subir un notebook local para usarlo en BigQuery Studio. El notebook subido se puede ver en la página de BigQuery de la consola de Google Cloud .

Para borrar un notebook, sigue estos pasos:

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 Explorar.

   

3. En el panel Explorador, expande tu proyecto y, luego, realiza una de las siguientes acciones:

   • Junto a Notebooks, haz clic en Ver acciones > Subir notebook.
   • Junto al nombre del proyecto de Google Cloud , haz clic en Ver acciones > Subir al proyecto > Notebook.

4. En el cuadro de diálogo Subir notebook, en el campo Seleccionar notebook, haz clic en Explorar y selecciona el notebook que deseas subir.

5. En el campo Nombre del notebook, edita el nombre del archivo de notebook (opcional).

6. En el campo Región, selecciona la región en la que deseas subir tu notebook.

7. Haz clic en Subir.

Puedes acceder a tu notebook a través del panel Explorador.

Conéctate a un entorno de ejecución

Usa las siguientes secciones para aprender a conectar un notebook a un entorno de ejecución de Gemini Enterprise Agent Platform. Un entorno de ejecución es un recurso de procesamiento que ejecuta el código en tu notebook. El entorno de ejecución debe estar en la misma región que el notebook.

Para obtener más información sobre los entornos de ejecución, consulta Entornos de ejecución y plantillas de entorno de ejecución.

Nota: Si usas los Controles del servicio de VPC, asegúrate de haber configurado el Acceso privado a Google con los Controles del servicio de VPC antes de conectarte a un entorno de ejecución. De lo contrario, el servicio devuelve el error Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.

Conéctate al entorno de ejecución predeterminado

El entorno de ejecución predeterminado es un entorno de ejecución predeterminado que requiere una configuración mínima.

Para conectarte al entorno de ejecución predeterminado, sigue estos pasos:

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 Explorar.

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en Conectar o ejecuta cualquier celda.

   Es posible que la conexión al entorno de ejecución predeterminado demore varios minutos si aún no tienes un entorno de ejecución activo.

Conéctate a un entorno de ejecución no predeterminado

Si deseas usar un entorno de ejecución que no sea el predeterminado, primero debes crear ese entorno de ejecución adicional en Agent Platform.

Para conectarte al entorno de ejecución no predeterminado, sigue estos pasos:

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 Explorar.

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en el menú desplegable junto a Conectar y, luego, en Conectar a un entorno de ejecución.

6. Haz clic en Conectarse a un entorno de ejecución existente.

7. En Entornos de ejecución, selecciona el entorno de ejecución que deseas usar. El entorno de ejecución debe estar en la misma ubicación que el notebook.

8. Haz clic en Conectar.

Conectar a un nuevo entorno de ejecución

Para conectarte a un entorno de ejecución nuevo, sigue estos pasos:

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 Explorar.

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en el menú desplegable junto a Conectar y, luego, en Conectar a un entorno de ejecución.

6. Haz clic en Crear un entorno de ejecución nuevo.

7. En Plantilla del entorno de ejecución, selecciona la plantilla de entorno de ejecución de Agent Platform que usarás.

8. En Nombre del entorno de ejecución, escribe un nombre para el entorno de ejecución.

9. Haz clic en Conectar.

Soluciona problemas

Para obtener más información, consulta Soluciona problemas de Colab Enterprise.

¿Qué sigue?

• Obtén más información sobre cómo administrar notebooks.
• Obtén más información para programar notebooks.
• Aprende a acceder a archivos de notebooks en una activación de repositorio de Git de BigQuery Studio.