Gestisci il codice con i repository Git di BigQuery Studio

I repository Git di BigQuery Studio ti consentono di controllare la versione di script SQL, notebook e altri asset di codice direttamente nel browser dei file di BigQuery Studio. Puoi clonare repository Git remoti, gestire i branch ed eseguire operazioni Git senza uscire dalla console Google Cloud .

Rispetto ai repository classici, questa integrazione offre un'esperienza semplificata basata su cartelle nella cartella root dell'utente nel riquadro di sinistra. Puoi interagire con gli asset di codice come 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 dei tuoi asset nel progetto, tecnicamente vengono creati a livello di progetto.
• Le operazioni del file system all'interno della posizione di montaggio consumano la quota di Dataform.
• I repository con un numero elevato di file, file di grandi dimensioni, molti rami o una cronologia dei commit profonda e complessa richiedono più tempo per la clonazione. L'operazione di clonazione potrebbe superare il timeout dell'operazione, impedendo la creazione del repository. Per ridurre il tempo di clonazione dei repository con cronologie dei commit profonde, puoi creare un clone shallow. Se necessario, puoi recuperare altri commit in un secondo momento.
• Le dimensioni dei file dei blocchi note archiviati in un mount del repository Git di BigQuery Studio non possono superare i 30 MB. Se i file sono più grandi di 30 MB, salvali nello spazio di archiviazione 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 di sinistra, possono 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 cui la cache deve rimanere valida. Se riduci questo valore, la frequenza di sincronizzazione aumenta e la quota di Dataform viene consumata più rapidamente.

Prima di iniziare

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

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 Developer Connect OAuth User (roles/developerconnect.oauthUser) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene 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 considerare le seguenti implicazioni di sicurezza per gli utenti con accesso a questi asset:

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

Per saperne di più, consulta Considerazioni sulla sicurezza per le autorizzazioni di Dataform.

Suggerimenti sulla sicurezza per le autorizzazioni di Developer Connect

I repository Git di BigQuery Studio utilizzano Developer Connect per connettersi ai repository remoti. Inoltre, i ruoli BigQuery e Dataform predefiniti includono le autorizzazioni Developer Connect. A causa di queste funzionalità di sicurezza, ti consigliamo di procedere come segue:

• Utilizza ruoli personalizzati per applicare la separazione dei compiti: se la tua organizzazione richiede una separazione rigorosa tra le attività di analisi dei dati e la gestione del codice sorgente, esegui il deployment di ruoli personalizzati che omettono le autorizzazioni di Developer Connect. I ruoli predefiniti come BigQuery User (roles/bigquery.user) e BigQuery Studio User (roles/bigquery.studioUser) includono le autorizzazioni di Developer Connect, che consentono agli utenti con questi ruoli di avviare flussi OAuth e il traffico Git proxy.
• Applica misure di protezione con le policy di negazione IAM: applica policy di negazione a livello di organizzazione per impedire azioni sensibili per gruppi di analisi ampi. Valuta la possibilità di negare l'autorizzazione developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken per impedire l'estrazione dei token e l'autorizzazione developerconnect.googleapis.com/accountConnectors.gitProxyWrite per impedire l'accesso in scrittura non intenzionale ai repository. I ruoli amministrativi, come BigQuery Admin (roles/bigquery.admin) e BigQuery Studio Admin (roles/bigquery.studioAdmin), includono autorizzazioni di accesso ai token che consentono alle entità di recuperare token di gestione del codice sorgente (SCM) di terze parti in testo non crittografato attivi, come i token di installazione dell'app GitHub.
• Isola i progetti CI/CD sensibili: mantieni le pipeline CI/CD sensibili, come Cloud Build o Vertex AI, in progetti Google Cloud dedicati separati dagli ambienti di analisi dei dati generali. Poiché le autorizzazioni di Developer Connect hanno un ambito a livello di progetto, un utente BigQuery in un progetto multi-tenant condiviso può elencare e utilizzare qualsiasi connessione Developer Connect in quel progetto per inviare richieste Git tramite proxy, il che potrebbe concedere l'accesso ai repository configurati per CI/CD o l'automazione dell'infrastruttura.
• Limita l'accesso alle risorse utilizzando le condizioni IAM: associa le condizioni IAM alle associazioni dei ruoli per limitare le autorizzazioni di Developer Connect a risorse specifiche. Puoi limitare l'accesso in base ai prefissi dei nomi delle risorse o definire l'ambito di accesso a risorse Connection e GitRepositoryLink specifiche. In questo modo, gli utenti possono interagire solo con le connessioni Developer Connect destinate ai loro workflow.
• Proteggi i metadati sensibili nei nomi delle risorse: non incorporare credenziali sensibili, nomi in codice dei progetti o informazioni riservate nei nomi dei repository, dei branch o degli ID connessione. Le autorizzazioni necessarie per elencare queste risorse (developerconnect.connections.list e developerconnect.accountConnectors.list) vengono concesse ai ruoli BigQuery standard. Chiunque abbia un accesso di base al progetto può enumerare queste risorse e scoprire metadati sensibili.

Crea un repository Git di BigQuery Studio

Quando crei un repository Git, tieni conto di questi requisiti:

• La connessione di un repository Git remoto a un repository Git può non riuscire se il repository remoto non è aperto alla rete internet pubblica, ad esempio se è protetto da un firewall. In questo caso, aggiungi gli intervalli di indirizzi IP in uscita di Dataform richiesti alle regole firewall per abilitare le connessioni ai repository remoti protetti.
• Per creare un repository Git connesso a un repository Git remoto che non è incluso nella lista consentita della policy dell'organizzazione dataform.restrictGitRemotes, aggiungi prima il repository Git remoto all'elenco allowedValues nella policy, quindi crea il repository Git. Per saperne di più, consulta Limita i repository remoti.

Per creare un repository Git, segui questi passaggi:

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

   Vai a BigQuery

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

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

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

4. Inserisci l'URL del tuo 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 un connettore di account, fai clic su Crea connettore di 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 utilizzando HTTPS o SSH.

     Nota: i repository Git di BigQuery Studio utilizzano i connettori dell'account di Developer Connect anziché le connessioni ai repository Git. Per saperne di più, consulta La differenza tra le connessioni ai repository Git e i connettori degli account.

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

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

7. Fai clic su Connetti.

Modifica un file

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

Tutte 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 Visualizza 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, data canvas, preparazioni di dati, file o sottodirectory.
• Carica nel repository: importa i file esistenti dalla tua 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 saperne di più, consulta Sposta una directory o un file.
• Elimina: rimuovi definitivamente la directory e tutti i relativi contenuti dal tuo workspace locale. Per saperne di più, consulta Elimina una directory o un file.

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

• Apri o Apri con: visualizza il file nell'editor predefinito o in un'applicazione specifica, ad esempio un ambiente notebook specifico.
• Rinomina: modifica il nome file.
• Copia: crea un duplicato del file. Puoi copiare i file solo in directory all'interno dello stesso repository Git. Per saperne di più, consulta Copia un file.
• Sposta: sposta il file in un'altra directory all'interno dello stesso repository Git. Per saperne di più, consulta Sposta una directory o un file.
• Scarica: salva una copia del file sul tuo computer locale.
• Elimina: rimuovi il file dal workspace. Per saperne di più, consulta Elimina una directory o un file.

Sposta una directory o un file

Per spostare una directory o un file in un repository Git di BigQuery Studio, segui questi passaggi:

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

   Vai a BigQuery

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

3. A seconda del numero di risorse che vuoi spostare, esegui una delle seguenti operazioni:

   • Per spostare una singola risorsa, nel browser dei file, seleziona la directory o il file che vuoi spostare, quindi fai clic su Visualizza azioni > Sposta.
   • Per spostare più risorse, nella visualizzazione delle cartelle, seleziona la casella di controllo accanto a ogni risorsa che vuoi spostare, quindi fai clic su Sposta.

4. Nella finestra di dialogo Sposta risorsa, seleziona la directory di destinazione all'interno dello stesso repository Git. Puoi spostare le risorse solo in posizioni all'interno dello stesso repository Git.

5. Fai clic su Sposta.

Nota: le operazioni di spostamento collettivo sono indipendenti. Se lo spostamento di una risorsa non va a buon fine, l'operazione tenta comunque di completare lo spostamento di tutte le altre risorse selezionate.

Copia un file

Per copiare un file in un repository Git di BigQuery Studio, segui questi passaggi:

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

   Vai a BigQuery

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

3. Seleziona il file che desideri copiare.

4. Fai clic su Visualizza azioni > Copia.

5. Nella finestra di dialogo Copia risorsa, seleziona la directory di destinazione all'interno dello stesso repository Git. Puoi copiare i file solo in posizioni all'interno dello stesso repository Git.

6. Fai clic su Copia.

Elimina una directory o un file

Per eliminare una directory o un file in un repository Git di BigQuery Studio, segui questi passaggi:

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

   Vai a BigQuery

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

3. A seconda del numero di risorse che vuoi eliminare, esegui una delle seguenti operazioni:

   • Per eliminare una singola risorsa, nel browser dei file, seleziona la directory o il file che vuoi eliminare, quindi fai clic su Visualizza azioni > Elimina.
   • Per eliminare più risorse, nella visualizzazione cartella, seleziona la casella di controllo accanto a ogni risorsa che vuoi eliminare, quindi fai clic su Elimina.

4. Nella finestra di dialogo di conferma dell'eliminazione, fai clic su Elimina.

Esegui il commit e il push delle modifiche

Per sincronizzare le modifiche locali con il repository remoto, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Controllo del codice sorgente.

3. (Facoltativo) Passa il mouse sopra un file modificato e fai clic su Mostra differenze 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 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.

Passa a un nuovo branch

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

Nel riquadro Controllo del codice sorgente, nella sezione Branch, 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.

Nota: non puoi estrarre un nuovo branch o cambiare branch se hai modifiche non eseguite nel tuo workspace. Devi eseguire il commit delle modifiche prima di cambiare o eseguire il checkout dei branch.

Per eseguire il checkout di un nuovo branch:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Controllo del codice sorgente.

3. Nella sezione Branch, accanto a Branch, fai clic su Azioni > Esegui il checkout del nuovo branch.

4. Nel menu Ramo di origine, seleziona il ramo su cui basare il nuovo ramo, ad esempio origin/main.

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

6. Fai clic su Checkout branch. 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 a quell'origine. Il nuovo branch diventa quello attivo e i contenuti del repository Git vengono aggiornati automaticamente per riflettere lo stato del branch di cui è stato eseguito il checkout.

Per passare a un branch esistente:

1. Nel riquadro Controllo del codice sorgente, espandi la sezione Branch.
2. Accanto al branch a cui vuoi passare, fai clic su Azioni > Passa a BRANCH_NAME.

Visualizza cronologia commit

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

Per visualizzare la cronologia dei commit:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Controllo del codice sorgente.

3. Accanto al pulsante di azione principale per il controllo della versione, fai clic sulla freccia del menu a discesa , quindi su Visualizza cronologia commit.

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

4. (Facoltativo) Per recuperare i commit dal repository remoto, esegui una delle seguenti operazioni:

   • Accanto al pulsante di azione principale per il controllo della versione, fai clic sulla freccia del menu a discesa e poi su Recupera da remoto.
   • Nel riquadro Cronologia dei commit del branch, fai clic su Recupera.

   Per i repository di clonazione shallow, 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 altri commit storici, ma BigQuery Studio esegue un recupero standard per sincronizzare i riferimenti e i metadati remoti.

5. Fai clic su Recupera.

   Puoi ripetere il recupero tutte le volte necessarie fino a quando non vengono recuperati tutti i commit.

Elimina un repository Git

L'eliminazione di un repository Git di BigQuery Studio rimuove il repository e tutti i suoi contenuti dall'ambiente BigQuery Studio.

Per eliminare un repository Git, segui questi passaggi:

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

   Vai a BigQuery

2. Elimina il repository utilizzando uno dei seguenti metodi:

   • Per eliminare il repository dal browser dei file, nel riquadro di sinistra, fai clic su File. Accanto al repository Git che vuoi eliminare, fai clic su Visualizza azioni > Elimina.
   • Per eliminare il repository dal pannello di controllo, nell'intestazione del riquadro Controllo del codice sorgente, fai clic su Opzioni di controllo del codice sorgente > Elimina REPOSITORY_NAME.

3. Nella finestra di dialogo di conferma dell'eliminazione, fai clic su Elimina.

Accedi ai file del blocco note in un mount del repository Git

Quando accedi a un notebook da un repository Git di BigQuery Studio, puoi montare il repository Git host nel runtime del notebook. Un montaggio è una connessione che fa apparire il repository Git remoto come se fosse un repository locale sul 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.

Monta il repository Git

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

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Nota: ti consigliamo di eseguire questo codice in una cella di lavoro 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 è collegato al supporto, si verificano le seguenti modifiche:

• La directory di lavoro corrente della sessione del notebook viene aggiornata in modo da riflettere il suo percorso relativo 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 di Python, il che ti consente di utilizzare le istruzioni di importazione Python standard per caricare script e file di query dal repository Git direttamente nel notebook.

Gestisci il supporto e la connessione

Utilizza i seguenti controlli per gestire l'area di lavoro:

• Monta l'area di lavoro: avvia il processo di montaggio del 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 del repository Git. Lo smontaggio dello spazio di lavoro rende il montaggio non disponibile per tutti i notebook sul 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, che ti consente di accedere ai file e importarli.
• Scollega workspace: termina la connessione di montaggio per la sessione corrente del notebook e la reimposta sullo 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 Scollega area di lavoro.
• Riparazione: ripristina lo stato di integrità di un montaggio o di una connessione se diventano inutilizzabili.

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.