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

Vous pouvez gérer les scripts et notebooks SQL à l'aide des dépôts Git BigQuery Studio. Cette fonctionnalité intègre le contrôle des versions directement dans l'explorateur de fichiers BigQuery Studio, ce qui vous permet de cloner des dépôts, de gérer des branches et d'effectuer des opérations Git sans quitter la console Cloud de Confiance .

Les dépôts Git BigQuery Studio offrent une expérience plus simple, basée sur des dossiers, par rapport aux dépôts classiques. Les dépôts Git BigQuery Studio s'affichent directement dans le volet de gauche, sous le dossier racine de votre utilisateur.

En utilisant les dépôts Git BigQuery Studio, vous pouvez interagir avec vos éléments de code comme avec des fichiers et des répertoires standards, tout en conservant 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 le dossier racine de votre utilisateur (qui est une représentation virtuelle de vos composants 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 prise en charge.
• Les opérations du système de fichiers dans le point de montage consomment le quota Dataform.
• Les dépôts comportant un grand nombre de fichiers, des fichiers volumineux, de nombreuses branches ou un historique des commits complexe et détaillé prennent plus de temps à cloner. L'opération de clonage peut dépasser le délai d'expiration de l'opération, ce qui empêche la création du dépôt.
• La taille des fichiers de notebooks stockés dans un montage 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 monté.

• Lorsque vous apportez des modifications à un dépôt Git en dehors du point de montage (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 le point de montage 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 reste valide. Si vous diminuez cette valeur, la fréquence de synchronisation augmente et le quota Dataform est consommé 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.

Considérations de sécurité pour les dépôts

Étant donné que les composants 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 composants :

• 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 limiter la visibilité, vous pouvez créer des rôles personnalisés qui excluent l'autorisation dataform.repositories.list.
• Les utilisateurs qui peuvent modifier ces éléments peuvent potentiellement accéder aux secrets partagés avec l'agent de service Dataform. Pour sécuriser vos identifiants, limitez la création et la modification des accès 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 permettre 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 le règlement de l'organisation dataform.restrictGitRemotes, ajoutez d'abord le dépôt Git distant à la liste allowedValues du règlement, puis créez le dépôt Git. Pour en savoir plus, consultez Restreindre les dépôts distants.

Pour créer un 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.

   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 votre 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 à l'aide de HTTPS ou SSH.

6. Cliquez sur Se connecter.

Modifier un fichier

Pour modifier un fichier, cliquez sur un nœud de fichier (script SQL ou notebook, par exemple) 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 tableaux 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 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 comparer ligne par ligne 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é ACTUEL indique votre branche active, et le libellé PAR DÉFAUT 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 le nom de 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 alors 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.

Accéder aux fichiers notebook dans un montage de dépôt Git

Lorsque vous accédez à un notebook depuis un dépôt Git BigQuery Studio, vous pouvez monter le dépôt Git hôte sur l'environnement d'exécution de votre notebook. Un montage est une connexion qui permet à votre dépôt Git distant d'apparaître 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 dans le même dépôt, de les lire et d'y écrire.

Monter le dépôt Git

Pour monter 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 montage, les modifications suivantes se produisent :

• Le répertoire de travail actuel de la session de notebook est mis à jour pour refléter son chemin d'accès 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 au dépôt Git dans l'environnement d'exécution du notebook est ajouté au chemin d'accès système Python, ce qui vous permet d'utiliser des instructions d'importation Python standards pour charger des scripts de requête et des fichiers depuis votre dépôt Git directement dans votre notebook.

Gérer le montage et la connexion

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

• Monter l'espace de travail : lance le processus de montage 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 de montage du dépôt Git. Le démontage de l'espace de travail rend le montage indisponible pour tous les notebooks de cet environnement d'exécution Colab qui l'utilisaient.
• Connecter l'espace de travail : lance la connexion à un montage actif pour la session de notebook actuelle. La connexion met à jour le répertoire de travail et le chemin 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 de montage pour la session de notebook en cours et la rétablit à l'état par défaut. La déconnexion n'a aucune incidence sur l'état de la connexion du montage pour les autres sessions de notebooks 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é le montage, consultez la barre d'état pour connaître l'état en temps réel et le chemin actif du montage. Les états de santé possibles sont Connecté, Monté, 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.