Gerenciar código com repositórios Git do BigQuery Studio

É possível gerenciar scripts SQL e notebooks usando repositórios Git do BigQuery Studio. Esse recurso integra o controle de versões diretamente ao navegador de arquivos do BigQuery Studio, permitindo clonar repositórios, gerenciar ramificações e realizar operações do Git sem sair do Cloud de Confiance console.

Os repositórios Git do BigQuery Studio oferecem uma experiência mais simplificada e baseada em pastas em comparação com os repositórios clássicos repositories. Os repositórios Git do BigQuery Studio aparecem diretamente no painel esquerdo, na pasta raiz do usuário.

Ao usar os repositórios Git do BigQuery Studio, é possível interagir com os recursos de código como arquivos e diretórios padrão, mantendo uma conexão com um repositório Git remoto.

Limitações

• Os repositórios Git do BigQuery Studio são restritos ao contexto da pasta raiz do usuário e destinados ao uso particular. Não compartilhe esses repositórios com outros usuários. Embora esses repositórios apareçam na pasta raiz do usuário, que é uma representação virtual dos seus recursos no projeto, eles são criados tecnicamente no nível do projeto.
• Não há suporte para o uso de um conector de conta do Developer Connect com um proxy Git.
• As operações do sistema de arquivos no local da montagem consomem a cota do Dataform.
• Os repositórios com um grande número de arquivos, tamanhos de arquivo grandes, muitas ramificações ou um histórico de confirmação profundo e complexo levam mais tempo para serem clonados. A operação de clonagem pode exceder o tempo limite da operação, o que impede a criação do repositório.
• O tamanho dos arquivos de notebook armazenados em uma montagem de repositório Git do BigQuery Studio não pode exceder 30 MB. Se os arquivos forem maiores que 30 MB, salve-os no armazenamento local do ambiente de execução do Colab fora do local montado.

• Quando você faz alterações em um repositório Git fora da montagem, por exemplo, editando ou renomeando arquivos no painel esquerdo, pode levar até 60 segundos para que essas alterações fiquem visíveis na montagem no ambiente de execução do notebook. É possível ajustar essa duração transmitindo o parâmetro CACHE_TTL_SECONDS ao construtor:

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  Substitua NUMBER pelo número de segundos para o cache permaneça válido. Diminuir esse valor aumenta a frequência de sincronização e consome a cota do Dataform mais rapidamente.

Antes de começar

Ative a API Developer Connect no seu Cloud de Confiance projeto.

Ativar a API

Funções exigidas

Para receber as permissões necessárias para gerenciar o código com repositórios Git do BigQuery Studio, peça ao administrador para conceder a você o papel do IAM de usuário OAuth do Developer Connect (roles/developerconnect.oauthUser) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para gerenciar o código com repositórios Git do BigQuery Studio. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Criar um repositório Git do BigQuery Studio

Ao criar um repositório Git, considere estes requisitos:

• A conexão de um repositório Git remoto a um repositório Git pode falhar se o repositório remoto não estiver aberto à Internet pública, por exemplo, se estiver atrás de um firewall. Nesse caso, adicione os intervalos de endereços IP de saída do Dataform necessários às regras de firewall para ativar conexões com repositórios remotos protegidos.
• Para criar um repositório Git conectado a um repositório Git remoto que não está na lista de permissões na política da organização dataform.restrictGitRemotes, primeiro adicione o repositório Git remoto à lista allowedValues na política e, em seguida, crie o repositório Git. Para mais informações, consulte Restringir repositórios remotos.

Para criar um repositório Git, faça o seguinte:

1. No Cloud de Confiance console, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel esquerdo, clique em folder Arquivos para abrir o navegador de arquivos.

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

3. Ao lado do nó raiz do usuário, clique em more_vert Ver ações > Criar > Repositório Git.

4. Insira o URL do repositório Git remoto.

5. O BigQuery Studio detecta se um conector de conta do Developer Connect está disponível. Siga uma destas instruções:

   • Se um conector de conta for encontrado, o nome de exibição do repositório Git será preenchido automaticamente. É possível editar esses valores.
   • Se nenhum conector de conta existir, clique em Criar conector de conta para criar um novo.
   • Se preferir não usar um conector de conta do Developer Connect, clique em Usar outro tipo de conexão para se conectar usando HTTPS ou SSH.

6. Clique em Conectar.

Editar um arquivo

Para editar um arquivo, clique em um nó de arquivo, como um script SQL ou um notebook, para abrir o arquivo em uma nova guia do editor.

Todas as alterações feitas são salvas automaticamente.

Gerenciar arquivos

É possível realizar tarefas de gerenciamento padrão usando o menu de ações associado a cada item. Para acessar essas opções, clique em more_vert Abrir ações ao lado de qualquer diretório ou arquivo.

No nível do diretório, é possível realizar as seguintes tarefas:

• Criar no repositório: crie novos recursos de código, incluindo consultas SQL, notebooks, telas de dados, preparações de dados, arquivos ou subdiretórios.
• Fazer upload para o repositório: importe arquivos da máquina local para o diretório selecionado.
• Renomear: mude o nome do diretório.
• Mover: realoque o diretório. Só é possível mover um diretório para outro local no mesmo repositório Git. Para mais informações, consulte Mover ou copiar arquivos e diretórios.
• Excluir: remova permanentemente o diretório e todo o conteúdo dele do seu espaço de trabalho local.

No nível do arquivo, é possível realizar as seguintes tarefas:

• Abrir ou Abrir em: visualize o arquivo no editor padrão ou em um aplicativo específico, por exemplo, um ambiente de notebook específico.
• Renomear: mude o nome do arquivo.
• Copiar: crie um duplicado do arquivo. Só é possível copiar arquivos para diretórios no mesmo repositório Git.
• Mover: realoque o arquivo para outro diretório no mesmo repositório Git. Para mais informações, consulte Mover ou copiar arquivos e diretórios.
• Fazer download: salve uma cópia do arquivo na máquina local.
• Excluir: remova o arquivo do espaço de trabalho.

Mover ou copiar arquivos e diretórios

É possível mover ou copiar arquivos e diretórios, mas eles precisam permanecer no mesmo repositório Git.

1. No Cloud de Confiance console, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel esquerdo, clique em folder Arquivos para abrir o navegador de arquivos.

3. Encontre o arquivo ou diretório que você quer mover ou copiar.

4. Clique em more_vert Abrir ações > Mover ou Copiar.

5. Na caixa de diálogo que aparece, selecione o diretório de destino no mesmo repositório Git.

6. Clique em Mover ou Copiar.

Confirmar e enviar alterações

Para sincronizar as edições locais com o repositório remoto, faça o seguinte:

1. No Cloud de Confiance console, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel esquerdo, clique em fork_right Repositório.

3. Opcional: passe o cursor sobre um arquivo modificado e clique em Ver diferenças para conferir uma comparação linha por linha entre a versão local e a última versão confirmada.

4. No campo Mensagem de confirmação, insira uma descrição das alterações.

5. Clique em Fazer commit. As alterações são salvas no histórico do Git da ramificação local.

6. Clique em Enviar para ramificação remota. As alterações são sincronizadas com o repositório remoto.

Fazer checkout de uma nova ramificação

É possível gerenciar ramificações locais e criar uma nova ramificação local com base em uma ramificação de rastreamento local ou remota.

Na guia Repositório, na seção Ramificações, é possível conferir as ramificações locais com checkout. O rótulo ATUAL indica a ramificação ativa, e o rótulo PADRÃO indica a ramificação padrão do repositório.

Para fazer checkout de uma nova ramificação, faça o seguinte:

1. No Cloud de Confiance console, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel esquerdo, clique em fork_right Repositório.

3. Expanda a seção Ramificações.

4. Clique em more_vert Abrir ações ao lado de uma ramificação e, em seguida, clique em Fazer checkout de uma nova ramificação.

5. No menu Ramificação de origem, selecione a ramificação em que você quer basear a nova ramificação, por exemplo, origin/main.

6. No campo Nome da ramificação, insira um nome para a nova ramificação.

7. Clique em Fazer checkout. O BigQuery Studio faz checkout da ramificação de origem primeiro. Se o nome da ramificação fornecido indicar uma nova ramificação, ela será criada com base nessa origem. A nova ramificação se torna a ramificação ativa, e o conteúdo do repositório Git é atualizado automaticamente para refletir o estado da ramificação com checkout.

Acessar arquivos de notebook em uma montagem de repositório Git

Ao acessar um notebook em um repositório Git do BigQuery Studio, é possível montar o repositório Git do host no ambiente de execução do notebook. Uma montagem é uma conexão que faz com que o repositório Git remoto apareça como se fosse um repositório local no ambiente de execução do notebook. Isso permite que o notebook acesse, leia e grave diretamente outros arquivos e scripts de consulta no mesmo repositório.

Montar o repositório Git

Para montar o repositório Git, execute o seguinte código Python no notebook:

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Quando o notebook está conectado à montagem, ocorrem as seguintes mudanças:

• O diretório de trabalho atual da sessão do notebook é atualizado para refletir o caminho relativo no repositório Git. Isso garante que o acesso a arquivos com base em caminho funcione automaticamente.
• O caminho do repositório Git no ambiente de execução do notebook é adicionado ao caminho do sistema Python, o que permite usar instruções de importação padrão do Python para carregar scripts de consulta e arquivos do repositório Git diretamente no notebook.

Gerenciar a montagem e a conexão

Use os controles a seguir para gerenciar seu espaço de trabalho:

• Montar espaço de trabalho: inicia o processo de montagem do repositório Git. A montagem é um recurso compartilhado. Portanto, se vários notebooks no mesmo ambiente de execução do Colab usarem o mesmo repositório Git, eles usarão a mesma montagem.
• Desmontar espaço de trabalho: interrompe o processo de montagem do repositório Git. A desmontagem do espaço de trabalho torna a montagem indisponível para todos os notebooks nesse ambiente de execução do Colab que estavam usando.
• Conectar espaço de trabalho: inicia a conexão com uma montagem ativa para a sessão atual do notebook. A conexão atualiza o diretório de trabalho e o caminho do sistema do notebook para incluir o repositório Git, o que permite acessar e importar arquivos.
• Desconectar espaço de trabalho: encerra a conexão de montagem para a sessão atual do notebook e a redefine para o estado padrão. A desconexão não afeta o status da conexão de montagem para outras sessões de notebook ativas. Para encerrar a conexão da sessão, recomendamos usar o botão Desconectar espaço de trabalho.
• Reparar: restaura uma montagem ou conexão para um estado íntegro se ela se tornar inutilizável.

Depois de inicializar a montagem, consulte a barra de Status para conferir a integridade em tempo real e o caminho ativo da montagem. Os estados de integridade possíveis são Conectado, Montado, Interrompido e Não íntegro.

A seguir

• Saiba como criar notebooks.
• Saiba como criar consultas salvas.
• Saiba como criar e gerenciar repositórios.
• Saiba como organizar recursos de código com pastas.