Crie notebooks

Este documento descreve como criar blocos de notas do Colab Enterprise no BigQuery. Os blocos de notas são recursos de código do BigQuery Studio com tecnologia Dataform.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (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 API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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 (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 API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Autorizações necessárias

Defina as autorizações adequadas para criar, editar ou ver blocos de notas.

Todos os utilizadores com a função Administrador do Dataform (roles/dataform.admin) têm acesso de proprietário a todos os blocos de notas criados no projeto.

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

Autorizações para criar blocos de notas

Para receber as autorizações necessárias para criar e executar blocos de notas, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

• Utilizador da sessão de leitura do BigQuery (roles/bigquery.readSessionUser)

• Utilizador do BigQuery Studio (roles/bigquery.studioUser) A função de utilizador do BigQuery Studio combina as seguintes funções do IAM:

  • Utilizador de tarefas do BigQuery (roles/bigquery.jobUser)
  • Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)

  • Code Creator (roles/dataform.codeCreator)

    Nota: os utilizadores aos quais foi atribuído o papel de criador de código num projeto podem listar os nomes dos recursos de código nesse projeto através da API Dataform ou da interface de linhas de comando (CLI) do Dataform. Os utilizadores que não são administradores que usam o BigQuery Studio só podem ver recursos de código que criaram ou que foram partilhados com eles.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas. Para ver as autorizações exatas necessárias para criar e executar blocos de notas, expanda a secção Autorizações necessárias:

Autorizaçõ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
Nota: os utilizadores com a autorização dataform.repositories.create podem executar código através da conta de serviço do Dataform predefinida e de todas as autorizações concedidas a essa conta de serviço. Para mais informações, consulte Considerações de segurança para autorizações do Dataform.
• 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

Funções para editar notebooks

Para editar e executar blocos de notas, precisa das seguintes funções do IAM:

• Utilizador de tarefas do BigQuery (roles/bigquery.jobUser)
• Utilizador da sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Editor de código (roles/dataform.codeEditor)

Funções para ver notebooks

Para ver e executar blocos de notas, precisa das seguintes funções do IAM:

• Utilizador de tarefas do BigQuery (roles/bigquery.jobUser)
• Utilizador da sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Visualizador de código (roles/dataform.codeViewer)

Crie notebooks

Use as secções seguintes para saber como criar um bloco de notas.

Defina a região predefinida para recursos de código

Se estiver a criar um recurso de código pela primeira vez, deve definir a região predefinida para recursos de código. Não é possível alterar a região de um recurso de código depois de o criar.

Nota: se criar um notebook e escolher uma região predefinida diferente da que tem usado para recursos de código, por exemplo, escolher us-west1 quando tem usado us-central1, esse notebook e todos os recursos de código que criar posteriormente usam essa nova região por predefinição. Os recursos de código existentes continuam a usar a região que lhes foi atribuída quando foram criados.

Todos os recursos de código no BigQuery Studio usam a mesma região predefinida. Para definir a região predefinida para recursos de código, siga estes passos:

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, encontre o projeto no qual ativou os recursos de código.

3. Clique em Ver ações junto ao projeto e, de seguida, clique em Alterar a minha região de código predefinida.

4. Para Região, selecione a região que quer usar para recursos de códigos.

5. Clique em Selecionar.

Para ver uma lista das regiões suportadas, consulte o artigo Localizações do BigQuery Studio.

Crie um bloco de notas a partir do editor do BigQuery

Para criar um bloco de notas que contenha uma consulta predefinida para uma determinada tabela, siga estes passos:

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. Na barra de separadores do painel do editor, clique na seta junto a Consulta SQL e, de seguida, clique em Criar bloco de notas Python.

   O novo bloco de notas é aberto com células que mostram consultas de exemplo em relação ao conjunto de dados público bigquery-public-data.ml_datasets.penguins.

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

   

   As funcionalidades da barra de ferramentas Detalhes, Histórico de versões e Comentários estão em pré-visualização. Para enviar feedback ou pedir apoio técnico para estas funcionalidades, envie um email para [e-mail].

4. Opcional: na barra de ferramentas, pode usar o painel Referência para pré-visualizar os detalhes do esquema de tabelas, instantâneos, vistas ou vistas materializadas, ou abri-los num novo separador. O painel também tem uma lista de recursos recentes e com estrela.

Crie um notebook a partir de uma tabela

Para criar um bloco de notas que contenha uma consulta predefinida para uma tabela específica, siga estes passos:

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o seu projeto e encontre a tabela que quer consultar.

3. Clique em Ver ações junto à tabela e, de seguida, clique em Consultar no > bloco de notas do Python.

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

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

Para criar um bloco de notas para explorar o conjunto de resultados de uma consulta, siga estes passos:

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

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

3. No painel Resultados da consulta, clique em Explorar dados e, de seguida, clique em Explorar com o bloco de notas do Python.

   O novo bloco de notas é aberto com células com código para devolver o SQL da consulta e os resultados da consulta.

Crie um notebook a partir de um notebook existente

Para abrir qualquer versão de um notebook existente como um novo notebook, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Selecione um bloco de notas.

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

4. Clique em Ver ações junto a uma versão do bloco de notas e, de seguida, clique em Abrir como novo bloco de notas Python.

   É aberta uma cópia do bloco de notas como um novo bloco de notas.

Carregue blocos de notas

Pode carregar um bloco de notas local para o usar no BigQuery Studio. O bloco de notas carregado fica visível na página do BigQuery da consola Google Cloud .

Para carregar um bloco de notas, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o seu projeto e, em seguida, faça uma das seguintes ações:

   • Junto a Blocos de notas, clique em Ver ações > Carregar para o Bloco de notas.
   • Junto ao Google Cloud nome do projeto, clique em Ver ações > Carregar para o projeto > Bloco de notas Python.

3. Na caixa de diálogo Carregar bloco de notas, no campo Bloco de notas, clique em Procurar e, de seguida, selecione o bloco de notas que quer carregar.

4. Opcional: no campo Nome do bloco de notas, edite o nome do bloco de notas.

5. No campo Região, selecione a região onde quer carregar o seu notebook.

6. Clique em Carregar.

O bloco de notas aparece no painel do explorador.

Ligue-se a um tempo de execução

Use as secções seguintes para saber como associar um bloco de notas a um tempo de execução do Vertex AI. Um tempo de execução é um recurso de computação que executa o código no seu bloco de notas. O tempo de execução tem de estar na mesma região que o bloco de notas.

Para mais informações acerca dos tempos de execução, consulte o artigo Tempos de execução e modelos de tempo de execução.

Nota: se usar os VPC Service Controls, certifique-se de que configurou o acesso privado à Google com os VPC Service Controls antes de se ligar a um tempo de execução. Caso contrário, o serviço devolve o erro Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.

Ligue-se ao tempo de execução predefinido

O tempo de execução predefinido é um tempo de execução predefinido que requer uma configuração mínima.

Para se ligar ao tempo de execução predefinido, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Clique no nome de um bloco de notas para o abrir.

3. No bloco de notas, clique em Associar ou execute qualquer célula no bloco de notas.

   Pode demorar vários minutos a estabelecer ligação ao tempo de execução predefinido se ainda não tiver um tempo de execução ativo.

Ligue-se a um tempo de execução não predefinido

Se quiser usar um tempo de execução diferente do tempo de execução predefinido, tem de criar esse tempo de execução adicional no Vertex AI.

Para estabelecer ligação ao tempo de execução não predefinido, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Clique no nome de um bloco de notas para o abrir.

3. No bloco de notas, clique no menu pendente junto a Associar e, de seguida, clique em Associar a um tempo de execução.

4. Clique em Associar a um tempo de execução existente.

5. Em Tempos de execução, selecione o tempo de execução a usar. O tempo de execução tem de estar na mesma localização que o bloco de notas.

6. Clique em Ligar.

Ligue-se a um novo tempo de execução

Para associar a um novo tempo de execução, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Clique no nome de um bloco de notas para o abrir.

3. No bloco de notas, clique no menu pendente junto a Associar e, de seguida, clique em Associar a um tempo de execução.

4. Clique em Criar novo tempo de execução.

5. Em Modelo do ambiente de execução, selecione o modelo do ambiente de execução do Vertex AI a usar.

6. Em Nome do ambiente de execução, introduza um nome para o ambiente de execução.

7. Clique em Ligar.

Conceda acesso a notebooks

Para conceder a outros utilizadores acesso a um notebook, adicione esses utilizadores a uma função do IAM adequada.

Importante: os utilizadores que têm acesso ao bloco de notas podem ver todos os resultados gerados pelo código no bloco de notas, mesmo que estes resultados contenham dados de tabelas às quais não têm acesso. Para impedir a partilha da saída guardada, desative a opção de guardar a saída do bloco de notas.

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Encontre o bloco de notas ao qual quer conceder acesso.

3. Clique em Ver ações junto ao bloco de notas e, de seguida, clique em Partilhar > Gerir autorizações.

4. No painel Gerir autorizações, clique em Adicionar utilizador/grupo.

5. No campo Novos membros, introduza um membro.

6. Na lista Função, selecione uma das seguintes funções:

   • Proprietário do código: pode realizar qualquer ação no bloco de notas, incluindo eliminá-lo ou partilhá-lo.
   • Editor de código: pode editar o notebook.
   • Leitor de código: pode ver o notebook.
   Nota: o principal também tem de ter as funções Utilizador do tempo de execução do bloco de notas (roles/aiplatform.notebookRuntimeUser) e Utilizador do BigQuery (roles/bigquery.user) para executar o bloco de notas.

7. Opcional: para ver uma lista completa de funções e definições de partilha avançadas, clique em Partilha avançada.

8. Clique em Guardar.

9. Para voltar à página de informações do bloco de notas, clique em Fechar.

Partilhe notebooks

Para partilhar um notebook com outros utilizadores, pode gerar e partilhar um link para o notebook. Para que outros utilizadores vejam o notebook que partilha, tem de conceder acesso ao notebook.

Para executar um notebook, os utilizadores têm de ter acesso aos dados aos quais o notebook acede. Para mais informações, consulte o artigo Conceda acesso a um conjunto de dados.

Importante: os utilizadores que têm acesso ao bloco de notas podem ver todos os resultados gerados pelo código no bloco de notas, mesmo que estes resultados contenham dados de tabelas às quais não têm acesso. Para impedir a partilha da saída guardada, desative a opção de guardar a saída do bloco de notas.

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, expanda a pasta Shared notebooks. Encontre o bloco de notas que quer partilhar.

3. Clique em Ver ações junto ao bloco de notas e, de seguida, clique em Partilhar > Copiar link.

4. Partilhe o link com outros utilizadores.

Desative a gravação da saída do bloco de notas

Pode impedir a partilha da saída do bloco de notas guardada com outros utilizadores que tenham acesso ao ficheiro do bloco de notas desativando a poupança da saída do bloco de notas.

Quando desativa a poupança de resultados para um bloco de notas selecionado, o BigQuery elimina todos os resultados guardados no ficheiro do bloco de notas e não guarda os resultados das execuções subsequentes.

No entanto, os utilizadores que têm acesso ao bloco de notas podem continuar a ver o respetivo resultado das seguintes formas:

• Execute o bloco de notas para ver o respetivo resultado atual. Esta saída não é guardada.
• Veja uma versão de arquivo do bloco de notas e a respetiva saída no histórico de revisões.

Para desativar a poupança de resultados para um bloco de notas selecionado, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o projeto e a pasta Notebooks e, de seguida, selecione o bloco de notas para o qual quer desativar a poupança de resultados.

3. Clique em Ativar/desativar visibilidade do cabeçalho > Editar > Definições do bloco de notas.

4. Na janela Definições do bloco de notas, selecione Omitir saída das células de código ao guardar este bloco de notas.

5. Clique em Guardar.

6. Clique em Recarregar.

Resolva conflitos

Se fizer alterações em conflito com outro utilizador num bloco de notas, o serviço gera o erro Automatic saving failed. This file was updated remotely or in another tab. e fornece um link Show diff. Para resolver o conflito, siga estes passos:

1. Clique no link Show diff. É aberta a caixa de diálogo Reveja as alterações remotas.
2. Opcional: para comparar o código fonte do notebook, selecione a caixa de verificação Fonte não processada.
3. Opcional: para comparar as versões incorporadas em vez de em painéis separados, selecione a caixa de verificação Diferença incorporada.
4. Reveja as alterações e decida quais manter, revendo a sua entrada, se necessário.
5. Clique em Guardar alterações.

Mude o nome dos blocos de notas

Para mudar o nome de um bloco de notas, siga estes passos:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No painel do Explorador, expanda o projeto e a pasta Notebooks e, se necessário, a pasta Shared notebooks. Encontre o bloco de notas cujo nome quer mudar.

3. Clique em Ver ações junto ao bloco de notas e, de seguida, clique em Mudar o nome.

4. Escreva um nome para o bloco de notas e, de seguida, clique em Mudar o nome.

Resolução de problemas

Para mais informações, consulte o artigo Resolva problemas do Colab Enterprise.

O que se segue?

• Saiba como gerir blocos de notas.
• Saiba como agendar blocos de notas.