Crea notebook

Questo documento descrive come creare notebook di Colab Enterprise in BigQuery. Notebooks sono asset di codice di BigQuery Studio basati su Dataform.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Autorizzazioni obbligatorie

Imposta le autorizzazioni appropriate per creare, modificare o visualizzare i notebook.

Tutti gli utenti con il ruolo Amministratore Dataform (roles/dataform.admin) hanno accesso come proprietario a tutti i notebook creati nel progetto.

Per saperne di più su Identity and Access Management (IAM) di BigQuery, consulta Controllo dell'accesso con IAM.

Autorizzazioni per creare notebook

Per ottenere le autorizzazioni necessarie per creare ed eseguire i notebook, chiedi all'amministratore di concederti il ruolo IAM BigQuery Studio User (roles/bigquery.studioUser) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota: gli utenti a cui è stato assegnato il ruolo Code Creator in un progetto possono elencare i nomi degli asset di codice in quel progetto utilizzando l'API Dataform o l'interfaccia a riga di comando (CLI) di Dataform.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti. Per vedere quali sono esattamente le autorizzazioni richieste per creare ed eseguire i notebook, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.list
• dataform.repositories.create
• dataform.repositories.list
• dataform.collections.create
• dataform.collections.list
• aiplatform.notebookRuntimeTemplates.apply
• aiplatform.notebookRuntimeTemplates.get
• aiplatform.notebookRuntimeTemplates.list
• aiplatform.notebookRuntimeTemplates.getIamPolicy
• aiplatform.notebookRuntimes.assign
• aiplatform.notebookRuntimes.get
• aiplatform.notebookRuntimes.list
• aiplatform.operations.list

Nota: quando crei un notebook, BigQuery ti concede il ruolo Amministratore Dataform (roles/dataform.admin) su quel notebook. Tutti gli utenti con il ruolo Amministratore Dataform concesso nel progetto Google Cloud hanno l'accesso come proprietario a tutti i notebook creati nel progetto. Per eseguire l'override di questo comportamento, consulta Concedi un ruolo specifico al momento della creazione della risorsa.

Ruoli per modificare i notebook

Per modificare ed eseguire i notebook, devi disporre dei seguenti ruoli IAM:

• BigQuery Job User (roles/bigquery.jobUser)
• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Editor di codice (roles/dataform.codeEditor)

Ruoli per visualizzare i notebook

Per visualizzare ed eseguire i notebook, devi disporre dei seguenti ruoli IAM:

• BigQuery Job User (roles/bigquery.jobUser)
• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)
• Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
• Code Viewer (roles/dataform.codeViewer)

Considerazioni sulla sicurezza per i notebook

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 notebook

Utilizza le sezioni seguenti per scoprire come creare un notebook.

Imposta la regione predefinita per gli asset di codice

Tutti i nuovi asset di codice nel tuo progetto Google Cloud utilizzano una regione predefinita. Dopo la creazione dell'asset, non puoi modificarne la regione.

Importante: se modifichi la regione durante la creazione di un asset di codice, questa diventa la regione predefinita per tutti gli asset di codice successivi. Gli asset di codice esistenti non sono interessati.

Per impostare la regione predefinita per i nuovi asset di codice, segui questi passaggi:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

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

   

3. Accanto al nome del progetto, fai clic su Visualizza azioni del riquadro dei file > Cambia regione del codice.

4. Seleziona la regione del codice che vuoi utilizzare come predefinita.

5. Fai clic su Salva.

Per un elenco delle regioni supportate, consulta Località di BigQuery Studio.

Crea un notebook utilizzando la galleria di notebook

La galleria di notebook nella console Google Cloud per BigQuery è l'hub centrale per scoprire e utilizzare modelli di notebook predefiniti.

Per creare un notebook da un template nella galleria di notebook, segui questi passaggi:

1. Nella console Google Cloud , vai a BigQuery Studio.

   Vai a BigQuery Studio

2. Per aprire la galleria, nella barra delle schede del riquadro dell'editor, fai clic sulla freccia accanto a Query SQL, quindi fai clic su Notebook > Tutti i template.

3. Nella galleria dei notebook, seleziona un modello. Ad esempio, puoi selezionare Inizia a utilizzare BigQuery DataFrames.

   Si apre il nuovo notebook, contenente celle che mostrano query di esempio sul set di dati pubblico bigquery-public-data.ml_datasets.penguins.

4. In alternativa, puoi fare clic sulla freccia accanto a Query SQL, quindi su Notebook > Notebook vuoto, Notebook > Modello BigQuery o Notebook > Modello Spark per aprire questi modelli specifici.

5. Per creare un notebook eseguibile dal template, fai clic su Utilizza questo template.

6. (Facoltativo) Per visualizzare i dettagli del notebook o la cronologia delle versioni, aggiungere nuovi commenti o rispondere o ottenere un link a un commento esistente, utilizza la seguente barra degli strumenti:

   

   La funzionalità della barra degli strumenti Commenti è in anteprima. Per fornire un feedback o richiedere assistenza per questa funzionalità, invia un'email all'indirizzo [e-mail].

7. (Facoltativo) Nella barra degli strumenti Commenti, puoi utilizzare il riquadro Riferimento per visualizzare l'anteprima dei dettagli dello schema di tabelle, snapshot, viste o viste materializzate oppure aprirli in una nuova scheda. Il riquadro contiene anche un elenco di risorse recenti e speciali.

Crea un notebook da una tabella

Per creare un notebook contenente una query predefinita per una tabella specifica, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

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

3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati, quindi sul set di dati.

4. Fai clic su Panoramica > Tabelle e trova la tabella su cui vuoi eseguire la query.

5. Accanto alla tabella, fai clic su Azioni, quindi su Apri in > Notebook Python.

   Si apre il nuovo blocco note, contenente celle che mostrano query di esempio sulla tabella selezionata.

Crea un notebook per esplorare il set di risultati di una query

Per creare un notebook per esplorare il set di risultati di una query, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro dell'editor, esegui una query che genera un risultato.

3. Nel riquadro Risultati delle query, fai clic su Apri in > Notebook.

   Si apre il nuovo notebook, contenente celle con il codice per restituire l'SQL della query e i risultati della query.

Crea un notebook da un notebook esistente

Per aprire una versione di un notebook esistente come nuovo notebook, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto e fai clic su Notebook.

4. Seleziona un notebook.

5. Fai clic su Cronologia delle versioni.

6. Fai clic su Visualizza azioni accanto a una versione del notebook, quindi fai clic su Apri come nuovo notebook Python.

   Viene aperta una copia del notebook come nuovo notebook.

Aggiorna notebook

Puoi caricare un notebook locale per utilizzarlo in BigQuery Studio. Il notebook caricato è quindi visibile nella pagina BigQuery della console Google Cloud .

Per caricare un notebook, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto, quindi esegui una delle seguenti operazioni:

   • Accanto a Notebook, fai clic su Visualizza azioni > Carica notebook.
   • Accanto al nome del progetto Google Cloud , fai clic su Visualizza azioni > Carica nel progetto > Notebook.

4. Nella finestra di dialogo Carica notebook, nel campo Notebook, fai clic su Sfoglia e seleziona il notebook che vuoi caricare.

5. (Facoltativo) Nel campo Nome notebook, modifica il nome del notebook.

6. Nel campo Regione, seleziona la regione in cui vuoi caricare il notebook.

7. Fai clic su Carica.

Puoi accedere al tuo notebook tramite il riquadro Explorer.

Connettiti a un runtime

Utilizza le sezioni seguenti per scoprire come connettere un notebook a un runtime di Gemini Enterprise Agent Platform. Un runtime è una risorsa di computing che esegue il codice nel tuo notebook. Il runtime deve trovarsi nella stessa regione del notebook.

Per saperne di più sui runtime, consulta Runtime e template di runtime.

Nota: se utilizzi i Controlli di servizio VPC, assicurati di aver configurato l'accesso privato Google con i Controlli di servizio VPC prima di connetterti a un runtime. In caso contrario, il servizio restituisce l'errore Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.

Connettiti al runtime predefinito

Il runtime predefinito è un runtime preimpostato che richiede una configurazione minima.

Per connetterti al runtime predefinito:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto e fai clic su Notebook.

4. Fai clic sul nome di un notebook per aprirlo.

5. Nel blocco note, fai clic su Connetti o esegui una cella qualsiasi.

   La connessione al runtime predefinito potrebbe richiedere diversi minuti se non hai ancora un runtime attivo.

Connettiti a un runtime non predefinito

Se vuoi utilizzare un runtime diverso da quello predefinito, devi prima crearlo in Agent Platform.

Per connetterti al runtime non predefinito:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto e fai clic su Notebook.

4. Fai clic sul nome di un notebook per aprirlo.

5. Nel notebook, fai clic sul menu a discesa accanto a Connetti e poi su Connetti a un runtime.

6. Fai clic su Connetti a un runtime esistente.

7. In Runtime, seleziona il runtime da utilizzare. Il runtime deve trovarsi nella stessa località del notebook.

8. Fai clic su Connetti.

Connettiti a un nuovo runtime

Per connetterti a un nuovo runtime, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto e fai clic su Notebook.

4. Fai clic sul nome di un notebook per aprirlo.

5. Nel notebook, fai clic sul menu a discesa accanto a Connetti e poi su Connetti a un runtime.

6. Fai clic su Crea nuovo runtime.

7. In Modello di runtime, seleziona il modello di runtime di Agent Platform da utilizzare.

8. In Nome runtime, digita un nome per il runtime.

9. Fai clic su Connetti.

Risoluzione dei problemi

Per ulteriori informazioni, consulta Risolvi i problemi di Colab Enterprise.

Passaggi successivi

• Scopri come gestire i notebook.
• Scopri come pianificare i notebook.
• Scopri come accedere ai file dei notebook in un mount del repository Git di BigQuery Studio.