Gerenciar notebooks

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

Este documento também descreve como visualizar e gerenciar metadados de notebooks no Knowledge Catalog.

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

Antes de começar

1. Crie um notebook.
2. Para gerenciar metadados de notebooks no Knowledge Catalog, verifique se a API Dataplex está ativada no seu projeto do Google Cloud .

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 mais informações sobre o IAM do BigQuery, consulte Controle de acesso com o IAM.

Para gerenciar metadados de notebooks no Knowledge Catalog, verifique se você tem os papéis necessários do Knowledge Catalog.

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 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 e clique em Notebooks.

4. Encontre o notebook a que você quer conceder acesso.

5. Clique em Abrir ações ao lado do notebook e depois em Compartilhar.

6. No painel Permissões de compartilhamento, clique em Adicionar usuário/grupo.

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

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

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

10. Clique em Salvar.

11. 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 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 e clique em Notebooks.

4. Localize o notebook que você quer compartilhar. Use o recurso de pesquisa ou os filtros para encontrar seu notebook.

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

6. Compartilhe o link com outros usuários.

Desativar o salvamento de saída do notebook

Para evitar o compartilhamento da saída salva do notebook com outros usuários que tenham acesso ao arquivo do notebook, desative o salvamento de saída do notebook.

Quando você desativa o salvamento de saída em um notebook selecionado, o BigQuery exclui todas as saídas salvas no arquivo do notebook e não salva a saída de execuções subsequentes.

No entanto, os usuários com acesso ao notebook ainda poderão visualizar a saída das seguintes maneiras:

• Execute o notebook para conferir a saída atual. Esta saída não foi salva.
• Conferir uma versão de arquivo do notebook e a saída no histórico de revisões.

Para desativar o salvamento da saída de um notebook selecionado, 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 e clique em Notebooks.

4. Clique no notebook em que você quer desativar o salvamento da saída.

5. Para abrir a barra de menus, clique em keyboard_arrow_down Alternar visibilidade do cabeçalho.

6. Clique em Editar > Configurações do notebook.

7. Na janela Configurações do notebook, selecione Omitir saída da célula de código ao salvar este notebook.

8. Clique em Salvar.

9. Clique em Atualizar.

Resolver conflitos

Se você e outro usuário fizerem alterações conflitantes em um notebook, o serviço vai gerar um erro Automatic saving failed. This file was updated remotely or in another tab. e fornecer um link Show diff. Para resolver o conflito, siga estas etapas:

1. Clique no link Show diff. A caixa de diálogo Revisar alterações remotas é aberta.
2. Opcional: para comparar o código-fonte do notebook, marque a caixa de seleção Origem dos dados brutos.
3. Opcional: para comparar as versões inline em vez de em painéis separados, marque a caixa de seleção Diferenças inline.
4. Revise as alterações e decida quais manter, revisando sua entrada, se necessário.
5. Clique em Salvar alterações.

Mostrar todos os blocos

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

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, 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 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 do notebook cujos metadados você quer ver.

5. Consulte os detalhes do 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

É possível criar um notebook dentro ou fora de um repositório. O controle de versões de notebooks é processado de maneira diferente com base no local do notebook.

Controle de versões de notebooks em repositórios

Os repositórios são repositórios Git que residem no BigQuery ou em um provedor terceirizado. É possível usar espaços de trabalho em repositórios para realizar o controle de versões em notebooks. Para mais informações, consulte Usar o controle de versões com um arquivo.

Controle de versões de notebooks fora dos repositórios

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda o projeto e clique em Notebooks. Clique no nome do notebook que tem o histórico de versões que você quer ver.

4. Para ver uma lista das versões do notebook em ordem decrescente por data, clique em Histórico de versões.

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 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 do notebook com as informações de versão que você quer comparar.

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

6. 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 atual.

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

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

9. Opcional: para ocultar a resposta ao comando no notebook, clique em Comparar e desmarque Mostrar resultado.

Restaurar uma versão do notebook

A restauração de uma versão do notebook no 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.

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 do notebook que tem uma versão anterior que você quer restaurar.

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

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

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

8. Clique em Confirmar.

Renomear um notebook

Para renomear 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 o projeto e clique em Notebooks.

4. Clique no notebook que você quer renomear.

5. Clique em keyboard_arrow_down Alternar visibilidade do cabeçalho para abrir a barra de menus.

6. Clique em Arquivo > Renomear.

7. Na caixa de diálogo Renomear notebook, digite um nome para o notebook e clique em Renomear.

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 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 do notebook que você quer baixar. Use o recurso de pesquisa ou os filtros para encontrar seu notebook.

5. Abra a barra de menus e acesse o menu Arquivo:

   

6. Selecione Fazer download e escolha o tipo de arquivo que você quer baixar.

Excluir notebooks

Para excluir 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 o projeto e clique em Notebooks.

4. Encontre o notebook que você quer excluir.

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

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

7. Clique em Excluir.

Gerenciar metadados no Knowledge Catalog

O Knowledge Catalog permite armazenar e gerenciar metadados de notebooks. Os notebooks estão disponíveis no Knowledge Catalog por padrão, sem configuração adicional.

É possível usar o Knowledge Catalog para gerenciar notebooks em todos os locais do BigQuery. O gerenciamento de notebooks no Knowledge Catalog está sujeito às cotas e limites do Knowledge Catalog e aos preços do Knowledge Catalog.

O Knowledge Catalog recupera automaticamente os seguintes metadados de notebooks:

• Nome do recurso de dados
• Ativo de dados pai
• Local do recurso de dados
• Tipo de recurso de dados
• Projeto do Google Cloud correspondente

O Knowledge Catalog registra notebooks como entradas com os seguintes valores:

Grupo de entrada do sistema

O grupo de entrada do sistema para notebooks é @dataform. Para conferir detalhes de entradas de notebook no Knowledge Catalog, acesse o grupo de entradas do sistema dataform. Para instruções sobre como ver uma lista de todas as entradas em um grupo de entradas, consulte Ver detalhes de um grupo de entradas na documentação do Knowledge Catalog.

Tipo de entrada do sistema

O tipo de entrada do sistema para notebooks é dataform-code-asset. Para ver detalhes de notebooks, é necessário visualizar o tipo de entrada do sistema dataform-code-asset, filtrar os resultados com um filtro baseado em aspecto e definir o campo type dentro do aspecto dataform-code-asset como NOTEBOOK. Em seguida, selecione uma entrada do notebook escolhido. Para instruções sobre como ver detalhes de um tipo de entrada selecionado, consulte Ver detalhes de um tipo de entrada na documentação do Knowledge Catalog. Para instruções sobre como ver detalhes de uma entrada selecionada, consulte Ver detalhes de uma entrada na documentação do Knowledge Catalog.

Tipo de aspecto do sistema

O tipo de aspecto do sistema para notebooks é dataform-code-asset. Para fornecer mais contexto aos notebooks no Knowledge Catalog anotando as entradas de notebook com aspectos, visualize o tipo de aspecto dataform-code-asset, filtre os resultados com um filtro baseado em aspecto e defina o campo type dentro do aspecto dataform-code-asset como NOTEBOOK. Para instruções sobre como anotar entradas com aspectos, consulte Gerenciar aspectos e enriquecer metadados na documentação do Knowledge Catalog.

Tipo

O tipo de telas de dados é NOTEBOOK. Esse tipo permite filtrar notebooks no tipo de entrada do sistema dataform-code-asset e no tipo de aspecto dataform-code-asset usando a consulta aspect:dataplex-types.global.dataform-code-asset.type=NOTEBOOK em um filtro baseado em aspecto.

Para instruções sobre como pesquisar recursos no Knowledge Catalog, consulte Pesquisar recursos de dados no Knowledge Catalog na documentação do Knowledge Catalog.

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.
• Saiba como programar notebooks.