Gerenciar notebooks

Neste documento, descrevemos como gerenciar notebooks do Colab Enterprise no BigQuery, incluindo como visualizar, comparar, restaurar, programar e excluir notebooks.

Os notebooks são recursos de código do BigQuery Studio com tecnologia do Dataform.

Para usar notebooks, primeiro é necessário ativar o BigQuery Studio para gerenciamento de recursos.

Permissões necessárias

Para compartilhar notebooks, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Usuário de jobs do BigQuery(roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery(roles/bigquery.readSessionUser)
• Proprietário de código (roles/dataform.codeOwner) no nível do recurso.

Para salvar e excluir 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)
• Proprietário de código (roles/dataform.codeOwner) ou Editor de código (roles/dataform.codeEditor)

Para trabalhar com revisões de notebook, 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)

• Qualquer um dos seguintes papéis:

  • Proprietário de código (roles/dataform.codeOwner)
  • Editor de código (roles/dataform.codeEditor)
  • Visualizador de código (roles/dataform.codeViewer)

Para criar programações de notebooks (pré-lançamento), você precisa das seguintes funções:

• Administrador do Dataform (roles/dataform.admin)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser) ou Usuário do BigQuery Studio (roles/bigquery.studioUser)

Para editar as programações de notebooks (Visualização), você precisa do papel de Editor do Dataform (roles/dataform.editor).

Para conferir as programações de notebooks (Visualização), você precisa do papel de Visualizador de formulários de dados (roles/dataform.viewer).

Para mais informações sobre o IAM do BigQuery, consulte Controle de acesso com o IAM.

Conceder acesso a notebooks

Para conceder acesso a um notebook a outros usuários, adicione-os a um papel apropriado do IAM.

Importante: os usuários que têm acesso ao notebook podem ver toda a saída gerada pelo código no notebook, mesmo que ela contenha dados de tabelas às quais eles não têm acesso. Para evitar que a saída salva seja compartilhada, desative o salvamento de saída do notebook.

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Encontre o notebook a que você quer conceder acesso.

3. Clique em Ver ações ao lado do notebook e depois selecione Compartilhar > Gerenciar permissões.

4. No painel Gerenciar permissões, clique em Adicionar usuário/grupo.

5. No campo Novos principais, digite um principal..

6. Na lista Papel, selecione um dos seguintes papéis:

   • Proprietário de código: pode executar qualquer ação no notebook, inclusive excluí-lo ou compartilhá-lo.
   • Editor de código: pode editar o notebook.
   • Leitor de código: pode visualizar o notebook.
   Observação: o principal também precisa ter os papéis Usuário de ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser) e Usuário do BigQuery (roles/bigquery.user) para executar o notebook.

7. Opcional: para ver uma lista completa de papéis e configurações de compartilhamento avançadas, clique em Compartilhamento avançado.

8. Clique em Salvar.

9. Para retornar à página de informações do notebook, clique em Fechar.

Compartilhar notebooks

Para compartilhar um notebook com outros usuários, gere e compartilhe um link para ele. Para que outros usuários vejam o notebook que você compartilha, primeiro é necessário conceder acesso a ele.

Para executar um notebook, os usuários precisam ter acesso aos dados que ele acessa. Para mais informações, consulte Conceder acesso a um conjunto de dados.

Importante: os usuários que têm acesso ao notebook podem ver toda a saída gerada pelo código no notebook, mesmo que ela contenha dados de tabelas às quais eles não têm acesso. Para evitar que a saída salva seja compartilhada, desative o salvamento de saída do notebook.

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, expanda a pasta Notebooks compartilhados. Localize o notebook que você quer compartilhar.

3. Clique em Conferir ações ao lado do notebook e depois em Compartilhar > Copiar link.

4. Compartilhe o link com outros usuários.

Mostrar todos os notebooks

Para ver uma lista de todos os notebooks do projeto, faça o seguinte:

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

   Acessar o BigQuery

2. No painel Explorer, clique em Ver ações ao lado de Notebooks e execute uma das seguintes ações:

• Para abrir a lista na guia atual, clique em Mostrar tudo.
• Para abrir a lista em uma nova guia, clique em Mostrar tudo em > Nova guia.
• Para abrir a lista em uma guia dividida, clique em Mostrar tudo em > Dividir guia.

Ver metadados do notebook

Para visualizar os metadados do notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook cujos metadados você quer ver.

3. Consulte o painel Resumo para ver informações sobre o notebook, como a região que ele usa para dados e a data da última modificação.

Trabalhar com versões de notebook

Use as seções a seguir para aprender a visualizar, comparar e restaurar versões de um notebook.

Ver versões do notebook

Para ver as versões do notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook com a atividade que você quer ver.

3. Clique na guia Atividade para ver uma lista das versões do notebook em ordem decrescente por data.

Comparar versões do notebook

Para comparar as versões do notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook com as informações de versão que você quer comparar.

3. Na guia Atividade, clique em Ver ações ao lado de uma versão do notebook e clique em Comparar. O painel de comparação é aberto, comparando a versão do notebook selecionada com a versão atual.

4. Opcional: para comparar as versões inline em vez de em painéis separados, clique em Comparar e em Inline.

5. Opcional: para comparar o código-fonte das versões, clique em Comparar e em Mostrar a origem bruta.

6. Opcional: para ocultar a saída do comando no notebook, clique em Comparar e desmarque Mostrar resultado.

Restaurar uma versão do notebook

Use uma das seguintes opções para restaurar uma versão do notebook. A restauração do painel de comparação permite comparar as versões atuais e anteriores do notebook antes de optar por restaurar a versão anterior. Restaurar um notebook cria uma nova versão dele em vez de substituir a atual. Nenhum histórico de versões é perdido.

Painel de atividades

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, expanda a pasta Notebooks compartilhados. Clique no nome do notebook que tem uma versão anterior que você quer restaurar.

3. Selecione o painel Atividade.

4. Clique em Ver ações ao lado da versão do notebook que você quer restaurar e, em seguida, clique em Restaurar.

5. Clique em Confirmar.

Painel de comparação

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, expanda a pasta Notebooks compartilhados. Clique no nome do notebook que tem uma versão anterior que você quer restaurar.

3. Selecione o painel Atividade.

4. Clique em Ver ações ao lado de uma versão do notebook e depois em Comparar. O painel de comparação é aberto, comparando a versão do notebook selecionada com a versão mais recente.

5. Se quiser restaurar a versão anterior do notebook após a comparação, clique em Restaurar.

6. Clique em Confirmar.

Fazer o download de um notebook

Para fazer o download de um notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook que você quer transferir por download.

3. Clique em Fazer download.

Programar notebooks

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para enviar feedback sobre a programação de notebooks, envie um e-mail para [e-mail].

É possível programar um notebook para ser executado automaticamente em um horário e frequência especificados, por exemplo, para treinar um modelo de ML, chamar APIs externas ou executar o código do DataFrames do BigQuery.

As mudanças feitas em um notebook são salvas automaticamente, mas ficam disponíveis apenas para você e para os usuários que têm acesso ao notebook. Para atualizar a programação com uma nova versão do notebook, é necessário implantar o notebook. Ao implantar um notebook, você atualiza a programação dele com a versão atual. Os agendamentos executam a versão implantada mais recente do notebook.

Cada programação de notebook é executada por uma conta de serviço personalizada do Dataform, que você seleciona durante a criação da programação. Para mais informações sobre os tipos de contas de serviço no Dataform, consulte Sobre as contas de serviço no Dataform.

O Dataform grava a saída das execuções de notebooks programadas no bucket do Cloud Storage selecionado durante a criação da programação.

As programações de notebooks usam um ambiente de execução padrão do E2. As cobranças do Colab Enterprise para ambientes de execução são válidas. A cobrança é feita pelo processamento de execução com base no tipo de máquina E2. Para informações sobre os preços dos ambientes de execução E2 padrão, consulte Preços do Colab Enterprise.

Ativar a programação do notebook

Para programar notebooks, é necessário conceder os seguintes papéis à conta de serviço personalizada do Dataform que você planeja usar para as programações de notebooks:

Usuário Executor do notebook (roles/aiplatform.notebookExecutorUser)

Siga Conceder um único papel em um projeto para conceder o papel de usuário de executor de notebooks à sua conta de serviço do Dataform personalizada no projeto selecionado.

Administrador do Storage (roles/storage.admin)

Siga as instruções em Adicionar um principal a uma política no nível do bucket para adicionar a conta de serviço personalizada do Dataform como um principal ao bucket do Cloud Storage que você planeja usar para armazenar a saída de execuções de notebooks programadas e conceda o papel de administrador do Storage a esse principal.

Usuário da conta de serviço (roles/iam.serviceAccountUser)

Siga Conceder uma única função em uma conta de serviço para adicionar a conta de serviço personalizada do Dataform como principal a si mesma. Em outras palavras, adicione a conta de serviço personalizada do Dataform como principal à mesma conta de serviço personalizada do Dataform. Em seguida, conceda o papel de usuário da conta de serviço a esse principal.

Além disso, é necessário conceder o seguinte papel à conta de serviço padrão do Dataform:

Criador do token da conta de serviço (roles/iam.serviceAccountTokenCreator)

Siga as instruções em Conceder acesso à criação de tokens a uma conta de serviço personalizada do Dataform para adicionar a conta de serviço padrão do Dataform como principal à sua conta de serviço personalizada e conceder o papel "Criador de token da conta de serviço" a esse principal.

Para saber mais sobre contas de serviço no Dataform, consulte Sobre as contas de serviço no Dataform.

Criar uma programação

Para programar um notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook que você quer transferir por programação.

3. Clique em Programar.

4. No painel Notebook da programação, no campo Nome da programação, insira um nome para a programação.

5. No campo Modelo de execução, selecione um ambiente de execução.

6. No campo Conta de serviço, selecione uma conta de serviço personalizada do Dataform.

7. No campo Bucket do Cloud Storage, clique em Procurar e selecione ou crie um bucket do Cloud Storage.

   A conta de serviço personalizada do Dataform selecionada precisa receber o papel do IAM "Administrador de armazenamento" no bucket selecionado. Para mais informações, consulte Ativar a programação de notebooks.

8. Na seção Frequência de programação, realize estas ações:

   1. No menu suspenso Repetições, selecione a frequência de execução do bloco de notas programado.
   2. No campo Em horário, insira o horário das execuções programadas do notebook.
   3. No menu suspenso Fuso horário, selecione o fuso horário da programação.

9. Clique em Criar programação.

Quando você cria a programação, a versão atual do notebook é implantada automaticamente. Para atualizar a programação com uma nova versão do notebook, implante o notebook.

A versão mais recente implantada do notebook é executada no horário e na frequência selecionados.

Implantar um notebook

A implantação de um notebook atualiza a programação com a versão atual dele. Os agendamentos executam a versão implantada mais recente do notebook.

Para implantar um notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Implantar.

A programação correspondente é atualizada com a versão atual do notebook. A versão mais recente implantada do notebook é executada no horário programado.

Conferir detalhes da programação

Para conferir os detalhes da programação de um notebook selecionado, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Ver programação.

Exibir execuções antigas

Para conferir as execuções anteriores de uma programação de notebook selecionada, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Ver programação e em Ver execuções anteriores.

Desativar uma programação

Para pausar as execuções programadas de um notebook selecionado sem excluir a programação, desative a programação.

Para desativar uma programação de um notebook selecionado, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Ver programação.

4. Na tabela de detalhes da programação, na linha Estado da programação, clique no botão A programação está ativada.

Ativar uma programação

Para retomar as execuções programadas de uma programação desativada, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Ver programação.

4. Na tabela de detalhes da programação, na linha Estado da programação, clique no botão A programação está desativada.

Editar uma programação

Para editar uma programação, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, a pasta Notebooks compartilhados. Clique no nome do notebook selecionado.

3. Clique em Ver programação e em Editar.

4. Na caixa de diálogo Programar notebook, edite a programação e clique em Atualizar programação.

Conferir todas as programações

Para conferir todas as programações de notebooks no projeto, siga estas etapas:

1. No console do Google Cloud, acesse a página Orquestração.

   Acessar a página Orquestração

2. Opcional: para conferir os detalhes de uma programação selecionada e as execuções anteriores, clique no nome dela.

Excluir uma programação

Para excluir permanentemente uma programação de um notebook selecionado, siga estas etapas:

1. No console do Google Cloud, acesse a página Orquestração.

   Acessar a página Orquestração

2. Na lista de todas as programações, selecione a linha que contém a programação que você quer excluir.

3. Opcional: para excluir várias programações de uma vez, selecione várias linhas.

4. Clique em Excluir.

5. Na caixa de diálogo exibida, clique em Excluir.

Excluir notebooks

Para excluir um notebook, siga estas etapas:

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Notebooks e, se necessário, expanda a pasta Notebooks compartilhados. Encontre o notebook que você quer excluir.

3. Clique em Ver ações ao lado do notebook e clique em Excluir.

4. Para confirmar a exclusão, digite delete na caixa de diálogo.

5. Clique em Excluir.

Solução de problemas

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

A seguir

• Saiba mais sobre os notebooks do Colab Enterprise no BigQuery.
• Saiba como criar notebooks.