Crea notebook

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

Prima di iniziare

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Autorizzazioni obbligatorie

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

Tutti gli utenti con il ruolo Dataform Admin (roles/dataform.admin) hanno accesso di proprietario a tutti i blocchi note creati nel progetto.

Per ulteriori informazioni su Identity and Access Management (IAM) di BigQuery, consulta Controllo dell'accesso con IAM.

Autorizzazioni per creare blocchi note

Per ottenere le autorizzazioni necessarie per creare ed eseguire blocchi note, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)

• Utente BigQuery Studio (roles/bigquery.studioUser) Il ruolo Utente BigQuery Studio combina i seguenti ruoli IAM:

  • BigQuery Job User (roles/bigquery.jobUser)
  • Utente runtime notebook (roles/aiplatform.notebookRuntimeUser)

  • Code Creator (roles/dataform.codeCreator)

    Nota :gli utenti a cui è stato assegnato il ruolo di 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) Dataform. Gli utenti non amministratori che utilizzano BigQuery Studio possono visualizzare solo gli asset di codice che hanno creato o che sono stati condivisi con loro.

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 blocchi note, 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
Nota:gli utenti che dispongono dell'autorizzazione dataform.repositories.create possono eseguire il codice utilizzando il service account Dataform predefinito e tutte le autorizzazioni concesse a questo account di servizio. Per ulteriori informazioni, consulta Considerazioni sulla sicurezza per le autorizzazioni Dataform.
• 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

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)
• Utente runtime notebook (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)
• Utente runtime notebook (roles/aiplatform.notebookRuntimeUser)
• Visualizzatore di codice (roles/dataform.codeViewer)

Crea notebook

Utilizza le sezioni seguenti per scoprire come creare un blocco note.

Impostare la regione predefinita per gli asset di codice

Se è la prima volta che crei un asset di codice, devi impostare la regione predefinita per gli asset di codice. Non puoi modificare la regione di un asset di codice dopo la creazione.

Nota :se crei un notebook e scegli una regione predefinita diversa da quella che hai utilizzato per gli asset di codice, ad esempio scegliendo us-west1 quando hai utilizzato us-central1, il notebook e tutti gli asset di codice che crei in seguito utilizzano per impostazione predefinita la nuova regione. Gli asset di codice esistenti continuano a utilizzare la regione che è stata loro assegnata al momento della creazione.

Tutti gli asset di codice in BigQuery Studio utilizzano la stessa regione predefinita. Per impostare la regione predefinita per gli asset di codice:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, trova il progetto in cui hai attivato gli asset di codice.

3. Fai clic su Visualizza azioni accanto al progetto, quindi fai clic su Modifica la regione di codice predefinita.

4. Per Regione, seleziona la regione che vuoi utilizzare per gli asset di codice.

5. Fai clic su Seleziona.

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

Crea un notebook utilizzando la galleria di notebook

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Nota: per fornire un feedback o richiedere miglioramenti del prodotto, contatta [e-mail].

La galleria dei blocchi note nella console Google Cloud per BigQuery è il tuo hub centrale per scoprire e utilizzare i modelli di blocchi note predefiniti.

Per creare un blocco note da un modello nella galleria dei blocchi note:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

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

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 rispetto al set di dati pubblico bigquery-public-data.ml_datasets.penguins.

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

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

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

   

   Le funzionalità della barra degli strumenti Dettagli, Cronologia delle versioni e Commenti sono in anteprima. Per fornire un feedback o richiedere assistenza per queste funzionalità, invia un'email all'indirizzo [e-mail].

7. (Facoltativo) Nella barra degli strumenti, 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 pannello contiene anche un elenco di risorse recenti e speciali.

Creare un notebook da una tabella

Per creare un blocco note contenente una query predefinita per una tabella specifica:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

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

4. Fai clic su Panoramica > Tabelle e individua la tabella per cui vuoi eseguire una query.

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

   Si apre il nuovo notebook, 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 blocco note per esplorare il set di risultati di una query:

1. 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 > Blocco note.

   Si apre il nuovo blocco note, contenente celle con il codice per restituire la query SQL 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 Explorer:

   

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

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.

   Una copia del notebook viene aperta come nuovo notebook.

Aggiorna notebook

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

Per caricare un blocco note:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

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

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 del 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 notebook tramite il riquadro Explorer.

Connetti a un runtime

Utilizza le sezioni seguenti per scoprire come connettere un notebook a un runtime di Vertex AI. Un runtime è una risorsa di calcolo che esegue il codice nel notebook. Il runtime deve trovarsi nella stessa regione del notebook.

Per ulteriori informazioni sui runtime, vedi Runtime e modelli 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.

Connettersi 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 Explorer:

   

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

4. Fai clic sul nome di un blocco note per aprirlo.

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

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

Connettersi a un runtime non predefinito

Se vuoi utilizzare un runtime diverso da quello predefinito, devi prima creare il runtime aggiuntivo in Vertex AI.

Per connetterti a un runtime non predefinito:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

4. Fai clic sul nome di un blocco note per aprirlo.

5. Nel blocco note, 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 posizione del notebook.

8. Fai clic su Connetti.

Connettiti a un nuovo runtime

Per connetterti a un nuovo runtime:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

4. Fai clic sul nome di un blocco note per aprirlo.

5. Nel blocco note, 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 Vertex AI da utilizzare.

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

9. Fai clic su Connetti.

Informazioni sulle celle

Un notebook è composto da celle che puoi modificare. Sono supportati i seguenti tipi di celle:

• Cella di testo: utilizza una cella di testo per aggiungere spiegazioni e immagini al notebook in Markdown.
• Cella di codice: utilizza una cella di codice per aggiungere Python al notebook. Puoi eseguire ogni cella di codice singolarmente. Una cella di codice può fare riferimento a qualsiasi variabile creata in un'altra cella che hai già eseguito.

• Cella SQL (anteprima): utilizza una cella SQL per eseguire query GoogleSQL. L'output della query viene salvato automaticamente come DataFrame con lo stesso nome del titolo della cella. Puoi eseguire più istruzioni SQL in una singola cella SQL, ma solo i risultati dell'ultima istruzione vengono salvati in un DataFrame.

  Puoi fare riferimento alle variabili Python nelle espressioni o utilizzare BigQuery DataFrames come tabelle nella query racchiudendo il nome della variabile tra parentesi graffe ({ }):

  # Refer to the Python variable my_threshold in a SQL expression.
  SELECT * FROM my_dataset.my_table WHERE x > {my_threshold};
  
  # Reference previous query results to iterate on your queries.
  SELECT * FROM {df};
  

Concedere l'accesso ai notebook

Per concedere l'accesso a un notebook ad altri utenti, aggiungili a un ruolo IAM appropriato.

Importante: gli utenti che hanno accesso al notebook possono visualizzare tutto l'output generato dal codice nel notebook, anche se l'output contiene dati provenienti da tabelle a cui non hanno accesso. Per impedire la condivisione dell'output salvato, disattiva il salvataggio dell'output del blocco note.

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

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

4. Trova il blocco note a cui vuoi concedere l'accesso.

5. Fai clic su Apri azioni accanto al blocco note, quindi fai clic su Condividi.

6. Nel riquadro Autorizzazioni di condivisione, fai clic su Aggiungi utente/gruppo.

7. Nel campo Nuove entità, inserisci un'entità.

8. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:

   • Proprietario del codice: può eseguire qualsiasi azione sul blocco note, inclusa l'eliminazione o la condivisione.
   • Editor di codice: può modificare il blocco note.
   • Code Viewer: può visualizzare il notebook.
   Nota :il principal deve disporre anche dei ruoli Utente runtime notebook (roles/aiplatform.notebookRuntimeUser) e Utente BigQuery (roles/bigquery.user) per eseguire il notebook.

9. (Facoltativo) Per visualizzare un elenco completo di ruoli e impostazioni di condivisione avanzate, fai clic su Condivisione avanzata.

10. Fai clic su Salva.

11. Per tornare alla pagina delle informazioni del blocco note, fai clic su Chiudi.

Condividere i notebook

Per condividere un notebook con altri utenti, puoi generare e condividere un link al notebook. Affinché altri utenti possano vedere il notebook che condividi, devi prima concedere l'accesso al notebook.

Per eseguire un blocco note, gli utenti devono avere accesso ai dati a cui accede il blocco note. Per saperne di più, vedi Concedere l'accesso a un set di dati.

Importante: gli utenti che hanno accesso al notebook possono visualizzare tutto l'output generato dal codice nel notebook, anche se l'output contiene dati provenienti da tabelle a cui non hanno accesso. Per impedire la condivisione dell'output salvato, disattiva il salvataggio dell'output del blocco note.

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

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

4. Trova il notebook che vuoi condividere. Puoi utilizzare la funzionalità di ricerca o i filtri per trovare il notebook.

5. Fai clic su Visualizza azioni accanto al blocco note, quindi fai clic su Condividi > Copia link.

6. Condividi il link con altri utenti.

Disattivare il salvataggio dell'output del notebook

Puoi impedire la condivisione dell'output del notebook salvato con altri utenti che hanno accesso al file del notebook disattivando il salvataggio dell'output del notebook.

Quando disattivi il salvataggio dell'output per un notebook selezionato, BigQuery elimina tutto l'output salvato nel file del notebook e non salva l'output delle esecuzioni successive.

Tuttavia, gli utenti che hanno accesso al notebook possono comunque visualizzarne l'output nei seguenti modi:

• Esegui il blocco note per visualizzare l'output corrente. Questo output non viene salvato.
• Visualizza una versione di archivio del blocco note e del relativo output nella cronologia delle revisioni.

Per disattivare il salvataggio dell'output per un notebook selezionato:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

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

4. Fai clic sul blocco note per il quale vuoi disattivare il salvataggio dell'output.

5. Per espandere la barra dei menu, fai clic su keyboard_arrow_down Attiva/disattiva visualizzazione intestazione.

6. Fai clic su Modifica > Impostazioni del notebook.

7. Nella finestra Impostazioni notebook, seleziona Escludi output delle celle di codice durante il salvataggio del notebook.

8. Fai clic su Salva.

9. Fai clic su Ricarica.

Risolvi conflitti

Se tu e un altro utente apportate modifiche in conflitto in un notebook, il servizio genera l'errore Automatic saving failed. This file was updated remotely or in another tab. e fornisce un link Show diff. Per risolvere il conflitto, segui questi passaggi:

1. Fai clic sul link Show diff. Si apre la finestra di dialogo Rivedi modifiche da remoto.
2. (Facoltativo) Per confrontare il codice sorgente del notebook, seleziona la casella di controllo Sorgente non elaborata.
3. (Facoltativo) Per confrontare le versioni in linea anziché in riquadri separati, seleziona la casella di controllo Diff in linea.
4. Esamina le modifiche e decidi quali conservare, rivedendo l'input se necessario.
5. Fai clic su Salva modifiche.

Rinominare i notebook

Per rinominare un blocco note:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

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

4. Fai clic sul blocco note che vuoi rinominare.

5. Fai clic su keyboard_arrow_down Attiva/disattiva visualizzazione intestazione per espandere la barra dei menu.

6. Fai clic su File > Rinomina.

7. Nella finestra di dialogo Rinomina blocco note, digita un nome per il blocco note, quindi fai clic su Rinomina.

Risoluzione dei problemi

Per saperne di più, vedi Risolvere i problemi relativi a Colab Enterprise.

Passaggi successivi

• Scopri come gestire i notebook.
• Scopri come pianificare i blocchi note.