Gestisci 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à in anteprima, contatta [e-mail].

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 rami 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 principale dell'utente, che è una rappresentazione virtuale dei tuoi asset nel progetto, tecnicamente vengono creati 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.
• I repository con un numero elevato di file, file di grandi dimensioni, molti branch 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 Utente OAuth Developer Connect (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 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.

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

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 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 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, 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 o copia file e directory.
• Elimina: rimuovi definitivamente la directory e tutti i suoi 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 file.
• Copia: crea un duplicato del file. Puoi copiare i file solo in directory all'interno dello stesso repository Git.
• Sposta: sposta il file in un'altra directory all'interno dello stesso repository Git. Per saperne di più, consulta Sposta o copia file e directory.
• Scarica: salva una copia del file sul tuo computer locale.
• Elimina: rimuovi il file dal workspace.

Sposta o copia file e directory

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

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

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

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

Nella scheda Repository, nella sezione Branch, puoi vedere 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 console Google Cloud , 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 Esegui il checkout del nuovo branch.

5. Nel menu Ramo di origine, seleziona il ramo su cui basare il nuovo ramo, 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 Paga. 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 ramo diventa quello attivo e i contenuti del repository Git vengono aggiornati automaticamente per riflettere lo stato del ramo sottoposto a checkout.

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

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

   Viene visualizzato il riquadro Cronologia di commit del branch, che mostra la cronologia di commit per il branch attivo.

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

   1. Nella finestra di dialogo Recupera (clone superficiale), 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.

   2. Fai clic su Recupera.

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

Accedi ai file dei blocchi 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 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.

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 punto di montaggio, 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 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 punto di montaggio è una risorsa condivisa, quindi se più notebook sullo stesso runtime di Colab utilizzano lo stesso repository Git, utilizzano lo stesso punto di 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 workspace.
• Riparazione: ripristina lo stato di integrità di un montaggio o di una connessione se diventano inutilizzabili.

Dopo aver inizializzato il montaggio, consulta la barra di 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.