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 Google Cloud .

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.
  • 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 approfondi prennent plus de temps à cloner. L'opération de clonage peut dépasser le délai avant expiration de l'opération, 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 d'installation.

  • 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 plus rapidement le quota Dataform.

Avant de commencer

Activez l'API Developer Connect dans votre projet Google Cloud .

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 :

Autorisations requises

Les autorisations suivantes sont requises pour gérer le code avec les dépôts Git BigQuery Studio :

  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • developerconnect.operations.list
  • developerconnect.operations.get
  • developerconnect.locations.list
  • developerconnect.locations.get
  • developerconnect.users.startOAuth
  • developerconnect.users.finishOAuth
  • developerconnect.users.fetchAccessToken
  • developerconnect.users.getSelf
  • developerconnect.users.deleteSelf
  • developerconnect.accountConnectors.get
  • developerconnect.accountConnectors.list
  • developerconnect.accountConnectors.gitProxyUse
  • developerconnect.accountConnectors.httpProxyUse
  • developerconnect.accountConnectors.gitProxyRead
  • developerconnect.accountConnectors.gitProxyWrite
  • developerconnect.accountConnectors.httpProxyRead
  • developerconnect.accountConnectors.httpProxyWrite
  • developerconnect.accountConnectors.fetchUserRepositories

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 é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, qui est incluse dans les rôles BigQuery standards tels que Utilisateur de job BigQuery, Utilisateur BigQuery Studio et Utilisateur BigQuery, peuvent voir tous les éléments de code dans le panneau Explorateur du projet Google Cloud , qu'ils aient créé ces éléments 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.

Recommandations de sécurité pour les autorisations Developer Connect

Les dépôts Git BigQuery Studio utilisent Developer Connect pour se connecter à des dépôts distants. De plus, les rôles BigQuery et Dataform prédéfinis incluent des autorisations Developer Connect. En raison de ces fonctionnalités de sécurité, nous vous recommandons de procéder comme suit :

  • Utilisez des rôles personnalisés pour appliquer la séparation des tâches : si votre organisation nécessite une séparation stricte entre les tâches d'analyse de données et la gestion du code source, déployez des rôles personnalisés qui omettent les autorisations Developer Connect. Les rôles prédéfinis tels que Utilisateur BigQuery (roles/bigquery.user) et Utilisateur BigQuery Studio (roles/bigquery.studioUser) incluent des autorisations Developer Connect, qui permettent aux utilisateurs auxquels ces rôles sont attribués de démarrer des flux OAuth et de rediriger le trafic Git.
  • Appliquer des garde-fous avec des stratégies de refus IAM : appliquez des stratégies de refus au niveau de l'organisation pour empêcher les actions sensibles pour les groupes d'analyse généraux. Envisagez de refuser l'autorisation developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken pour empêcher l'extraction de jetons et l'autorisation developerconnect.googleapis.com/accountConnectors.gitProxyWrite pour empêcher l'accès en écriture involontaire aux dépôts. Les rôles d'administrateur tels que Administrateur BigQuery (roles/bigquery.admin) et Administrateur BigQuery Studio (roles/bigquery.studioAdmin) incluent des autorisations d'accesseur de jeton qui permettent aux comptes principaux de récupérer des jetons de gestion de code source (SCM) tiers en texte brut actifs, tels que les jetons d'installation de l'application GitHub.
  • Isoler les projets CI/CD sensibles : conservez les pipelines CI/CD sensibles, tels que Cloud Build ou Vertex AI, dans des projets Google Cloud dédiés, distincts des environnements d'analyse de données généraux. Étant donné que les autorisations Developer Connect sont limitées au niveau du projet, un utilisateur BigQuery d'un projet partagé mutualisé peut lister et utiliser n'importe quelle connexion Developer Connect de ce projet pour envoyer des requêtes Git par proxy, ce qui peut lui accorder l'accès aux dépôts configurés pour l'automatisation de l'infrastructure ou de l'intégration/du déploiement continus.
  • Limiter l'accès aux ressources à l'aide de conditions IAM : associez des conditions IAM aux liaisons de rôles pour limiter les autorisations Developer Connect à des ressources spécifiques. Vous pouvez limiter l'accès en fonction des préfixes de nom de ressource ou limiter l'accès à des ressources Connection et GitRepositoryLink spécifiques. Cela garantit que les utilisateurs ne peuvent interagir qu'avec les connexions Developer Connect destinées à leurs workflows.
  • Protégez les métadonnées sensibles dans les noms de ressources : n'intégrez pas d'identifiants sensibles, de noms de code de projet ni d'informations confidentielles dans les noms de dépôts, les noms de branches ou les ID de connexion. Les autorisations requises pour lister ces ressources (developerconnect.connections.list et developerconnect.accountConnectors.list) sont accordées aux rôles BigQuery standards. Toute personne disposant d'un accès de base au projet peut énumérer ces ressources et découvrir des métadonnées sensibles.

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 ne figure pas sur la liste d'autorisation de 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 Restreindre les dépôts distants.

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

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

    Accéder à BigQuery

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

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

  3. À côté du nœud racine de l'utilisateur, cliquez sur 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 :

  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 Afficher 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 un répertoire ou un fichier.
  • Supprimer : supprime définitivement le répertoire et tout son contenu de votre espace de travail local. Pour en savoir plus, consultez Supprimer un répertoire ou un fichier.

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. Pour en savoir plus, consultez Copier un fichier.
  • 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 un répertoire ou un fichier.
  • Télécharger : enregistrez une copie du fichier sur votre ordinateur.
  • Supprimer : supprimez le fichier de votre espace de travail. Pour en savoir plus, consultez Supprimer un répertoire ou un fichier.

Déplacer un répertoire ou un fichier

Pour déplacer un répertoire ou un fichier dans un dépôt Git BigQuery Studio, procédez comme suit :

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

    Accéder à BigQuery

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

  3. Selon le nombre de ressources que vous souhaitez déplacer, effectuez l'une des opérations suivantes :

    • Pour déplacer une seule ressource, dans l'explorateur de fichiers, sélectionnez le répertoire ou le fichier que vous souhaitez déplacer, puis cliquez sur Afficher les actions > Déplacer.
    • Pour déplacer plusieurs ressources, dans la vue des dossiers, cochez la case à côté de chaque ressource que vous souhaitez déplacer, puis cliquez sur Déplacer.

  4. Dans la boîte de dialogue de déplacement de ressource, sélectionnez le répertoire cible dans le même dépôt Git. Vous ne pouvez déplacer des ressources que vers des emplacements situés dans le même dépôt Git.

  5. Cliquez sur Déplacer.

Copier un fichier

Pour copier un fichier dans un dépôt Git BigQuery Studio, procédez comme suit :

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

    Accéder à BigQuery

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

  3. Sélectionnez le fichier que vous voulez copier.

  4. Cliquez sur Afficher les actions > Copier.

  5. Dans la boîte de dialogue de copie de la ressource, sélectionnez le répertoire cible dans le même dépôt Git. Vous ne pouvez copier des fichiers que vers des emplacements situés dans le même dépôt Git.

  6. Cliquez sur Copier.

Supprimer un répertoire ou un fichier

Pour supprimer un répertoire ou un fichier dans un dépôt Git BigQuery Studio, procédez comme suit :

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

    Accéder à BigQuery

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

  3. Selon le nombre de ressources que vous souhaitez supprimer, effectuez l'une des opérations suivantes :

    • Pour supprimer une seule ressource, dans l'explorateur de fichiers, sélectionnez le répertoire ou le fichier que vous souhaitez supprimer, puis cliquez sur Afficher les actions > Supprimer.
    • Pour supprimer plusieurs ressources, dans la vue des dossiers, cochez la case à côté de chaque ressource que vous souhaitez supprimer, puis cliquez sur Supprimer.

  4. Dans la boîte de dialogue de confirmation de la suppression, cliquez sur Supprimer.

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 Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet de gauche, cliquez sur Contrôle de code source.

  3. Facultatif : pointez sur un fichier modifié et 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 le panneau Contrôle de code source, dans la section Branches, vous pouvez voir vos branches locales extraites. L'étiquette CURRENT indique votre branche active, et l'étiquette DEFAULT indique la branche par défaut du dépôt.

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

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

    Accéder à BigQuery

  2. Dans le volet de gauche, cliquez sur Contrôle de code source.

  3. Dans la section Branches, à côté de Branches, cliquez sur Actions > Extraire une nouvelle branche.

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

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

  6. Cliquez sur Créer une branche. 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.

Pour passer à une branche existante, procédez comme suit :

  1. Dans le panneau Contrôle de code source, développez la section Branches.
  2. À côté de la branche vers laquelle vous souhaitez basculer, cliquez sur Actions > Basculer vers BRANCH_NAME.

Afficher l'historique des validations

Vous pouvez afficher l'historique des commits pour 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 davantage de commits.

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

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

    Accéder à BigQuery

  2. Dans le volet de gauche, cliquez sur Contrôle de code source.

  3. À côté du bouton d'action principal du contrôle des versions, cliquez sur la flèche du menu déroulant , 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 à partir du dépôt distant, effectuez l'une des opérations suivantes :

    • À côté du bouton d'action principal du contrôle des versions, cliquez sur la flèche du menu déroulant , puis sur Récupérer à partir d'un dépôt distant.
    • Dans le volet Historique des commits de la branche, cliquez sur Récupérer.

    Pour les dépôts de clones superficiels, 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.

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

Supprimer un dépôt Git

La suppression d'un dépôt Git BigQuery Studio supprime le dépôt et tout son contenu de votre environnement BigQuery Studio.

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

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

    Accéder à BigQuery

  2. Supprimez le dépôt à l'aide de l'une des méthodes suivantes :

    • Pour supprimer le dépôt de l'explorateur de fichiers, cliquez sur Fichiers dans le volet de gauche. À côté du dépôt Git que vous souhaitez supprimer, cliquez sur Afficher les actions > Supprimer.
    • Pour supprimer le dépôt du panneau de configuration, sous l'en-tête du panneau Contrôle des sources, cliquez sur Options de contrôle des sources > Supprimer REPOSITORY_NAME.

  3. Dans la boîte de dialogue de confirmation de la suppression, cliquez sur Supprimer.

Accéder aux fichiers de notebook dans un montage 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. Votre notebook peut ainsi accéder directement à d'autres fichiers et scripts de requête du même dépôt, les lire et 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 du 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, reportez-vous à 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