BigQuery Studio Git リポジトリでコードを管理する

BigQuery Studio Git リポジトリを使用すると、BigQuery Studio ファイル ブラウザで SQL スクリプト、ノートブック、その他のコードアセットを直接バージョン管理できます。 Google Cloud コンソールを離れることなく、リモート Git リポジトリのクローン作成、ブランチの管理、Git オペレーションの実行を行うことができます。

従来のリポジトリと比較して、この統合では、左側のペインのユーザー ルートフォルダの下に、フォルダベースの合理化されたエクスペリエンスが提供されます。リモート Git リポジトリへの接続を維持しながら、標準のファイルやディレクトリなどのコードアセットを操作できます。

制限事項

  • BigQuery Studio Git リポジトリは、ユーザーのルートフォルダ コンテキストに制限されており、非公開での使用を目的としています。これらのリポジトリを他のユーザーと共有しないでください。これらのリポジトリは、プロジェクト内のアセットを仮想的に表すユーザー ルート フォルダに表示されますが、技術的にはプロジェクト レベルで作成されます。
  • マウント場所内のファイル システム オペレーションは、Dataform の割り当てを消費します。
  • ファイル数が多い、ファイルサイズが大きい、ブランチが多い、コミット履歴が深く複雑なリポジトリは、クローン作成に時間がかかります。クローン作成オペレーションがオペレーション タイムアウトを超え、リポジトリが正常に作成されないことがあります。コミット履歴が深いリポジトリのクローン作成時間を短縮するには、シャロー クローンを作成します。必要に応じて、後でさらに commit を取得できます。
  • BigQuery Studio Git リポジトリ マウントに保存されるノートブック ファイルのサイズは 30 MB を超えることはできません。ファイルが 30 MB を超える場合は、マウントされた場所の外にある Colab ランタイムのローカル ストレージに保存します。

  • マウントの外部で Git リポジトリに変更を加える場合（左側のペインでファイルを編集または名前変更する場合など）、ノートブックのランタイムのマウント内に変更が表示されるまでに最大 60 秒かかることがあります。この期間は、CACHE_TTL_SECONDS パラメータをコンストラクタに渡すことで調整できます。

      FuseWidget(CACHE_TTL_SECONDS=NUMBER)

    NUMBER は、キャッシュが有効なままになる秒数に置き換えます。この値を小さくすると、同期の頻度が増加し、Dataform の割り当てがより早く消費されます。

始める前に

Google Cloud プロジェクトで Developer Connect API を有効にします。

API を有効化

必要なロール

BigQuery Studio Git リポジトリでコードを管理するために必要な権限を取得するには、プロジェクトに対する Developer Connect OAuth ユーザー （roles/developerconnect.oauthUser）の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、BigQuery Studio Git リポジトリでコードを管理するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

BigQuery Studio Git リポジトリでコードを管理するには、次の権限が必要です。

  • 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

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

リポジトリのセキュリティに関する考慮事項

BigQuery のコードアセットは Dataform を利用しているため、これらのアセットにアクセスできるユーザーに対して、次のセキュリティ上の影響を考慮する必要があります。

  • コードアセットの可視性は、プロジェクト レベルの Dataform 権限に則って管理されます。dataform.repositories.list 権限（BigQuery ジョブユーザー、BigQuery Studio ユーザー、BigQuery ユーザーなどの標準の BigQuery ロールに含まれる）を持つユーザーは、 Google Cloud プロジェクトの [エクスプローラ] パネルですべてのコードアセットを表示できます。これらのアセットを作成したかどうか、またはこれらのアセットが共有されているかどうかは関係ありません。可視性を制限するには、dataform.repositories.list 権限を除外するカスタムロールを作成します。
  • Dataform サービス エージェントと共有されているシークレットには、これらのアセットを編集できるユーザーがアクセスできる可能性があります。認証情報を保護するには、信頼できるユーザーに作成権限と編集権限を制限し、Dataform サービス エージェントがアクセスできるシークレットを制限します。詳細については、パッケージのインストール中のシークレットへのアクセスをご覧ください。

詳細については、Dataform 権限のセキュリティに関する考慮事項をご覧ください。

Developer Connect の権限に関するセキュリティの推奨事項

BigQuery Studio Git リポジトリは、Developer Connect を使用してリモート リポジトリに接続します。また、事前定義された BigQuery ロールと Dataform ロールには、Developer Connect 権限が含まれています。これらのセキュリティ機能により、次のことをおすすめします。

  • カスタムロールを使用して職務分掌を適用する: 組織でデータ分析タスクとソースコード管理を厳密に分離する必要がある場合は、Developer Connect 権限を省略したカスタムロールをデプロイします。BigQuery ユーザー（roles/bigquery.user）や BigQuery Studio ユーザー（roles/bigquery.studioUser）などの事前定義ロールには、Developer Connect 権限が含まれています。これらのロールが割り当てられたユーザーは、OAuth フローを開始して Git トラフィックをプロキシできます。
  • IAM 拒否ポリシーでガードレールを適用する: 組織レベルの拒否ポリシーを適用して、広範な分析グループに対する機密性の高いアクションを防止します。トークンの抽出を防ぐために developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken 権限を拒否し、リポジトリへの意図しない書き込みアクセスを防ぐために developerconnect.googleapis.com/accountConnectors.gitProxyWrite 権限を拒否することを検討してください。BigQuery 管理者（roles/bigquery.admin）や BigQuery Studio 管理者（roles/bigquery.studioAdmin）などの管理ロールには、GitHub アプリのインストール トークンなど、アクティブな平文のサードパーティ ソースコード管理（SCM）トークンをプリンシパルが取得できるようにするトークン アクセサー権限が含まれています。
  • 機密性の高い CI / CD プロジェクトを分離する: Cloud Build や Vertex AI などの機密性の高い CI / CD パイプラインは、一般的なデータ分析環境から分離された専用の Google Cloud プロジェクトに保持します。Developer Connect の権限はプロジェクト レベルでスコープされるため、共有のマルチテナント プロジェクトの BigQuery ユーザーは、そのプロジェクト内の任意の Developer Connect 接続を一覧表示して使用し、Git リクエストをプロキシできます。これにより、CI/CD またはインフラストラクチャ自動化用に構成されたリポジトリへのアクセス権が付与される可能性があります。
  • IAM Conditions を使用してリソースへのアクセスを制限する: IAM Conditions をロール バインディングに接続して、Developer Connect の権限を特定のリソースに制限します。リソース名の接頭辞に基づいてアクセスを制限したり、特定の Connection リソースと GitRepositoryLink リソースにアクセスを制限したりできます。これにより、ユーザーはワークフローを対象とする Developer Connect 接続のみを操作できます。
  • リソース名の機密メタデータを保護する: 機密性の高い認証情報、プロジェクトのコードネーム、機密情報をリポジトリ名、ブランチ名、接続 ID に埋め込まないでください。これらのリソースを一覧表示するために必要な権限（developerconnect.connections.list と developerconnect.accountConnectors.list）は、標準の BigQuery ロールに付与されます。基本的なプロジェクト アクセス権を持つユーザーは、これらのリソースを列挙して機密性の高いメタデータを検出できます。

BigQuery Studio Git リポジトリを作成する

Git リポジトリを作成する際は、次の要件を考慮してください。

  • リモート Git リポジトリが公共のインターネットに開かれていない場合（例: ファイアウォールの内側にある場合）、リモート Git リポジトリを Git リポジトリに接続できないことがあります。この場合は、必要な Dataform 外向き IP アドレス範囲をファイアウォール ルールに追加して、保護されたリモート リポジトリへの接続を有効にします。
  • dataform.restrictGitRemotes 組織のポリシーで許可リストに登録されていないリモート Git リポジトリに接続する Git リポジトリを作成するには、まずリモート Git リポジトリをポリシーの allowedValues リストに追加してから、Git リポジトリを作成します。詳細については、リモート リポジトリを制限するをご覧ください。

Git リポジトリを作成するには、次の操作を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで [ファイル] をクリックして、ファイル ブラウザを開きます。

    左側のペインが表示されていない場合は、 左ペインを開くをクリックしてペインを開きます。

  3. ユーザーのルートノードの横にある （アクションを表示）> [作成] > [Git リポジトリ] をクリックします。

  4. リモート Git リポジトリの URL を入力します。

  5. BigQuery Studio は、既存の Developer Connect アカウント コネクタが使用可能かどうかを検出します。以下のいずれかをご検討ください。

    • アカウント コネクタが見つかった場合、Git リポジトリの表示名が事前入力されます。これらの値は編集できます。
    • アカウント コネクタが存在しない場合は、[アカウント コネクタを作成] をクリックして、新しいアカウント コネクタを作成します。

    • Developer Connect アカウント コネクタを使用しない場合は、[別の接続タイプを使用する] をクリックして、HTTPS または SSH を使用して接続します。

  6. 省略可: commit 履歴が制限されたシャロー クローン リポジトリを作成するには、[詳細オプション] をクリックし、[シャロー クローン] チェックボックスをオンにします。

    1. [Depth] フィールドに、制限付きの commit 履歴で取得する commit の数を入力します。

  7. [接続] をクリックします。

ファイルの編集

ファイルを編集するには、SQL スクリプトやノートブックなどのファイルノードをクリックして、新しいエディタタブでファイルを開きます。

変更内容はすべて自動的に保存されます。

ファイルの管理

各アイテムに関連付けられた操作メニューを使用して、標準的な管理タスクを実行できます。これらのオプションにアクセスするには、ディレクトリまたはファイルの横にある [アクションを表示] をクリックします。

ディレクトリ レベルでは、次のタスクを実行できます。

  • リポジトリに作成: SQL クエリ、ノートブック、データ キャンバス、データ準備、ファイル、サブディレクトリなどの新しいコードアセットを作成します。
  • リポジトリにアップロード: ローカルマシンから選択したディレクトリに既存のファイルをインポートします。
  • 名前を変更: ディレクトリの名前を変更します。
  • 移動: ディレクトリを移動します。ディレクトリは、同じ Git リポジトリ内の別の場所にのみ移動できます。詳細については、ディレクトリまたはファイルを移動するをご覧ください。
  • 削除: ディレクトリとそのすべてのコンテンツをローカル ワークスペースから完全に削除します。詳細については、ディレクトリまたはファイルを削除するをご覧ください。

ファイルレベルでは、次のタスクを実行できます。

  • 開くまたは開く: デフォルトのエディタまたは特定のアプリケーション（特定のノートブック環境など）でファイルを表示します。
  • 名前を変更: ファイル名を変更します。
  • コピー: ファイルのコピーを作成します。ファイルをコピーできるのは、同じ Git リポジトリ内のディレクトリのみです。詳細については、ファイルをコピーするをご覧ください。
  • 移動: 同じ Git リポジトリ内の別のディレクトリにファイルを移動します。詳細については、ディレクトリまたはファイルを移動するをご覧ください。
  • ダウンロード: ファイルのコピーをローカルマシンに保存します。
  • 削除: ワークスペースからファイルを削除します。詳細については、ディレクトリまたはファイルを削除するをご覧ください。

ディレクトリまたはファイルを移動する

BigQuery Studio Git リポジトリ内のディレクトリまたはファイルを移動するには、次の操作を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで [ファイル] をクリックして、ファイル ブラウザを開きます。

  3. 移動するリソースの数に応じて、次のいずれかを行います。

    • 単一のリソースを移動するには、ファイル ブラウザで移動するディレクトリまたはファイルを選択し、（アクションを表示）> [移動] をクリックします。
    • 複数のリソースを移動するには、フォルダビューで、移動する各リソースの横にあるチェックボックスをオンにして、[移動] をクリックします。

  4. リソースの移動ダイアログで、同じ Git リポジトリ内のターゲット ディレクトリを選択します。リソースは、同じ Git リポジトリ内のロケーションにのみ移動できます。

  5. [移動] をクリックします。

ファイルをコピーする

BigQuery Studio Git リポジトリ内のファイルをコピーする手順は次のとおりです。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで [ファイル] をクリックして、ファイル ブラウザを開きます。

  3. コピーするファイルを選択します。

  4. [アクションを表示] > [コピー] をクリックします。

  5. リソースのコピー ダイアログで、同じ Git リポジトリ内のターゲット ディレクトリを選択します。ファイルをコピーできるのは、同じ Git リポジトリ内の場所のみです。

  6. [コピー] をクリックします。

ディレクトリまたはファイルを削除する

BigQuery Studio Git リポジトリ内のディレクトリまたはファイルを削除するには、次の操作を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで [ファイル] をクリックして、ファイル ブラウザを開きます。

  3. 削除するリソースの数に応じて、次のいずれかを行います。

    • 単一のリソースを削除するには、ファイル ブラウザで削除するディレクトリまたはファイルを選択し、（アクションを表示）> [削除] をクリックします。
    • 複数のリソースを削除するには、フォルダビューで、削除する各リソースの横にあるチェックボックスをオンにして、[削除] をクリックします。

  4. 削除の確認ダイアログで、[削除] をクリックします。

変更を commit して push する

ローカルの編集内容をリモート リポジトリと同期する手順は次のとおりです。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで、 [ソース管理] をクリックします。

  3. 省略可: 変更されたファイルにカーソルを合わせ、[差分を表示] をクリックして、ローカル バージョンと最後に commit されたバージョンを 1 行ずつ比較します。

  4. [commit メッセージ] フィールドに、変更の説明を入力します。

  5. [Commit] をクリックします。変更はローカル ブランチの Git 履歴に保存されます。

  6. [リモートに push] をクリックします。変更はリモート リポジトリと同期されます。

新しいブランチをチェックアウトする

ローカル ブランチを管理し、既存のローカル ブランチまたはリモート トラッキング ブランチに基づいて新しいローカル ブランチを作成できます。

[ソース管理] パネルの [ブランチ] セクションに、チェックアウトされたローカル ブランチが表示されます。CURRENT ラベルはアクティブなブランチを示し、DEFAULT ラベルはリポジトリのデフォルト ブランチを示します。

新しいブランチをチェックアウトするには、次の操作を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで、 [ソース管理] をクリックします。

  3. [ブランチ] セクションで、[ブランチ] の横にある [アクション] > [新しいブランチをチェックアウト] をクリックします。

  4. [ソースブランチ] メニューで、新しいブランチのベースにするブランチ（origin/main など）を選択します。

  5. [ブランチ名] フィールドに、新しいブランチの名前を入力します。

  6. [Checkout branch] をクリックします。BigQuery Studio は、まずソース ブランチをチェックアウトします。指定されたブランチ名が新しいブランチを示している場合は、そのソースに基づいて作成されます。新しいブランチがアクティブ ブランチになり、Git リポジトリの内容が自動的に更新され、チェックアウトされたブランチの状態が反映されます。

既存のブランチに切り替えるには、次の操作を行います。

  1. [ソース管理] パネルで、[ブランチ] セクションを開きます。
  2. 切り替えるブランチの横にある [アクション] > [BRANCH_NAME に切り替える] をクリックします。

commit 履歴を表示

アクティブなブランチの commit 履歴を表示できます。リポジトリがシャロー クローンとして作成された場合、[ブランチの commit 履歴] ペインに、リポジトリの commit 履歴が制限されていることを示す情報バナーが表示されます。より多くの commit をフェッチすることで、ローカルの履歴を拡張できます。

commit 履歴を表示する手順は次のとおりです。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 左側のペインで、 [ソース管理] をクリックします。

  3. メインのバージョン管理操作ボタンの横にある 矢印プルダウンをクリックし、[commit 履歴を表示] をクリックします。

    [ブランチの commit 履歴] ペインが開き、アクティブなブランチの commit 履歴が表示されます。

  4. 省略可: リモート リポジトリから commit を取得するには、次のいずれかを行います。

    • メインのバージョン管理操作ボタンの横にある 矢印プルダウンをクリックし、[リモートからフェッチ] をクリックします。
    • [ブランチの commit 履歴] ペインで、[フェッチ] をクリックします。

    シャロー クローン リポジトリの場合は、[フェッチ（シャロー クローン）] ダイアログの [フェッチする追加の commit] フィールドに、リポジトリ履歴から取得する追加の commit の数を入力します。

    0 を入力すると、追加の履歴 commit は取得されませんが、BigQuery Studio は標準のフェッチを実行して、リモート参照とメタデータを同期します。

  5. [Fetch] をクリックします。

    すべての commit が取得されるまで、必要に応じてフェッチを繰り返すことができます。

Git リポジトリを削除する

BigQuery Studio Git リポジトリを削除すると、リポジトリとそのすべてのコンテンツが BigQuery Studio 環境から削除されます。

Git リポジトリを削除する手順は次のとおりです。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. 次のいずれかの方法でリポジトリを削除します。

    • ファイル ブラウザからリポジトリを削除するには、左側のペインで [ファイル] をクリックします。削除する Git リポジトリの横にある [アクションを表示] > [削除] をクリックします。
    • コントロール パネルからリポジトリを削除するには、[ソース管理] パネル ヘッダーで、 [ソース管理オプション] > [REPOSITORY_NAME を削除] をクリックします。

  3. 削除の確認ダイアログで、[削除] をクリックします。

Git リポジトリ マウント内のノートブック ファイルにアクセスする

BigQuery Studio Git リポジトリ内からノートブックにアクセスすると、ホスト Git リポジトリをノートブックのランタイムにマウントできます。マウントは、リモート Git リポジトリをノートブックのランタイムのローカル リポジトリのように表示する接続です。これにより、ノートブックは同じリポジトリ内の他のファイルやクエリ スクリプトに直接アクセスして、読み取りと書き込みを行うことができます。

Git リポジトリをマウントする

Git リポジトリをマウントするには、ノートブックで次の Python コードを実行します。

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

ノートブックがマウントに接続されると、次の変更が行われます。

  • ノートブック セッションの現在の作業ディレクトリが更新され、Git リポジトリ内の相対パスが反映されます。これにより、パスベースのファイル アクセスが自動的に機能します。
  • ノートブックのランタイム上の Git リポジトリのパスが Python システムパスに追加されます。これにより、標準の Python インポート ステートメントを使用して、Git リポジトリからノートブックにクエリ スクリプトとファイルを直接読み込むことができます。

マウントと接続を管理する

ワークスペースを管理するには、次のコントロールを使用します。

  • ワークスペースをマウントする: Git リポジトリのマウント プロセスを開始します。マウントは共有リソースであるため、同じ Colab ランタイム上の複数のノートブックが同じ Git リポジトリを使用する場合、同じマウントを使用します。
  • ワークスペースのマウントを解除: Git リポジトリのマウント プロセスを停止します。ワークスペースのマウントを解除すると、そのワークスペースを使用していた Colab ランタイム上のすべてのノートブックでマウントが使用できなくなります。
  • ワークスペースを接続: 現在のノートブック セッションのアクティブなマウントへの接続を開始します。接続すると、ノートブックの作業ディレクトリとシステムパスが更新され、Git リポジトリが含まれるようになります。これにより、ファイルにアクセスしてインポートできるようになります。
  • ワークスペースを切断する: 現在のノートブック セッションのマウント接続を終了し、デフォルトの状態にリセットします。切断しても、他のアクティブなノートブック セッションのマウント接続ステータスには影響しません。セッションの接続を終了するには、[ワークスペースを切断] ボタンを使用することをおすすめします。
  • 修復: マウントまたは接続が使用できなくなった場合に、正常な状態に復元します。

マウントを初期化したら、[ステータス] バーでマウントのリアルタイムの健全性とアクティブなパスを確認します。考えられる健全性の状態は、接続済み、マウント済み、停止、異常です。

次のステップ