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

BigQuery Studio Git リポジトリを使用して、SQL スクリプトとノートブックを管理できます。この機能により、バージョン管理が BigQuery Studio ファイル ブラウザに直接統合されるため、リポジトリのクローン作成、 ブランチの管理、Git オペレーションの実行を Google Cloud コンソールを離れることなく行うことができます。

BigQuery Studio Git リポジトリは、従来のリポジトリと比較して、フォルダベースの合理化された エクスペリエンスを提供します 。 BigQuery Studio Git リポジトリは、左側のペインのユーザー ルートフォルダに直接表示されます。

BigQuery Studio Git リポジトリを使用すると、リモート Git リポジトリへの接続を維持しながら、標準のファイルやディレクトリと同じようにコードアセットを操作できます。

制限事項

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

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

      FuseWidget(CACHE_TTL_SECONDS=NUMBER)

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

始める前に

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

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 権限のセキュリティに関する考慮事項をご覧ください。

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

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

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

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

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

    BigQuery に移動

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

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

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

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

  5. BigQuery Studio は、既存の Developer Connect アカウント コネクタ が使用可能かどうかを検出します。お手数ですが以下のどちらかの方法でご対応ください。

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

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

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

ファイルの編集

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

加えた変更は自動的に保存されます。

ファイルの管理

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

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

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

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

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

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

ファイルとディレクトリを移動またはコピーできますが、同じ Git リポジトリ内に残す必要があります。

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

    BigQuery に移動

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

  3. 移動またはコピーするファイルまたはディレクトリを見つけます。

  4. [アクションを開く] > [移動] または [コピー] をクリックします。

  5. 表示されたダイアログで、同じ Git リポジトリ内のターゲット ディレクトリを選択します。

  6. [移動] または [コピー] をクリックします。

変更を commit して push する

ローカルの編集内容をリモート リポジトリと同期するには、次の操作を行います。

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

    BigQuery に移動

  2. 左側のペインで、 [Repository] をクリックします。

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

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

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

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

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

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

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

新しいブランチをチェックアウトする手順は次のとおりです。

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

    BigQuery に移動

  2. 左側のペインで、 [Repository] をクリックします。

  3. [ブランチ] セクションを開きます。

  4. ブランチの横にある [**アクションを開く**] をクリックし、[**新しいブランチをチェックアウト**] をクリックします。

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

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

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

commit 履歴を表示する

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

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

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

    BigQuery に移動

  2. 左側のペインで、 [Repository] をクリックします。

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

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

  4. 省略可: シャロー クローン リポジトリの commit を追加で取得するには、[ブランチの commit 履歴] ペインで [取得] をクリックします。

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

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

    2. [取得] をクリックします。

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

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 リポジトリが含まれるようになります。これにより、ファイルにアクセスしてインポートできます。
  • ワークスペースを切断: 現在の ノートブック セッションのマウント接続を終了し、デフォルトの状態にリセットします。切断しても、他のアクティブなノートブック セッションのマウント接続ステータスには影響しません。セッションの接続を終了するには、[ワークスペースを切断] ボタンを使用することをおすすめします。
  • 修復: 使用できなくなったマウントまたは接続を正常な状態に戻します。

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

次のステップ