使用 BigQuery Studio Git 存放區管理程式碼

BigQuery Studio Git 存放區可讓您直接在 BigQuery Studio 檔案瀏覽器中，管控 SQL 指令碼、筆記本和其他程式碼資產的版本。您不必離開 Google Cloud 控制台，就能複製遠端 Git 存放區、管理分支版本，以及執行 Git 作業。

與傳統存放區相比，這項整合功能在左側窗格的使用者根資料夾下，提供簡化的資料夾式體驗。您可以與程式碼資產互動，例如標準檔案和目錄，同時維持與遠端 Git 存放區的連線。

限制

  • BigQuery Studio Git 存放區僅限使用者根資料夾情境，且僅供私人使用。請勿與其他使用者共用這些存放區。雖然這些存放區會顯示在使用者根資料夾中 (這是專案中素材資源的虛擬表示法)，但技術上來說，這些存放區是在專案層級建立。
  • 掛接位置內的檔案系統作業會耗用 Dataform 配額。
  • 如果存放區含有大量檔案、檔案大小較大、分支版本較多，或修訂版本記錄較深且複雜，複製作業所需的時間會較長。複製作業可能會超過作業逾時時間，導致無法成功建立存放區。如要縮短修訂版本記錄較多的存放區複製時間，可以建立淺層副本。日後可以視需求擷取更多修訂版本。
  • 儲存在 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 存放區管理程式碼所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

您必須具備下列權限，才能使用 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 工作使用者、BigQuery Studio 使用者和 BigQuery 使用者)，就能在 Google Cloud 專案的「Explorer」面板中查看所有程式碼資產，無論這些資產是否由他們建立或與他們共用。如要限制瀏覽權限，可以建立不含 dataform.repositories.list 權限的自訂角色。
  • 凡是與 Dataform 服務代理共用的 Secret，都有可能遭到可編輯這些資產的使用者存取。為確保憑證安全，請限制只有信任的使用者才能建立及編輯權限，並限制 Dataform 服務代理可存取的密鑰。詳情請參閱「在套件安裝期間存取 Secret」。

詳情請參閱「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 流程和 Proxy Git 流量。
  • 使用 IAM 拒絕政策強制執行防護機制：套用組織層級拒絕政策，防止大型數據分析群組執行敏感動作。建議您拒絕 developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken 權限，防止權杖遭到擷取，並拒絕 developerconnect.googleapis.com/accountConnectors.gitProxyWrite 權限，防止存放區遭到意外寫入。BigQuery 管理員 (roles/bigquery.admin) 和 BigQuery Studio 管理員 (roles/bigquery.studioAdmin) 等管理角色包含權杖存取子權限，可讓主體擷取有效的明文第三方原始碼管理 (SCM) 權杖，例如 GitHub 應用程式安裝權杖。
  • 隔離機密 CI/CD 專案：將機密 CI/CD 管道 (例如 Cloud Build 或 Vertex AI) 放在專屬 Google Cloud 專案中，與一般資料分析環境區隔。Developer Connect 權限的範圍限定在專案層級，因此在共用的多租戶專案中，BigQuery 使用者可以列出並使用該專案中的任何 Developer Connect 連線，透過 Proxy 傳送 Git 要求，這可能會授予為 CI/CD 或基礎架構自動化設定的存放區存取權。
  • 使用 IAM 條件限制資源存取權：將 IAM 條件附加至角色繫結，限制特定資源的 Developer Connect 權限。您可以根據資源名稱前置字元限制存取權，或將存取權範圍限定在特定 Connection 和 GitRepositoryLink 資源。這可確保使用者只能與工作流程專用的 Developer Connect 連線互動。
  • 保護資源名稱中的機密中繼資料：請勿在存放區名稱、分支版本名稱或連線 ID 中，嵌入機密憑證、專案代號或機密資訊。列出這些資源 (developerconnect.connections.list 和 developerconnect.accountConnectors.list) 所需的權限會授予標準 BigQuery 角色。只要具備基本專案存取權，任何人都能列舉這些資源，並探索機密中繼資料。

建立 BigQuery Studio Git 存放區

建立 Git 存放區時，請考量下列規定：

  • 如果遠端存放區未開放給公開網際網路 (例如位於防火牆後方)，則將遠端 Git 存放區連線至 Git 存放區可能會失敗。在這種情況下，請將必要的 Dataform egress IP 位址範圍新增至防火牆規則，以便連線至受保護的遠端存放區。
  • 如要建立 Git 存放區，並連線至未列入 dataform.restrictGitRemotes 組織政策許可清單的遠端 Git 存放區，請先將遠端 Git 存放區新增至政策的 allowedValues 清單，然後再建立 Git 存放區。詳情請參閱「限制遠端存放區」。

如要建立 Git 存放區，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在左側窗格中，按一下 「Files」(檔案)，開啟檔案瀏覽器。

    如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

  3. 按一下使用者根節點旁的 「View actions」(查看動作) >「Create」(建立) >「Git repository」(Git 存放區)。

  4. 輸入遠端 Git 存放區的網址。

  5. BigQuery Studio 會偵測是否有現成的 Developer Connect 帳戶連接器。您可以採取下列做法︰

    • 如果找到帳戶連接器，系統會預先填入 Git 存放區的顯示名稱。您可以編輯這些值。
    • 如果沒有帳戶連接器，請按一下「Create account connector」(建立帳戶連接器)，建立新的帳戶連接器。
    • 如果不想使用 Developer Connect 帳戶連接器，請按一下「Use a different connection type」(使用其他連線類型)，使用 HTTPS 或 SSH 連線。

  6. 選用：如要建立修訂版本記錄有限的淺層副本存放區，請按一下「Advanced options」(進階選項)，然後勾選「Shallow clone」(淺層副本) 核取方塊。

    1. 在「Depth」(深度) 欄位中，輸入要在有限修訂版本記錄中擷取的修訂版本數量。

  7. 點選「連線」。

編輯檔案

如要編輯檔案，請點選檔案節點 (例如 SQL 指令碼或筆記本)，在新的編輯器分頁中開啟檔案。

系統會自動儲存你所做的任何變更。

管理檔案

您可以使用與各個項目相關聯的動作選單，執行標準管理工作。如要存取這些選項，請按一下任何目錄或檔案旁的 「View actions」(查看動作)。

在目錄層級，您可以執行下列工作：

  • 在存放區中建立：建立新的程式碼資產，包括 SQL 查詢、筆記本、資料畫布、資料準備、檔案或子目錄。
  • 上傳至存放區：將本機電腦中的現有檔案匯入所選目錄。
  • 重新命名：變更目錄名稱。
  • 移動：重新定位目錄。您只能將目錄移至同一個 Git 存放區中的其他位置。詳情請參閱「移動目錄或檔案」。
  • 刪除：從本機工作區永久移除目錄及其所有內容。詳情請參閱「刪除目錄或檔案」。

在檔案層級，您可以執行下列工作：

  • 「Open」(開啟) 或「Open in」(開啟方式)：在預設編輯器或特定應用程式 (例如特定筆記本環境) 中查看檔案。
  • 重新命名：變更檔案名稱。
  • 複製：建立檔案副本。您只能將檔案複製到同一個 Git 存放區中的目錄。詳情請參閱「複製檔案」。
  • Move：將檔案移至同一個 Git 存放區中的其他目錄。詳情請參閱「移動目錄或檔案」。
  • 下載：將檔案副本儲存到本機電腦。
  • 刪除：從工作區中移除檔案。詳情請參閱「刪除目錄或檔案」。

移動目錄或檔案

如要移動 BigQuery Studio Git 存放區中的目錄或檔案，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在左側窗格中，按一下 「Files」(檔案)，開啟檔案瀏覽器。

  3. 視要移動的資源數量而定，執行下列任一操作：

    • 如要移動單一資源，請在檔案瀏覽器中選取要移動的目錄或檔案，然後依序點選 「View actions」(查看動作) >「Move」(移動)。
    • 如要移動多項資源，請在資料夾檢視畫面中，勾選要移動的每項資源旁的核取方塊，然後按一下「Move」(移動)。

  4. 在移動資源對話方塊中，選取同一個 Git 存放區中的目標目錄。只能將資源移至同一個 Git 存放區內的位置。

  5. 按一下 [移動]。

複製檔案

如要複製 BigQuery Studio Git 存放區中的檔案，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在左側窗格中，按一下 「Files」(檔案)，開啟檔案瀏覽器。

  3. 選取要複製的檔案。

  4. 按一下 查看動作 > 複製。

  5. 在複製資源對話方塊中，選取同一個 Git 存放區中的目標目錄。只能將檔案複製到同一個 Git 存放區內的位置。

  6. 點選「複製」。

刪除目錄或檔案

如要刪除 BigQuery Studio Git 存放區中的目錄或檔案，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在左側窗格中，按一下 「Files」(檔案)，開啟檔案瀏覽器。

  3. 視要刪除的資源數量而定，請執行下列任一操作：

    • 如要刪除單一資源，請在檔案瀏覽器中選取要刪除的目錄或檔案，然後依序點選 「View actions」(查看動作) >「Delete」(刪除)。
    • 如要刪除多項資源，請在資料夾檢視畫面中，勾選要刪除的每項資源旁的核取方塊，然後按一下「Delete」(刪除)。

  4. 在刪除確認對話方塊中，按一下「Delete」(刪除)。

修訂並推送變更

如要將本機編輯內容與遠端存放區同步，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在左側窗格中，按一下「Source control」圖示 ，開啟「Source control」面板。

  3. 選用：將滑鼠游標懸停在修改過的檔案上，然後按一下「Show diff」(顯示差異)，即可逐行比較本機版本和上次提交的版本。

  4. 在「Commit message」(修訂版本訊息) 欄位中，輸入變更說明。

  5. 按一下「Commit」。變更會儲存至本機分支版本的 Git 記錄。

  6. 按一下「Push to remote」(推送至遠端分支版本)。變更會與遠端存放區同步。

查看新的分支版本

您可以管理本機分支，並根據現有的本機或遠端追蹤分支建立新的本機分支。

在「Source control」(原始碼控制) 面板的「Branches」(分支版本) 部分，您可以看到已簽出的本機分支版本。CURRENT 標籤代表目前使用的分支版本，DEFAULT 標籤則代表存放區的預設分支版本。

如要查看新的分支版本，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 開啟「Source control」面板。

  3. 在「Branches」(分支版本) 區段中，依序點選「Branches」(分支版本) 旁邊的 「Actions」(動作) >「Check out new branch」(查看新分支版本)。

  4. 在「Source branch」(來源分支版本) 選單中，選取要建立新分支版本的來源分支版本，例如 origin/main。

  5. 在「Branch name」(分支版本名稱) 欄位中，輸入新分支版本的名稱。

  6. 按一下「Checkout branch」。BigQuery Studio 會先檢出來源分支版本，如果提供的分支版本名稱代表新的分支版本，系統會根據該來源建立分支版本。新分支版本會成為使用中的分支版本，Git 存放區的內容也會自動更新，反映已簽出分支版本的狀態。

如要切換至現有分支版本，請按照下列步驟操作：

  1. 在「Source control」(原始碼控制) 面板中，展開「Branches」(分支版本) 區段。
  2. 在要切換的分支版本旁，依序點選 「Actions」(動作) > 「Switch to <分支版本名稱>」(切換至 <分支版本名稱>)BRANCH_NAME。

查看修訂記錄

您可以查看使用中分支版本的修訂版本記錄。如果存放區是以淺層副本 (shallow clone) 形式建立，「Branch commit history」(分支版本修訂記錄) 窗格會顯示資訊橫幅，指出存放區的修訂記錄有限。您可以擷取更多修訂版本，擴充本機記錄。

如要查看修訂版本記錄，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 開啟「Source control」面板。

  3. 按一下主要版本管控動作按鈕旁的 箭頭下拉式選單，然後點選「View commit history」(查看修訂版本記錄)。

    「Branch commit history」(分支版本修訂記錄) 窗格隨即開啟，顯示現行分支版本的修訂記錄。

  4. 選用：如要從遠端存放區擷取修訂版本，請執行下列其中一項操作：

    • 按一下主要版本管控動作按鈕旁的 箭頭下拉式選單，然後點選「Fetch from remote」(從遠端擷取)。
    • 在「Branch commit history」(分支版本修訂版本記錄) 窗格中，按一下「Fetch」(擷取)。

    如果是淺層副本存放區，請在「Fetch (shallow clone)」(擷取 (淺層副本)) 對話方塊的「Additional commits to fetch」(要擷取的其他修訂版本) 欄位中，輸入要從存放區記錄擷取的其他修訂版本數量。

    如果輸入 0，系統不會擷取其他歷來修訂版本，但 BigQuery Studio 會執行標準擷取作業，同步處理遠端參照和中繼資料。

  5. 按一下「擷取」。

    您可以視需要重複擷取，直到擷取所有修訂版本。

刪除 Git 存放區

刪除 BigQuery Studio Git 存放區後，該存放區和所有內容都會從 BigQuery Studio 環境中移除。

如要刪除 Git 存放區，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 使用下列任一方法刪除存放區：

    • 如要從檔案瀏覽器中刪除存放區，請按一下左側窗格中的「 Files」(檔案)。找到要刪除的 Git 存放區，依序點選旁邊的 「View actions」(查看動作) >「Delete」(刪除)。
    • 如要從控制台刪除存放區，請在「Source control」(原始碼控制) 面板標題下方，依序點選 「Source control options」(原始碼控制選項) >「Delete REPOSITORY_NAME」(刪除)。

  3. 在刪除確認對話方塊中，按一下「Delete」(刪除)。

存取 Git 存放區掛接中的筆記本檔案

從 BigQuery Studio Git 存放區存取筆記本時，您可以將主機 Git 存放區掛接至筆記本的執行階段。掛接是一種連線，可讓遠端 Git 存放區看起來像是筆記本執行階段上的本機存放區。這樣一來，筆記本就能直接存取、讀取及寫入同一存放區中的其他檔案和查詢指令碼。

掛接 Git 存放區

如要掛接 Git 存放區，請在筆記本中執行下列 Python 程式碼：

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

筆記本連至掛接點後，會發生下列變化：

  • Notebook 工作階段目前使用的目錄會更新，反映其在 Git 存放區中的相對路徑。這可確保路徑式檔案存取權自動運作。
  • 筆記本執行階段上的 Git 存放區路徑會新增至 Python 系統路徑，讓您可以使用標準 Python 匯入陳述式，直接將 Git 存放區中的查詢指令碼和檔案載入筆記本。

管理掛接和連線

使用下列控制項管理工作區：

  • 掛接工作區：啟動 Git 存放區的掛接程序。掛接是共用資源，因此如果相同 Colab 執行階段中的多個筆記本使用同一個 Git 存放區，就會使用相同的掛接。
  • 卸載工作區：停止 Git 存放區的掛接程序。卸載工作區後，使用該工作區的 Colab 執行階段上所有筆記本都無法再存取該工作區。
  • 連結工作區：開始連結至目前筆記本工作階段的有效掛接。連結後，筆記本的工作目錄和系統路徑會更新，納入 Git 存放區，方便您存取及匯入檔案。
  • 中斷工作區連線：結束目前筆記本工作階段的掛接連線，並重設為預設狀態。中斷連線不會影響其他有效筆記本工作階段的掛接連線狀態。如要結束工作階段連線，建議使用「中斷工作區連線」按鈕。
  • 修復：如果掛接或連線無法使用，則將其還原至健康狀態。

初始化掛接作業後，請參閱「Status」(狀態) 列，瞭解掛接作業的即時健康狀態和有效路徑。可能的健康狀態包括「Connected」(已連線)、「Mounted」(已掛接)、「Stopped」(已停止)和「Unhealthy」(健康狀態不良)。

後續步驟