Criar notebooks

Neste documento, descrevemos como criar notebooks do Colab Enterprise no BigQuery. Os notebooks são recursos de código do BigQuery Studio com tecnologia do Dataform.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

Permissões necessárias

Defina as permissões apropriadas para criar, editar ou ver notebooks.

Todos os usuários com o papel de administrador do Dataform (roles/dataform.admin) têm acesso de proprietário a todos os notebooks criados no projeto.

Para mais informações sobre o Identity and Access Management (IAM) do BigQuery, consulte Controle de acesso com o IAM.

Permissões para criar notebooks

Para receber as permissões necessárias para criar e executar notebooks, peça ao administrador para conceder a você o papel do IAM de Usuário do BigQuery Studio (roles/bigquery.studioUser) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Observação: os usuários com papel de Criador de código em um projeto podem listar os nomes dos recursos de código nesse projeto usando a API Dataform ou a interface de linha de comando (CLI) do Dataform.

Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos. Para conferir as permissões exatas necessárias para criar e executar notebooks, abra a seção Permissões necessárias:

Permissões necessárias

• 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

Observação: ao criar um notebook, o BigQuery concede a você o papel de administrador do Dataform (roles/dataform.admin) nele. Todos os usuários com o papel de administrador do Dataform concedido no projeto do Google Cloud têm acesso de proprietário a todos os notebooks criados no projeto. Para modificar esse comportamento, consulte Conceder um papel específico na criação de recursos.

Papéis para editar notebooks

Para editar e executar notebooks, você precisa dos seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser)
• Editor de código (roles/dataform.codeEditor)

Papéis para visualizar notebooks

Para visualizar e executar notebooks, você precisa dos seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser)
• Visualizador de código (roles/dataform.codeViewer)

Considerações de segurança para notebooks

Como os recursos de código no BigQuery são alimentados pelo Dataform, considere as seguintes implicações de segurança para usuários com acesso a esses recursos:

• A visibilidade dos recursos de código é controlada pelas permissões do Dataform no nível do projeto. Os usuários com a permissão dataform.repositories.list, que está incluída nos papéis padrão do BigQuery, como Usuário de jobs do BigQuery, Usuário do BigQuery Studio e Usuário do BigQuery, podem ver todos os recursos de código no painel Explorador do projeto do Google Cloud , independentemente de terem criado esses recursos ou de eles terem sido compartilhados com eles. Para restringir a visibilidade, crie papéis personalizados que excluam a permissão dataform.repositories.list.
• Todas as secrets compartilhadas com o agente de serviço do Dataform podem ser acessadas por usuários que podem editar esses recursos. Para proteger suas credenciais, restrinja o acesso de criação e edição a usuários confiáveis e limite os secrets acessíveis ao agente de serviço do Dataform. Para mais informações, consulte Acesso a secrets durante a instalação do pacote.

Para mais informações, consulte Considerações de segurança para permissões do Dataform.

Criar notebooks

Use as seções a seguir para aprender a criar um notebook.

Definir a região padrão para recursos de código

Todos os novos recursos de código no seu projeto do Google Cloud usam uma região padrão. Depois que o recurso é criado, não é possível mudar a região dele.

Importante: se você mudar a região ao criar um recurso de código, ela vai se tornar o padrão para todos os recursos de código seguintes. Os recursos de código atuais não são afetados.

Para definir a região padrão para novos recursos de código, faça o seguinte:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos:

   

3. Ao lado do nome do projeto, clique em Ver ações do painel de arquivos > Mudar região do código.

4. Selecione a região de código que você quer usar como padrão.

5. Clique em Salvar.

Para uma lista de regiões com disponibilidade, consulte Locais do BigQuery Studio.

Criar um notebook usando a galeria de notebooks

A galeria de notebooks no console do Google Cloud para o BigQuery é o hub central para descobrir e usar modelos de notebook pré-criados.

Para criar um notebook usando um modelo da galeria, siga estas etapas:

1. No Google Cloud console, acesse o BigQuery Studio.

   Acessar o BigQuery Studio

2. Para abrir a galeria, na barra de guias do painel do editor, clique na seta ao lado de Consulta SQL e, em seguida, clique em Notebook > Todos os modelos.

3. Na galeria de notebooks, selecione um modelo. Por exemplo, selecione Primeiros passos com o BigQuery DataFrames.

   O novo notebook é aberto, com células que mostram exemplos de consultas no conjunto de dados público bigquery-public-data.ml_datasets.penguins.

4. Como alternativa, clique na seta ao lado de Consulta SQL e, em seguida, clique em Notebook > Notebook vazio, Notebook > Modelo do BigQuery ou Notebook > Modelo do Spark para abrir esses modelos específicos.

5. Para criar um notebook executável com base no modelo, clique em Usar este modelo.

6. Opcional: para ver os detalhes do notebook ou o histórico de versões, adicionar novos comentários, responder ou receber um link para um comentário, use a seguinte barra de ferramentas:

   

   O recurso da barra de ferramentas Comentários está em pré-lançamento. Para enviar feedback ou solicitar suporte para esse recurso, envie um e-mail para [e-mail].

7. Opcional: na barra de ferramentas Comentários, use o painel Referência para visualizar os detalhes do esquema de tabelas, snapshots, visualizações ou visualizações materializadas ou abri-los em uma nova guia. O painel também tem uma lista de recursos recentes e com estrela.

Criar um notebook a partir de uma tabela

Para criar um notebook contendo uma consulta padrão para uma determinada tabela, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda o projeto, clique em Conjuntos de dados e, em seguida, clique no conjunto de dados.

4. Clique em Visão geral > Tabelas e encontre a tabela que você quer consultar.

5. Ao lado da tabela, clique em Ações e em Abrir em > Notebook Python.

   O novo notebook é aberto, com células que mostram exemplos de consultas na tabela selecionada.

Criar um notebook para explorar o conjunto de resultados de uma consulta

Para criar um notebook para explorar o conjunto de resultados de uma consulta, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel do editor, execute uma consulta que gere um resultado.

3. No painel Resultados da consulta, clique em Abrir em > Notebook.

   O novo notebook é aberto, contendo células com o código para retornar o SQL da consulta e os resultados da consulta.

Criar um notebook a partir de um notebook

Para abrir qualquer versão de um notebook atual como um novo notebook, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda o projeto e clique em Notebooks.

4. Selecione um notebook

5. Clique em Histórico de versões.

6. Clique em Ver ações ao lado de uma versão do notebook e clique em Abrir como um novo notebook Python.

   Uma cópia do notebook é aberta como um novo notebook.

Fazer upload de notebooks

É possível fazer upload de um notebook local para usá-lo no BigQuery Studio. O notebook enviado por upload fica visível na página do BigQuery no console do Google Cloud .

Para fazer upload de um notebook, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto e depois siga um destes procedimentos:

   • Ao lado de Notebooks, clique em Ver ações > Fazer upload do notebook.
   • Ao lado do nome do projeto do Google Cloud , clique em Ver ações > Fazer upload para o projeto > Notebook.

4. Na caixa de diálogo Fazer upload do notebook, no campo notebook, clique em Procurar e selecione o notebook para upload.

5. Opcional: no campo Nome do notebook, edite o nome do notebook.

6. No campo Região, selecione a região em que você quer fazer upload do notebook.

7. Clique em Fazer upload.

Seu notebook pode ser acessado pelo painel Explorador.

Conectar-se a um ambiente de execução

Use as seções a seguir para saber como conectar um notebook a um ambiente de execução da Gemini Enterprise Agent Platform. Um ambiente de execução é um recurso de computação que executa o código no notebook. O ambiente de execução precisa estar na mesma região do notebook.

Para mais informações sobre ambientes de execução, consulte Ambientes de execução e modelos de ambiente de execução.

Observação :se você usa o VPC Service Controls, verifique se configurou o Acesso privado do Google com o VPC Service Controls antes de se conectar a um ambiente de execução. Caso contrário, o serviço retornará o erro Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.

Conectar ao ambiente de execução padrão

O padrão é predefinido e requer configuração mínima.

Para se conectar ao ambiente de execução padrão, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda o projeto e clique em Notebooks.

4. Clique no nome de um notebook para abri-lo.

5. No notebook, clique em Conectar ou execute qualquer célula no notebook.

   Se você ainda não tiver um ambiente de execução ativo, poderá levar vários minutos para se conectar ao ambiente de execução padrão.

Conectar-se a um ambiente de execução não padrão

Se você quiser usar um ambiente de execução diferente do padrão, primeiro crie esse ambiente de execução adicional na Agent Platform.

Para se conectar ao ambiente de execução não padrão, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda o projeto e clique em Notebooks.

4. Clique no nome de um notebook para abri-lo.

5. No notebook, clique no menu suspenso ao lado de Conectar e, em seguida, clique em Conectar a um ambiente de execução.

6. Clique em Conectar a um ambiente de execução.

7. Em Ambientes de execução, selecione o ambiente a ser usado. O ambiente de execução precisa estar no mesmo local que o notebook.

8. Clique em Conectar.

Conexão com um novo ambiente de execução

Para se conectar a um novo ambiente de execução, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda o projeto e clique em Notebooks.

4. Clique no nome de um notebook para abri-lo.

5. No notebook, clique no menu suspenso ao lado de Conectar e, em seguida, clique em Conectar a um ambiente de execução.

6. Clique em Criar novo ambiente de execução.

7. Em Modelo de ambiente de execução, selecione o modelo de ambiente de execução da Agent Platform para usar.

8. Em Nome do ambiente de execução, digite um nome para o ambiente de execução.

9. Clique em Conectar.

Solução de problemas

Confira mais informações em Resolver problemas no Colab Enterprise.

A seguir

• Saiba como gerenciar notebooks.
• Saiba como programar notebooks.
• Saiba como acessar arquivos de notebook em uma montagem de repositório Git do BigQuery Studio.