Créer des notebooks

Ce document explique comment créer des notebooks Colab Enterprise dans BigQuery. Les notebooks sont des composants de code BigQuery Studio fournis par Dataform.

Avant de commencer

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery API.

   Enable the API

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery API.

   Enable the API

Activer BigQuery Studio

Suivez les instructions de la page Activer BigQuery Studio pour la gestion des éléments pour enregistrer, partager et gérer des versions d'éléments de code tels que les notebooks.

Autorisations requises

Définissez les autorisations appropriées pour créer, modifier ou afficher des notebooks.

Tous les utilisateurs disposant du rôle Dataform Admin (roles/dataform.admin) disposent d'un accès propriétaire à tous les notebooks créés dans le projet.

Pour en savoir plus sur la gestion de l'authentification et des accès (IAM) dans BigQuery, consultez la page Contrôle des accès avec IAM.

Autorisations de créer des notebooks

Pour créer et exécuter des notebooks, vous avez besoin des autorisations IAM suivantes :

• resourcemanager.projects.get
• resourcemanager.projects.list
• 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

  Remarque : Les utilisateurs disposant de l'autorisation dataform.repositories.create peuvent exécuter du code à l'aide du compte de service Dataform par défaut et de toutes les autorisations accordées à ce compte de service. Pour en savoir plus, consultez la section Remarques sur la sécurité pour les autorisations 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

Vous pouvez obtenir ces autorisations à partir des rôles IAM suivants :

• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)

• Utilisateur BigQuery Studio (roles/bigquery.studioUser)

  Le rôle Utilisateur BigQuery Studio combine les rôles IAM suivants:

  • Utilisateur de job BigQuery (roles/bigquery.jobUser)
  • Utilisateur de l'environnement d'exécution de notebook (roles/aiplatform.notebookRuntimeUser)

  • Créateur de code (roles/dataform.codeCreator)

    Remarque : Les utilisateurs auxquels le rôle de créateur de code est attribué dans un projet peuvent lister les noms des composants de code de ce projet à l'aide de l'API ou de l'interface de ligne de commande (CLI) Dataform. Les utilisateurs sans droits d'administrateur qui utilisent BigQuery Studio ne peuvent voir que les composants de code qu'ils ont créés ou qui ont été partagés avec eux.

Autorisations de modifier les notebooks

Pour modifier et exécuter des notebooks, vous devez disposer des rôles IAM suivants :

• Utilisateur de job BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)
• Utilisateur de l'environnement d'exécution de notebook (roles/aiplatform.notebookRuntimeUser)
• Éditeur de code (roles/dataform.codeEditor)

Autorisations d'afficher les notebooks

Pour afficher et exécuter des notebooks, vous devez disposer des rôles IAM suivants :

• Utilisateur de job BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)
• Utilisateur de l'environnement d'exécution de notebook (roles/aiplatform.notebookRuntimeUser)
• Lecteur de code (roles/dataform.codeViewer)

Créer des notebooks

Utilisez les sections suivantes pour apprendre à créer un notebook.

Définir la région par défaut des composants de code

Si c'est la première fois que vous créez un composant de code, définissez leur région par défaut. Vous ne pouvez pas modifier la région d'un composant de code après sa création.

Remarque : Si vous créez une requête enregistrée et choisissez une région par défaut différente de celle que vous avez utilisée pour les composants de code, choisissez par exemple us-west1 si vous avez utilisé us-central1. Cette requête et tous les composants de code que vous créez par la suite utilisent cette nouvelle région par défaut. Les composants de code existants continuent à utiliser la région qui leur a été attribuée lors de leur création.

Créer un notebook à partir de l'éditeur BigQuery

Pour créer un notebook contenant une requête par défaut pour une table donnée, procédez comme suit :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans la barre d'onglets du volet de l'éditeur, cliquez sur la flèche vers le bas à côté du signe +, puis sur Créer un notebook Python.

   Le nouveau notebook s'ouvre. Il contient des cellules dans lesquelles figurent des exemples de requêtes sur l'ensemble de données public bigquery-public-data.ml_datasets.penguins.

Créer un notebook à partir d'une table

Pour créer un notebook contenant une requête par défaut pour une table particulière, procédez comme suit :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et recherchez la table que vous souhaitez interroger.

3. Cliquez sur Afficher les actions à côté de la table, puis sur Requête dans > Notebook Python.

   Le nouveau notebook s'ouvre. Il contient des cellules dans lesquelles figurent des exemples de requêtes sur la table sélectionnée.

Créer un notebook pour explorer l'ensemble de résultats d'une requête

Pour créer un notebook permettant d'explorer l'ensemble de résultats d'une requête, procédez comme suit :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet de l'éditeur, exécutez une requête qui génère un résultat.

3. Dans le volet Résultats de requête, cliquez sur Explorer les données, puis sur Explorer avec le notebook Python.

   Le nouveau notebook s'ouvre. Il contient des cellules avec du code pour renvoyer la requête SQL et les résultats de la requête.

Créer un notebook à partir d'un notebook existant

Pour ouvrir une version d'un notebook existant en tant que nouveau notebook, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Sélectionnez un notebook.

3. Sélectionnez le volet Activité.

4. Cliquez sur Afficher les actions à côté d'une version de notebook, puis sur Ouvrir en tant que nouveau notebook Python.

   Une copie du notebook est ouverte en tant que nouveau notebook.

Importer des notebooks

Vous pouvez importer un notebook local pour l'utiliser dans BigQuery Studio. Le notebook importé est visible sur la page BigQuery de la console Google Cloud.

Pour importer un notebook, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet, puis effectuez l'une des opérations suivantes :

   • À côté de Notebooks, cliquez sur Afficher les actions > Importer dans Notebooks.
   • À côté du nom du projet Google Cloud, cliquez sur Afficher les actions > Importer dans le projet > Notebook Python.

3. Dans la boîte de dialogue Importer le notebook, dans le champ Notebook, cliquez sur Parcourir, puis sélectionnez le notebook que vous souhaitez importer.

4. Facultatif : Dans le champ Nom du notebook, modifiez le nom du fichier notebook.

5. Dans le champ Région, sélectionnez la région dans laquelle vous souhaitez importer votre notebook.

6. Cliquez sur Importer.

Votre notebook s'affiche dans le volet Explorateur.

Se connecter à un environnement d'exécution

Les sections suivantes vous expliquent comment connecter un notebook à un environnement d'exécution Vertex AI. Un environnement d'exécution est une ressource de calcul qui exécute le code de votre notebook.

Pour en savoir plus sur les environnements d'exécution, consultez la page Environnements d'exécution et modèles d'exécution.

Se connecter à l'environnement d'exécution par défaut

L'environnement d'exécution par défaut est un environnement d'exécution prédéfini qui nécessite une configuration minimale.

Pour vous connecter à l'environnement d'exécution par défaut, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Cliquez sur le nom d'un notebook pour l'ouvrir.

3. Dans le notebook, cliquez sur Connecter ou exécutez n'importe quelle cellule du notebook.

   La connexion à l'environnement d'exécution par défaut peut prendre plusieurs minutes si vous n'avez pas encore d'environnement d'exécution actif.

Se connecter à un environnement d'exécution autre que celui par défaut

Si vous souhaitez utiliser un environnement d'exécution autre que celui par défaut, vous devez d'abord créer cet environnement d'exécution supplémentaire dans Vertex AI.

Pour vous connecter à l'environnement d'exécution par défaut, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Cliquez sur le nom d'un notebook pour l'ouvrir.

3. Dans le notebook, cliquez sur le menu déroulant à côté de Connecter, puis sur Connexion à un environnement d'exécution.

4. Cliquez sur Se connecter à un environnement d'exécution existant.

5. Dans Environnements d'exécution, sélectionnez l'environnement d'exécution à utiliser.

6. Cliquez sur Se connecter.

Se connecter à un nouvel environnement d'exécution

Pour vous connecter à un nouvel environnement d'exécution, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Cliquez sur le nom d'un notebook pour l'ouvrir.

3. Dans le notebook, cliquez sur le menu déroulant à côté de Connecter, puis sur Connexion à un environnement d'exécution.

4. Cliquez sur Créer un environnement d'exécution.

5. Dans Modèle d'exécution, sélectionnez le modèle d'exécution Vertex AI à utiliser.

6. Dans le champ Nom de l'environnement d'exécution, saisissez un nom pour l'environnement d'exécution.

7. Cliquez sur Se connecter.

Accorder l'accès aux notebooks

Pour accorder à d'autres utilisateurs l'accès à un notebook, ajoutez-les à un rôle IAM approprié.

Important : Les utilisateurs ayant accès au notebook peuvent voir tous les résultats générés par le code dans le notebook, même si ces résultats contiennent des données de tables auxquelles ils n'ont pas accès. Pour empêcher le partage de la sortie enregistrée, désactivez l'enregistrement de la sortie du notebook.

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Recherchez le notebook auquel vous souhaitez accorder l'accès.

3. Cliquez sur le bouton Afficher les actions en regard du notebook, puis sur Partager > Gérer les autorisations.

4. Dans le volet Gérer les autorisations, cliquez sur Ajouter un utilisateur/groupe.

5. Dans le champ Nouveaux comptes principaux, saisissez un compte principal.

6. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

   • Propriétaire de code : peut effectuer n'importe quelle action sur le notebook, y compris le supprimer ou le partager.
   • Éditeur de code : peut modifier le notebook.
   • Lecteur de code : peut afficher le notebook.
   Remarque : Le compte principal doit également disposer des rôles Utilisateur de l'environnement d'exécution de notebook (roles/aiplatform.notebookRuntimeUser) et Utilisateur BigQuery (roles/bigquery.user) pour exécuter le notebook.

7. Facultatif : Pour afficher la liste complète des rôles et des paramètres de partage avancés, cliquez sur Partage avancé.

8. Cliquez sur Enregistrer.

9. Pour revenir à la page d'informations sur le notebook, cliquez sur Fermer.

Partager des notebooks

Pour partager un notebook avec d'autres utilisateurs, vous pouvez générer et partager un lien vers celui-ci. Pour que les autres utilisateurs puissent voir le notebook que vous partagez, vous devez d'abord accorder l'accès au notebook.

Pour exécuter un notebook, les utilisateurs doivent avoir accès aux données auxquelles le notebook accède. Pour en savoir plus, consultez la section Accorder l'accès à un ensemble de données.

Important : Les utilisateurs ayant accès au notebook peuvent voir tous les résultats générés par le code dans le notebook, même si ces résultats contiennent des données de tables auxquelles ils n'ont pas accès. Pour empêcher le partage de la sortie enregistrée, désactivez l'enregistrement de la sortie du notebook.

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks, et développez si nécessaire le dossier Notebooks partagés. Recherchez le notebook que vous souhaitez partager.

3. Cliquez sur le bouton Afficher les actions en regard du notebook, puis sur Partager > Copier le lien.

4. Partagez le lien avec d'autres utilisateurs.

Désactiver l'enregistrement de la sortie du notebook

Vous pouvez empêcher le partage de la sortie de notebook enregistrée avec d'autres utilisateurs ayant accès au fichier notebook en désactivant l'enregistrement de la sortie de notebook.

Lorsque vous désactivez l'enregistrement des résultats pour un notebook sélectionné, BigQuery supprime toutes les sorties enregistrées dans le fichier notebook et n'enregistre pas le résultat des exécutions ultérieures.

Toutefois, les utilisateurs qui ont accès au notebook peuvent toujours afficher son résultat des manières suivantes :

• Exécutez le notebook pour afficher ses résultats actuels. Ce résultat n'a pas été enregistré.
• Affichez une version d'archivage du notebook et ses résultats dans l'historique des révisions.

Pour désactiver l'enregistrement des résultats pour un notebook sélectionné, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks, puis sélectionnez le notebook pour lequel vous souhaitez désactiver l'enregistrement du résultat.

3. Cliquez sur Activer/Désactiver la visibilité de l'en-tête > Modifier > Paramètres du notebook.

4. Dans la fenêtre Paramètres du notebook, sélectionnez Exclure la sortie de la cellule de code lors de l'enregistrement de ce notebook.

5. Cliquez sur Enregistrer.

6. Cliquez sur Actualiser.

Résoudre les conflits

Si vous et un autre utilisateur apportez des modifications conflictuelles dans un notebook, le service génère l'erreur Automatic saving failed. This file was updated remotely or in another tab. et fournit un lien Show diff. Pour résoudre le conflit, procédez comme suit :

1. Cliquez sur le lien Show diff. La boîte de dialogue Vérifier les modifications à distance s'ouvre.
2. Facultatif : Pour comparer le code source du notebook, cochez la case Source brute.
3. Facultatif : Pour comparer les versions de manière intégrée plutôt que dans des volets distincts, cochez la case Différences intégrées.
4. Passez en revue les modifications et décidez de celles à conserver, en révisant votre entrée si nécessaire.
5. Cliquez sur Enregistrer les modifications.

Renommer des notebooks

Pour renommer un notebook, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Notebooks et, si nécessaire, le dossier Notebooks partagés. Recherchez le notebook que vous souhaitez renommer.

3. Cliquez sur Afficher les actions à côté du notebook, puis sur Renommer.

4. Saisissez un nom pour le notebook, puis cliquez sur Renommer.

Dépannage

Pour en savoir plus, consultez la page Résoudre les problèmes liés à Colab Enterprise.

Étapes suivantes

• Apprenez à gérer les notebooks.