Gérer le code avec les dépôts Git BigQuery Studio

Les dépôts Git BigQuery Studio vous permettent de contrôler les versions des scripts SQL, des notebooks et d'autres éléments de code directement dans l'explorateur de fichiers BigQuery Studio. Vous pouvez cloner des dépôts Git distants, gérer des branches et effectuer des opérations Git sans quitter la console Cloud de Confiance .

Par rapport aux dépôts classiques, cette intégration offre une expérience simplifiée basée sur des dossiers sous votre dossier racine utilisateur dans le volet de gauche. Vous pouvez interagir avec vos composants de code comme des fichiers et des répertoires standards tout en maintenant une connexion à un dépôt Git distant.

Limites

• Les dépôts Git BigQuery Studio sont limités au contexte du dossier racine de l'utilisateur et sont destinés à un usage privé. Ne partagez pas ces dépôts avec d'autres utilisateurs. Bien que ces dépôts apparaissent dans votre dossier racine utilisateur (qui est une représentation virtuelle de vos éléments dans le projet), ils sont techniquement créés au niveau du projet.
• L'utilisation d'un connecteur de compte Developer Connect avec un proxy Git n'est pas possible.
• Les opérations sur le système de fichiers dans l'emplacement d'installation consomment le quota Dataform.
• Les dépôts contenant un grand nombre de fichiers, des fichiers volumineux, de nombreuses branches ou un historique de commit complexe et profond prennent plus de temps à cloner. L'opération de clonage peut dépasser le délai avant expiration, ce qui empêche la création du dépôt. Pour réduire le temps de clonage des dépôts avec un historique de commit étendu, vous pouvez créer un clone superficiel. Vous pourrez récupérer d'autres commits ultérieurement si nécessaire.
• La taille des fichiers de notebook stockés dans un point d'installation de dépôt Git BigQuery Studio ne peut pas dépasser 30 Mo. Si vos fichiers dépassent 30 Mo, enregistrez-les dans l'espace de stockage local de votre environnement d'exécution Colab, en dehors de l'emplacement installé.

• Lorsque vous apportez des modifications à un dépôt Git en dehors de l'installation (par exemple, en modifiant ou en renommant des fichiers dans le volet de gauche), il peut s'écouler jusqu'à 60 secondes avant que ces modifications ne soient visibles dans l'installation de l'environnement d'exécution de votre notebook. Vous pouvez ajuster cette durée en transmettant le paramètre CACHE_TTL_SECONDS au constructeur :

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  Remplacez NUMBER par le nombre de secondes pendant lesquelles le cache doit rester valide. La diminution de cette valeur augmente la fréquence de synchronisation et consomme le quota Dataform plus rapidement.

Avant de commencer

Activez l'API Developer Connect dans votre projet Cloud de Confiance .

Activer l'API

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer le code avec les dépôts Git BigQuery Studio, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur OAuth Developer Connect (roles/developerconnect.oauthUser) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour gérer le code avec les dépôts Git BigQuery Studio. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Points à noter concernant la sécurité des dépôts

Étant donné que les éléments de code dans BigQuery sont fournis par Dataform, vous devez tenir compte des implications de sécurité suivantes pour les utilisateurs ayant accès à ces éléments :

• La visibilité des composants de code est régie par les autorisations Dataform au niveau du projet. Les utilisateurs disposant de l'autorisation dataform.repositories.list (incluse dans les rôles BigQuery standards tels que Utilisateur de job BigQuery, Utilisateur BigQuery Studio et Utilisateur BigQuery) peuvent voir tous les composants de code dans le panneau Explorateur du projet Cloud de Confiance , qu'ils les aient créés ou qu'ils aient été partagés avec eux. Pour restreindre la visibilité, vous pouvez créer des rôles personnalisés qui excluent l'autorisation dataform.repositories.list.
• Tous les secrets partagés avec l'agent de service Dataform sont potentiellement accessibles aux utilisateurs autorisés à modifier ces éléments. Pour sécuriser vos identifiants, limitez l'accès en création et en modification aux utilisateurs de confiance, et limitez les secrets accessibles à l'agent de service Dataform. Pour en savoir plus, consultez Accès aux secrets lors de l'installation du package.

Pour en savoir plus, consultez Remarques sur la sécurité pour les autorisations Dataform.

Créer un dépôt Git BigQuery Studio

Lorsque vous créez un dépôt Git, tenez compte des exigences suivantes :

• La connexion d'un dépôt Git distant à un dépôt Git peut échouer si le dépôt distant n'est pas ouvert à l'Internet public, par exemple s'il se trouve derrière un pare-feu. Dans ce cas, ajoutez les plages d'adresses IP de sortie Dataform requises à vos règles de pare-feu pour autoriser les connexions aux dépôts distants protégés.
• Pour créer un dépôt Git connecté à un dépôt Git distant qui n'est pas autorisé dans la règle d'administration dataform.restrictGitRemotes, ajoutez d'abord le dépôt Git distant à la liste allowedValues de la règle, puis créez le dépôt Git. Pour en savoir plus, consultez Limiter les dépôts distants.

Pour créer un dépôt Git, procédez comme suit :

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur folder Fichiers pour ouvrir l'explorateur de fichiers.

   Si le volet de gauche ne s'affiche pas, cliquez sur last_page Développer le volet de gauche pour l'ouvrir.

3. À côté du nœud racine de l'utilisateur, cliquez sur more_vert Afficher les actions > Créer > Dépôt Git.

4. Saisissez l'URL de votre dépôt Git distant.

5. BigQuery Studio détecte si un connecteur de compte Developer Connect existant est disponible. Vous avez plusieurs options :

   • Si un connecteur de compte est trouvé, le nom à afficher du dépôt Git est prérempli. Vous pouvez modifier ces valeurs.
   • Si aucun connecteur de compte n'existe, cliquez sur Créer un connecteur de compte pour en créer un.
   • Si vous préférez ne pas utiliser de connecteur de compte Developer Connect, cliquez sur Utiliser un autre type de connexion pour vous connecter via HTTPS ou SSH.

6. Facultatif : Pour créer un dépôt de clone superficiel avec un historique des commits limité, cliquez sur Options avancées, puis cochez la case Clone superficiel.

   1. Dans le champ Profondeur, saisissez le nombre de commits à récupérer dans l'historique des commits limité.

7. Cliquez sur Se connecter.

Modifier un fichier

Pour modifier un fichier, cliquez sur un nœud de fichier (par exemple, un script SQL ou un notebook) pour l'ouvrir dans un nouvel onglet de l'éditeur.

Toutes les modifications que vous apportez sont enregistrées automatiquement.

Gérer les fichiers

Vous pouvez effectuer des tâches de gestion standards à l'aide du menu d'actions associé à chaque élément. Pour accéder à ces options, cliquez sur more_vert Ouvrir les actions à côté d'un répertoire ou d'un fichier.

Au niveau du répertoire, vous pouvez effectuer les tâches suivantes :

• Créer dans le dépôt : créez des composants de code, y compris des requêtes SQL, des notebooks, des canevas de données, des préparations de données, des fichiers ou des sous-répertoires.
• Importer dans le dépôt : importez des fichiers existants depuis votre ordinateur local dans le répertoire sélectionné.
• Renommer : modifiez le nom du répertoire.
• Déplacer : déplacez le répertoire. Vous ne pouvez déplacer un répertoire que vers un autre emplacement du même dépôt Git. Pour en savoir plus, consultez Déplacer ou copier des fichiers et des répertoires.
• Supprimer : supprime définitivement le répertoire et tout son contenu de votre espace de travail local.

Au niveau du fichier, vous pouvez effectuer les tâches suivantes :

• Ouvrir ou Ouvrir dans : affichez le fichier dans l'éditeur par défaut ou dans une application spécifique, par exemple un environnement de notebook spécifique.
• Renommer : modifiez le nom du fichier.
• Copier : créez un double du fichier. Vous ne pouvez copier des fichiers que dans des répertoires du même dépôt Git.
• Déplacer : déplacez le fichier vers un autre répertoire du même dépôt Git. Pour en savoir plus, consultez Déplacer ou copier des fichiers et des répertoires.
• Télécharger : enregistrez une copie du fichier sur votre ordinateur local.
• Supprimer : supprimez le fichier de votre espace de travail.

Déplacer ou copier des fichiers et des répertoires

Vous pouvez déplacer ou copier des fichiers et des répertoires, mais ils doivent rester dans le même dépôt Git.

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur folder Fichiers pour ouvrir l'explorateur de fichiers.

3. Recherchez le fichier ou le répertoire que vous souhaitez déplacer ou copier.

4. Cliquez sur more_vert Ouvrir les actions > Déplacer ou Copier.

5. Dans la boîte de dialogue qui s'affiche, sélectionnez le répertoire cible dans le même dépôt Git.

6. Cliquez sur Déplacer ou sur Copier.

Validation et déploiement des modifications

Pour synchroniser vos modifications locales avec votre dépôt distant, procédez comme suit :

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur fork_right Dépôt.

3. Facultatif : pointez sur un fichier modifié, puis cliquez sur Afficher les différences pour afficher une comparaison ligne par ligne entre votre version locale et la dernière version validée.

4. Dans le champ Message de commit, saisissez une description de vos modifications.

5. Cliquez sur Commit. Vos modifications sont enregistrées dans l'historique Git de votre branche locale.

6. Cliquez sur Transférer vers la branche distante. Vos modifications sont synchronisées avec le dépôt distant.

Créer une branche

Vous pouvez gérer les branches locales et en créer une à partir d'une branche de suivi locale ou distante existante.

Dans l'onglet Dépôt, dans la section Branches, vous pouvez voir vos branches locales extraites. Le libellé CURRENT indique votre branche active, et le libellé DEFAULT indique la branche par défaut du dépôt.

Pour extraire une nouvelle branche, procédez comme suit :

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur fork_right Dépôt.

3. Développez la section Branches.

4. Cliquez sur more_vert Ouvrir les actions à côté d'une branche, puis sur Extraire une nouvelle branche.

5. Dans le menu Branche source, sélectionnez la branche sur laquelle vous souhaitez baser votre nouvelle branche, par exemple origin/main.

6. Dans le champ Nom de la branche, saisissez un nom pour la nouvelle branche.

7. Cliquez sur Payer. BigQuery Studio extrait d'abord la branche source. Si le nom de branche fourni indique une nouvelle branche, celle-ci est créée à partir de cette source. La nouvelle branche devient la branche active, et le contenu de votre dépôt Git est automatiquement mis à jour pour refléter l'état de la branche extraite.

Afficher l'historique des validations

Vous pouvez afficher l'historique des commits de votre branche active. Si votre dépôt a été créé en tant que clone superficiel, le volet Historique des commits de la branche affiche une bannière d'information indiquant que le dépôt dispose d'un historique des commits limité. Vous pouvez développer votre historique local en récupérant d'autres commits.

Pour afficher l'historique des commits, procédez comme suit :

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur fork_right Dépôt.

3. À côté du bouton d'action principal du contrôle des versions, cliquez sur la flèche du menu déroulant expander_arrow, puis sur Afficher l'historique des commits.

   Le volet Historique des commits de la branche s'ouvre et affiche l'historique des commits de votre branche active.

4. Facultatif : Pour récupérer des commits supplémentaires pour un dépôt de clone superficiel, dans le volet Historique des commits de la branche, cliquez sur Récupérer.

   1. Dans la boîte de dialogue Récupérer (clone superficiel), dans le champ Commits supplémentaires à récupérer, saisissez le nombre de commits supplémentaires à récupérer à partir de l'historique du dépôt.

      Si vous saisissez 0, aucun commit historique supplémentaire n'est récupéré, mais BigQuery Studio effectue une récupération standard pour synchroniser les références et les métadonnées distantes.

   2. Cliquez sur Récupérer.

      Vous pouvez répéter l'extraction autant de fois que nécessaire jusqu'à ce que tous les commits soient récupérés.

Accéder aux fichiers de notebook dans un point d'installation de dépôt Git

Lorsque vous accédez à un notebook à partir d'un dépôt Git BigQuery Studio, vous pouvez installer le dépôt Git hôte sur l'environnement d'exécution de votre notebook. Un montage est une connexion qui fait apparaître votre dépôt Git distant comme s'il s'agissait d'un dépôt local sur l'environnement d'exécution de votre notebook. Cela permet à votre notebook d'accéder directement à d'autres fichiers et scripts de requête du même dépôt, de les lire et d'y écrire.

Installer le dépôt Git

Pour installer le dépôt Git, exécutez le code Python suivant dans votre notebook :

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Lorsque le notebook est connecté au point d'installation, les modifications suivantes se produisent :

• Le répertoire de travail actuel de la session de notebook est mis à jour pour refléter son chemin relatif dans le dépôt Git. Cela garantit que l'accès aux fichiers basé sur le chemin d'accès fonctionne automatiquement.
• Le chemin d'accès du dépôt Git sur l'environnement d'exécution du notebook est ajouté au chemin d'accès du système Python, ce qui vous permet d'utiliser des instructions d'importation Python standards pour charger des scripts et des fichiers de requête depuis votre dépôt Git directement dans votre notebook.

Gérer l'installation et la connexion

Utilisez les commandes suivantes pour gérer votre espace de travail :

• Installer l'espace de travail : lance le processus d'installation du dépôt Git. Le montage est une ressource partagée. Par conséquent, si plusieurs notebooks sur le même environnement d'exécution Colab utilisent le même dépôt Git, ils utilisent le même montage.
• Démonter l'espace de travail : arrête le processus d'installation du dépôt Git. Le démontage de l'espace de travail rend l'installation indisponible pour tous les notebooks de l'environnement d'exécution Colab qui l'utilisaient.
• Connecter l'espace de travail : démarre la connexion à un point d'installation actif pour la session de notebook actuelle. La connexion met à jour le répertoire de travail et le chemin d'accès système du notebook pour inclure le dépôt Git, ce qui vous permet d'accéder aux fichiers et de les importer.
• Déconnecter l'espace de travail : met fin à la connexion d'installation pour la session de notebook actuelle et la réinitialise à l'état par défaut. La déconnexion n'affecte pas l'état de la connexion d'installation pour les autres sessions de notebook actives. Pour mettre fin à la connexion de votre session, nous vous recommandons d'utiliser le bouton Déconnecter l'espace de travail.
• Réparer : restaure un montage ou une connexion à un état opérationnel s'il devient inutilisable.

Après avoir initialisé l'installation, consultez la barre d'état pour connaître l'état de l'installation et le chemin d'accès actif en temps réel. Les états d'état possibles sont Connecté, Installé, Arrêté et Non opérationnel.

Étapes suivantes

• Apprenez à créer des notebooks.
• Découvrez comment créer des requêtes enregistrées.
• Découvrez comment créer et gérer des dépôts.
• Découvrez comment organiser les composants de code avec des dossiers.