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

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de 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.

Observação :para enviar feedback ou fazer perguntas relacionadas a esse recurso em pré-lançamento, entre em contato com [e-mail].

Os repositórios Git do BigQuery Studio permitem que você controle as versões de scripts SQL, notebooks e outros recursos de código diretamente no navegador de arquivos do BigQuery Studio. É possível clonar repositórios Git remotos, gerenciar ramificações e realizar operações do Git sem sair do console do Google Cloud .

Em comparação com os repositórios clássicos, essa integração oferece uma experiência simplificada baseada em pastas na pasta raiz do usuário no painel esquerdo. É 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 são 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 é possível usar um conector de conta do Developer Connect com um proxy do Git.
• As operações do sistema de arquivos no local de montagem consomem a cota do Dataform.
• Repositórios com um grande número de arquivos, arquivos 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 que o repositório seja criado. Para reduzir o tempo de clonagem de repositórios com históricos de commit profundos, crie um clone superficial. É possível buscar mais commits depois, se necessá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 tiverem mais de 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 para o construtor:

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  Substitua NUMBER pelo número de segundos em que o cache permanece 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 projeto do Google Cloud .

Ativar a API

Funções exigidas

Para receber as permissões necessárias para gerenciar o código com os repositórios Git do BigQuery Studio, peça ao administrador para conceder a você o papel do IAM de Usuário do 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 código com repositórios Git do BigQuery Studio. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para gerenciar códigos com repositórios Git do BigQuery Studio:

• resourcemanager.projects.get
• resourcemanager.projects.list
• developerconnect.operations.list
• developerconnect.operations.get
• developerconnect.locations.list
• developerconnect.locations.get
• developerconnect.users.startOAuth
• developerconnect.users.finishOAuth
• developerconnect.users.fetchAccessToken
• developerconnect.users.getSelf
• developerconnect.users.deleteSelf
• developerconnect.accountConnectors.get
• developerconnect.accountConnectors.list
• developerconnect.accountConnectors.gitProxyUse
• developerconnect.accountConnectors.httpProxyUse
• developerconnect.accountConnectors.gitProxyRead
• developerconnect.accountConnectors.gitProxyWrite
• developerconnect.accountConnectors.httpProxyRead
• developerconnect.accountConnectors.httpProxyWrite
• developerconnect.accountConnectors.fetchUserRepositories

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

Considerações de segurança para repositórios

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 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 para a 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 permitir conexões com repositórios remotos protegidos.
• Para criar um repositório Git conectado a um repositório Git remoto que não esteja na lista de permissões da 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 console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

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

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

3. Ao lado do nó raiz do usuário, clique em Ver ações > Criar > Repositório do 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 não houver um conector de conta, clique em Criar conector de conta para criar um novo.
   • Se você 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. Opcional: para criar um repositório de clone superficial com histórico de commit limitado, clique em Opções avançadas e marque a caixa de seleção Clone superficial.

   1. No campo Profundidade, insira o número de commits a serem recuperados no histórico limitado.

7. 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 mudanças 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 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 sua máquina local para o diretório selecionado.
• Renomear: mude o nome do diretório.
• Mover: realoca 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: cria uma cópia 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 o download: salve uma cópia do arquivo na sua 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 console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

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

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

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

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

6. Clique em Mover ou Copiar.

Confirmar e enviar mudanças

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

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Repositório.

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

4. No campo Mensagem de commit, insira uma descrição das mudanças.

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

6. Clique em Enviar para ramificação remota. As mudanças 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 com base em uma ramificação de rastreamento local ou remota.

Na guia Repository, na seção Branches, é possível ver as ramificações locais que foram extraídas. O rótulo CURRENT indica a ramificação ativa, e o rótulo DEFAULT indica a ramificação padrão do repositório.

Para verificar uma nova ramificação, faça o seguinte:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Repositório.

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

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

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

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

   Observação: se você selecionou uma ramificação de rastreamento remoto como origem, o campo Branch name será preenchido automaticamente com o nome da ramificação correspondente.

7. Clique em Finalizar compra. O BigQuery Studio verifica primeiro a ramificação de origem. 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 ativa, e o conteúdo do repositório Git é atualizado automaticamente para refletir o estado da ramificação de check-out.

Conferir histórico de confirmação

É possível ver o histórico de commits da ramificação ativa. Se o repositório foi criado como um clone superficial, o painel Histórico de commits da ramificação vai mostrar um banner informativo indicando que o repositório tem um histórico de commits limitado. Você pode expandir o histórico local buscando mais confirmações.

Para ver o histórico de commits, faça o seguinte:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Repositório.

3. Ao lado do botão de ação principal do controle de versões, clique na seta suspensa e em Ver histórico de commits.

   O painel Histórico de commit da ramificação é aberto, mostrando o histórico de commit da sua ramificação ativa.

4. Opcional: para buscar outros commits para um repositório de clone superficial, no painel Histórico de commits da ramificação, clique em Buscar.

   1. Na caixa de diálogo Buscar (clone superficial), no campo Commits adicionais a serem buscados, insira o número de commits adicionais a serem recuperados do histórico do repositório.

      Se você inserir 0, nenhum commit histórico adicional será recuperado, mas o BigQuery Studio vai realizar uma busca padrão para sincronizar referências e metadados remotos.

   2. Clique em Buscar.

      Você pode repetir a busca conforme necessário até que todos os commits sejam recuperados.

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 em 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()

Observação: recomendamos executar esse código em uma célula de rascunho do Colab que não seja salva com o notebook. Para criar uma célula de rascunho, clique em Inserir > Célula de código de rascunho.

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

• 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 baseado 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 e arquivos de consulta do repositório Git diretamente no notebook.

Gerenciar a montagem e a conexão

Use os seguintes controles 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. Ao desmontar o espaço de trabalho, a montagem fica indisponível para todos os notebooks no ambiente de execução do Colab que o 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 da 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 de outras sessões de notebook ativas. Para encerrar a conexão da sessão, recomendamos usar o botão Desconectar espaço de trabalho.
• Reparo: 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 ver 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.