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

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

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

限制

  • BigQuery Studio Git 存放區僅限使用者根資料夾情境，且僅供私人使用。請勿與其他使用者共用這些存放區。雖然這些存放區會顯示在使用者根資料夾中 (這是專案中素材資源的虛擬表示法)，但技術上來說，這些存放區是在專案層級建立。
  • 不支援搭配使用 Developer Connect 帳戶連接器和 Git Proxy。
  • 掛接位置內的檔案系統作業會耗用 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 權限的安全性考量」。

建立 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 different connection type」(使用其他連線類型)，使用 HTTPS 或 SSH 連線。

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

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

  7. 點選「連線」。

編輯檔案

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

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

管理檔案

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

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

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

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

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

移動或複製檔案和目錄

您可以移動或複製檔案和目錄，但必須保留在同一個 Git 存放區中。

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

    前往「BigQuery」

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

  3. 找出要移動或複製的檔案或目錄。

  4. 按一下 開啟動作 > 移動或複製。

  5. 在顯示的對話方塊中，選取同一個 Git 存放區中的目標目錄。

  6. 按一下「移動」或「複製」。

修訂並推送變更

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

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

    前往「BigQuery」

  2. 點選左側窗格中的「 Repository」。

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

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

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

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

查看新的分支版本

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

在「Repository」(存放區) 分頁的「Branches」(分支版本) 部分，您可以看到已簽出的本機分支版本。CURRENT 標籤代表目前使用的分支版本，DEFAULT 標籤則代表存放區的預設分支版本。

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

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

    前往「BigQuery」

  2. 點選左側窗格中的「 Repository」。

  3. 展開「Branches」(分支版本) 區段。

  4. 按一下分支版本旁的「Open actions」圖示 ，然後點選「Check out new branch」。

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

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

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

查看修訂記錄

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

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

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

    前往「BigQuery」

  2. 點選左側窗格中的「 Repository」。

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

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

  4. 選用：如要擷取淺層副本存放區的其他修訂版本，請在「Branch commit history」(分支版本修訂版本記錄) 窗格中，按一下「Fetch」(擷取)。

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

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

    2. 按一下「擷取」。

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

存取 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」(健康狀態不良)。

後續步驟