Gestire il codice con i repository Git di BigQuery Studio

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per fornire feedback o porre domande relative a questa funzionalità di anteprima, contatta [e-mail].

Puoi gestire gli script SQL e i notebook utilizzando i repository Git di BigQuery Studio. Questa funzionalità integra il controllo della versione direttamente nel browser dei file di BigQuery Studio, consentendoti di clonare i repository, gestire i branch ed eseguire operazioni Git senza uscire dalla Google Cloud console.

I repository Git di BigQuery Studio offrono un'esperienza più semplificata e basata su cartelle rispetto ai repository classici repositories. I repository Git di BigQuery Studio vengono visualizzati direttamente nel riquadro a sinistra sotto la cartella root dell'utente.

Utilizzando i repository Git di BigQuery Studio, puoi interagire con gli asset di codice come se fossero file e directory standard, mantenendo al contempo una connessione a un repository Git remoto.

Limitazioni

• I repository Git di BigQuery Studio sono limitati al contesto della cartella root dell'utente e sono destinati all'uso privato. Non condividere questi repository con altri utenti. Sebbene questi repository vengano visualizzati nella cartella root dell'utente, che è una rappresentazione virtuale degli asset nel progetto, vengono creati tecnicamente a livello di progetto.
• L'utilizzo di un connettore dell'account Developer Connect con un proxy Git non è supportato.
• Le operazioni del file system all'interno della posizione di montaggio consumano la quota di Dataform.
• La clonazione dei repository con un numero elevato di file, file di grandi dimensioni, molti branch o una cronologia dei commit complessa e approfondita richiede più tempo. L'operazione di clonazione potrebbe superare il timeout dell'operazione, impedendo la creazione corretta del repository. Per ridurre il tempo di clonazione dei repository con cronologie dei commit approfondite, puoi creare un clone shallow. Se necessario, puoi recuperare altri commit in un secondo momento.
• Le dimensioni dei file dei notebook archiviati in un montaggio del repository Git di BigQuery Studio non possono superare i 30 MB. Se i file sono più grandi di 30 MB, salvali nella memoria locale del runtime di Colab al di fuori della posizione montata.

• Quando apporti modifiche a un repository Git al di fuori del montaggio, ad esempio modificando o rinominando i file nel riquadro a sinistra, potrebbero essere necessari fino a 60 secondi prima che queste modifiche diventino visibili all'interno del montaggio nel runtime del notebook. Puoi modificare questa durata passando il parametro CACHE_TTL_SECONDS al costruttore:

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  Sostituisci NUMBER con il numero di secondi per la cache deve rimanere valida. La riduzione di questo valore aumenta la frequenza di sincronizzazione e consuma più rapidamente la quota di Dataform.

Prima di iniziare

Abilita l'API Developer Connect nel tuo Google Cloud progetto.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire il codice con i repository Git di BigQuery Studio, chiedi all'amministratore di concederti il ruolo IAM Utente OAuth di Developer Connect (roles/developerconnect.oauthUser) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito include le autorizzazioni necessarie per gestire il codice con i repository Git di BigQuery Studio. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per gestire il codice con i repository Git di BigQuery Studio sono necessarie le seguenti autorizzazioni:

• 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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Considerazioni sulla sicurezza per i repository

Poiché gli asset di codice in BigQuery sono basati su Dataform, devi tenere conto delle seguenti implicazioni per la sicurezza per gli utenti con accesso a questi asset:

• La visibilità degli asset di codice è regolata dalle autorizzazioni di Dataform a livello di progetto. Gli utenti con l'autorizzazione dataform.repositories.list, inclusa nei ruoli BigQuery standard come Utente job BigQuery, Utente BigQuery Studio e Utente BigQuery, possono visualizzare tutti gli asset di codice nel riquadro Explorer del Google Cloud progetto, indipendentemente dal fatto che li abbiano creati o che siano stati condivisi con loro. Per limitare la visibilità, puoi creare ruoli personalizzati che escludono l'autorizzazione dataform.repositories.list.
• Gli utenti che possono modificare questi asset possono potenzialmente accedere a tutti i secret condivisi con l'agente di servizio Dataform. Per proteggere le tue credenziali, limita la creazione e l'accesso in modifica agli utenti attendibili e limita i secret accessibili all'agente di servizio Dataform. Per ulteriori informazioni, consulta Accesso ai secret durante l'installazione del pacchetto.

Per ulteriori informazioni, consulta Considerazioni sulla sicurezza per le autorizzazioni di Dataform.

Creare un repository Git di BigQuery Studio

Quando crei un repository Git, tieni presente questi requisiti:

• La connessione di un repository Git remoto a un repository Git può non riuscire se il repository remoto non è aperto a internet pubblico, ad esempio se si trova dietro un firewall. In questo caso, aggiungi gli intervalli di indirizzi IP di uscita di Dataform richiesti alle regole firewall per consentire le connessioni ai repository remoti protetti.
• Per creare un repository Git connesso a un repository Git remoto non incluso nell'elenco consentito nella policy dell'organizzazione dataform.restrictGitRemotes, aggiungi prima il repository Git remoto all'elenco allowedValues nella policy, quindi crea il repository Git. Per ulteriori informazioni, consulta Limitare i repository remoti.

Per creare un repository Git:

1. Nella Google Cloud console, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file.

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro a sinistra per aprirlo.

3. Accanto al nodo root dell'utente, fai clic su Visualizza azioni > Crea > Repository Git.

4. Inserisci l'URL del repository Git remoto.

5. BigQuery Studio rileva se è disponibile un connettore dell'account Developer Connect esistente. Hai le seguenti opzioni:

   • Se viene trovato un connettore dell'account, il nome visualizzato del repository Git viene precompilato. Puoi modificare questi valori.
   • Se non esiste alcun connettore dell'account, fai clic su Crea connettore dell'account per crearne uno nuovo.
   • Se preferisci non utilizzare un connettore dell'account Developer Connect, fai clic su Utilizza un tipo di connessione diverso per connetterti tramite HTTPS o SSH.

6. (Facoltativo) Per creare un repository di clonazione shallow con una cronologia dei commit limitata, fai clic su Opzioni avanzate e seleziona la casella di controllo Clonazione shallow.

   1. Nel campo Profondità, inserisci il numero di commit da recuperare nella cronologia dei commit limitata.

7. Fai clic su Connetti.

Modificare un file

Per modificare un file, fai clic su un nodo file, ad esempio uno script SQL o un notebook, per aprirlo in una nuova scheda dell'editor.

Le modifiche apportate vengono salvate automaticamente.

Gestione file

Puoi eseguire attività di gestione standard utilizzando il menu Azioni associato a ogni elemento. Per accedere a queste opzioni, fai clic su Apri azioni accanto a qualsiasi directory o file.

A livello di directory, puoi eseguire le seguenti attività:

• Crea nel repository: crea nuovi asset di codice, tra cui query SQL, notebook, canvas di dati, preparazioni dei dati, file o sottodirectory.
• Carica nel repository: importa i file esistenti dalla macchina locale nella directory selezionata.
• Rinomina: modifica il nome della directory.
• Sposta: sposta la directory. Puoi spostare una directory solo in un'altra posizione all'interno dello stesso repository Git. Per ulteriori informazioni, consulta Spostare o copiare file e directory.
• Elimina: rimuovi definitivamente la directory e tutti i relativi contenuti dal tuo workspace locale.

A livello di file, puoi eseguire le seguenti attività:

• Apri o Apri in: visualizza il file nell'editor predefinito o in un'applicazione specifica, ad esempio un ambiente notebook specifico.
• Rinomina: modifica il nome del file.
• Copia: crea un duplicato del file. Puoi copiare i file solo nelle directory all'interno dello stesso repository Git.
• Sposta: sposta il file in un'altra directory all'interno dello stesso repository Git. Per ulteriori informazioni, consulta Spostare o copiare file e directory.
• Scarica: salva una copia del file sulla macchina locale.
• Elimina: rimuovi il file dal workspace.

Spostare o copiare file e directory

Puoi spostare o copiare file e directory, ma devono rimanere all'interno dello stesso repository Git.

1. Nella Google Cloud console, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file.

3. Trova il file o la directory che vuoi spostare o copiare.

4. Fai clic su Apri azioni > Sposta o Copia.

5. Nella finestra di dialogo visualizzata, seleziona la directory di destinazione all'interno dello stesso repository Git.

6. Fai clic su Sposta o Copia.

Eseguire il commit e il push delle modifiche

Per sincronizzare le modifiche locali con il repository remoto:

1. Nella Google Cloud console, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Repository.

3. (Facoltativo) Passa il mouse sopra un file modificato e fai clic su Visualizza diff per visualizzare un confronto riga per riga tra la versione locale e l'ultima versione di cui è stato eseguito il commit.

4. Nel campo Messaggio di commit, inserisci una descrizione delle modifiche.

5. Fai clic su Esegui il commit. Le modifiche vengono salvate nella cronologia Git del branch locale.

6. Fai clic su Esegui il push sul branch remoto. Le modifiche vengono sincronizzate con il repository remoto.

Passare a un nuovo branch

Puoi gestire i branch locali e crearne uno nuovo in base a un branch di monitoraggio locale o remoto esistente.

Nella sezione Branch della scheda Repository puoi visualizzare i branch locali di cui hai eseguito il checkout. L'etichetta CURRENT indica il branch attivo, mentre l'etichetta DEFAULT indica il branch predefinito del repository.

Per eseguire il checkout di un nuovo branch:

1. Nella Google Cloud console, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Repository.

3. Espandi la sezione Branch.

4. Fai clic su Apri azioni accanto a un branch, quindi fai clic su Passa a un nuovo branch.

5. Nel menu Branch di origine , seleziona il branch su cui vuoi basare il nuovo branch, ad esempio origin/main.

6. Nel campo Nome branch, inserisci un nome per il nuovo branch.

   Nota: se hai selezionato un branch di monitoraggio remoto come origine, il campo Nome branch viene precompilato con il nome del branch corrispondente.

7. Fai clic su Checkout. BigQuery Studio esegue prima il checkout del branch di origine. Se il nome del branch fornito indica un nuovo branch, questo viene creato in base all'origine. Il nuovo branch diventa il branch attivo e i contenuti del repository Git vengono aggiornati automaticamente per riflettere lo stato del branch di cui è stato eseguito il checkout.

Visualizzare la cronologia dei commit

Puoi visualizzare la cronologia dei commit per il branch attivo. Se il repository è stato creato come clonazione shallow, il riquadro Cronologia dei commit del branch mostra un banner informativo che indica che la cronologia dei commit del repository è limitata. Puoi espandere la cronologia locale recuperando altri commit.

Per visualizzare la cronologia dei commit:

1. Nella Google Cloud console, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Repository.

3. Accanto al pulsante di azione principale per il controllo della versione, fai clic sul menu a discesa e poi su Visualizza cronologia dei commit.

   Si apre il riquadro Cronologia dei commit del branch, che mostra la cronologia dei commit per il branch attivo.

4. (Facoltativo) Per recuperare altri commit per un repository di clonazione shallow, fai clic su Recupera nel riquadro Cronologia dei commit del branch.

   1. Nella finestra di dialogo Recupera (clonazione shallow), nel campo Commit aggiuntivi da recuperare, inserisci il numero di commit aggiuntivi da recuperare dalla cronologia del repository.

      Se inserisci 0, non vengono recuperati commit storici aggiuntivi, ma BigQuery Studio esegue un recupero standard per sincronizzare i riferimenti e i metadati remoti.

   2. Fai clic su Recupera.

      Puoi ripetere il recupero tutte le volte che è necessario finché non vengono recuperati tutti i commit.

Accedere ai file dei notebook in un montaggio del repository Git

Quando accedi a un notebook da un repository Git di BigQuery Studio, puoi montare il repository Git dell'host nel runtime del notebook. Un montaggio è una connessione che fa apparire il repository Git remoto come se fosse un repository locale nel runtime del notebook. In questo modo, il notebook può accedere, leggere e scrivere direttamente in altri file e script di query all'interno dello stesso repository.

Montare il repository Git

Per montare il repository Git, esegui il seguente codice Python nel notebook:

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Nota: ti consigliamo di eseguire questo codice in una cella di prova di Colab che non viene salvata con il notebook. Per creare una cella di prova, fai clic su Inserisci > Cella di codice di prova.

Quando il notebook è connesso al montaggio, si verificano le seguenti modifiche:

• La directory di lavoro corrente della sessione del notebook viene aggiornata in modo da riflettere il relativo percorso all'interno del repository Git. In questo modo, l'accesso ai file basato sul percorso funziona automaticamente.
• Il percorso del repository Git nel runtime del notebook viene aggiunto al percorso di sistema Python, il che ti consente di utilizzare le istruzioni di importazione Python standard per caricare gli script di query e i file dal repository Git direttamente nel notebook.

Gestire il montaggio e la connessione

Utilizza i seguenti controlli per gestire il workspace:

• Monta workspace: avvia il processo di montaggio per il repository Git. Il montaggio è una risorsa condivisa, quindi se più notebook nello stesso runtime di Colab utilizzano lo stesso repository Git, utilizzano lo stesso montaggio.
• Smonta workspace: interrompe il processo di montaggio per il repository Git. Lo smontaggio del workspace rende il montaggio non disponibile per tutti i notebook nel runtime di Colab che lo utilizzavano.
• Connetti workspace: avvia la connessione a un montaggio attivo per la sessione del notebook corrente. La connessione aggiorna la directory di lavoro e il percorso di sistema del notebook in modo da includere il repository Git, il che ti consente di accedere e importare i file.
• Disconnetti workspace: termina la connessione di montaggio per la sessione del notebook corrente e la reimposta allo stato predefinito. La disconnessione non influisce sullo stato della connessione di montaggio per altre sessioni di notebook attive. Per terminare la connessione della sessione, ti consigliamo di utilizzare il pulsante Disconnetti workspace.
• Ripara: ripristina un montaggio o una connessione a uno stato integro se diventa inutilizzabile.

Dopo aver inizializzato il montaggio, consulta la barra Stato per l'integrità in tempo reale e il percorso attivo del montaggio. Gli stati di integrità possibili sono Connesso, Montato, Arrestato e Non integro.

Passaggi successivi

• Scopri come creare notebook.
• Scopri come creare query salvate.
• Scopri come creare e gestire i repository.
• Scopri come organizzare gli asset di codice con le cartelle.