管理已儲存的查詢

本文說明如何管理已儲存的查詢和傳統已儲存的查詢，以及如何在 Dataplex Universal Catalog 中管理已儲存的查詢中繼資料。

已儲存的查詢是 BigQuery Studio 程式碼資產，由 Dataform 提供支援。

事前準備

您可以選擇在遷移期間，為已遷移的公開或專案傳統儲存查詢設定 IAM 權限，建立或選取 BigQuery Studio 儲存查詢，並為該儲存查詢授予所選身分與存取權管理 (IAM) 權限。

將公開或專案的傳統型已儲存查詢遷移至 BigQuery Studio 的已儲存查詢時，請選取 BigQuery Studio 的已儲存查詢，將授予該查詢的權限複製到已遷移的已儲存查詢。

必要的角色

如要取得管理已儲存查詢所需的權限，請要求管理員為您授予下列 IAM 角色，以便您管理所需專案的已儲存查詢：

• 如要在 Google Cloud 控制台中管理 BigQuery Studio 已儲存的查詢，請按照下列步驟操作：
  • BigQuery 工作使用者 (roles/bigquery.jobUser)
  • BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
  • Code Owner (roles/dataform.codeOwner)
• 如要使用 BigQuery API 管理 BigQuery Studio 儲存的查詢，請按照下列步驟操作： 程式碼擁有者 (roles/dataform.codeOwner)
• 如要將專案的傳統儲存查詢遷移至 BigQuery Studio 儲存查詢，請按照下列步驟操作： BigQuery Studio 管理員 (roles/bigquery.studioAdmin)
• 如要讓已驗證的使用者查看公開存取查詢： Code Viewer (roles/dataform.codeViewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這些預先定義的角色包含管理已儲存查詢所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

您必須具備下列權限，才能管理已儲存的查詢：

• 如要在 Google Cloud 控制台管理 BigQuery Studio 已儲存的查詢，請按照下列步驟操作： bigquery.config.get, bigquery.jobs.create, dataform.locations., resourcemanager.projects.get, resourcemanager.projects.list, bigquery.readsessions., dataform.repositories., dataform.workspaces.
• 如要使用 BigQuery API 管理 BigQuery Studio 已儲存的查詢，請按照下列步驟操作： dataform.locations., dataform.repositories., dataform.workspaces.*, resourcemanager.projects.get, resourcemanager.projects.list
• 如要將專案的傳統版已儲存查詢遷移至 BigQuery Studio 的已儲存查詢，請按照下列步驟操作： bigquery.savedqueries.get, bigquery.savedqueries.list, bigquery.savedqueries.update, bigquery.savedqueries.delete, bigquery.savedqueries.create
• 如要讓已驗證的使用者查看公開存取查詢： dataform.locations.*, dataform.repositories.computeAccessTokenStatus, dataform.repositories.fetchHistory, dataform.repositories.fetchRemoteBranches, dataform.repositories.get, dataform.repositories.getIamPolicy, dataform.repositories.list, dataform.repositories.queryDirectoryContents, dataform.repositories.readFile, dataform.workspaces.fetchFileDiff, dataform.workspaces.fetchFileGitStatuses, dataform.workspaces.fetchGitAheadBehind. dataform.workspaces.get, dataform.workspaces.getIamPolicy, dataform.workspaces.list, dataform.workspaces.queryDirectoryContents, dataform.workspaces.readFile, dataform.workspaces.searchFiles, resourcemanager.projects.get, resourcemanager.projects.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解 BigQuery 身分與存取權管理，請參閱「使用身分與存取權管理功能控管存取權」。

如要在 Dataplex 通用目錄中管理已儲存的查詢中繼資料，請確認您具備必要的 Dataplex 通用目錄角色和 dataform.repositories.get 權限。

分享已儲存的查詢

如要與使用者分享已儲存的查詢，請先授予該使用者已儲存查詢的存取權，然後將使用者新增至適當的 IAM 角色。接著，您可以產生儲存查詢的連結，並與使用者分享該連結。

您與他人分享的查詢，對方只會看到最新版本。未明確儲存的自動儲存變更不會顯示在共用查詢中。

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。找出要授予存取權的已儲存查詢，然後按一下該查詢。

3. 依序點選 person_add「分享」和「管理權限」。

4. 在「管理權限」窗格中，按一下「新增使用者/群組」。

5. 在「新增主體」欄位中輸入主體。

6. 在「Role」清單中，選取下列其中一個角色：

   • 程式碼擁有者：可對儲存的查詢執行任何動作，包括刪除或分享。
   • 程式碼編輯器：可編輯查詢。
   • 程式碼檢視器：可查看查詢。

7. 選用步驟：如要查看完整的角色清單和進階共用設定，請按一下「進階共用」。

8. 按一下 [儲存]。

9. 如要返回已儲存的查詢資訊，請按一下「關閉」。

10. 如要產生已儲存查詢的連結，請依序按一下 person_add「共享」和「取得連結」。

    系統隨即會將連結複製到剪貼簿。

授予已儲存查詢的公開存取權

您可以將「程式碼檢視者」(roles/dataform.codeViewer) 角色授予 allAuthenticatedUsers 實體，藉此授予 BigQuery Studio 儲存查詢的公開存取權。

將 IAM 角色指派給 allAuthenticatedUsers 授權對象後，服務帳戶和透過 Google 帳戶驗證的所有網路使用者都會獲得該角色。這包括未連結至 Google Workspace 帳戶或 Cloud Identity 網域的帳戶，例如個人 Gmail 帳戶。未通過驗證的使用者 (例如匿名訪客) 不在此範圍內。詳情請參閱「所有已驗證的使用者」。

舉例來說，如果您在 sales 已儲存的查詢中授予 allAuthenticatedUsers 程式碼檢視者角色，則所有服務帳戶和透過 Google 帳戶驗證的網路使用者，都會對 sales 已儲存的查詢擁有唯讀存取權。

如要授予 BigQuery Studio 儲存查詢的公開存取權，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。找出要授予公開存取權的已儲存查詢。

3. 按一下已儲存查詢旁的 more_vert「View actions」，然後依序點選「Share」>「Manage Permissions」。

4. 在「管理權限」窗格中，按一下「新增使用者/群組」。

5. 在「New principals」(新增主體) 欄位中輸入 allAuthenticatedUsers。

6. 在「Role」清單中，選取「Code Viewer」 角色。

7. 按一下 [儲存]。

8. 如要返回已儲存的查詢資訊，請按一下「關閉」。

禁止公開存取已儲存的查詢

如要確保不會向任何 BigQuery Studio 已儲存的查詢授予公開存取權，請限制專案中的 allAuthenticatedUsers 使用者主體。

如要限制專案中的 allAuthenticatedUsers，您可以設定 iam.allowedPolicyMemberDomains 政策，並從 allowed_values 清單中移除 allAuthenticatedUsers。

如果您在 iam.allowedPolicyMemberDomains 政策中限制 allAuthenticatedUsers，allAuthenticatedUsers 主體就無法用於專案中的任何 IAM 政策，因此無法授予所有資源 (包括 BigQuery Studio 的已儲存查詢) 的公開存取權。

如要進一步瞭解 iam.allowedPolicyMemberDomains 政策和設定說明，請參閱「依照網域限制身分」。

設定預設區域

如果您是第一次建立程式碼資產，請為程式碼資產設定預設區域。建立程式碼資產後，就無法變更其地區。

BigQuery Studio 中的所有程式碼資產都會使用相同的預設區域。如要設定程式碼資產的預設區域，請按照下列步驟操作：

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，找出已啟用程式碼資產的專案。

3. 按一下專案旁的 more_vert「View actions」，然後點選「Change my default code region」。

4. 在「區域」中，選取要用於程式碼資產的區域。

5. 按一下 [選取]。

如需可用地區的清單，請參閱 BigQuery Studio 位置。

查看所有已儲存的查詢

如要查看專案中所有已儲存查詢的清單，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中，按一下「查詢」旁的 more_vert「查看動作」，然後執行下列任一操作：

• 如要在目前的分頁中開啟清單，請按一下「全部顯示」。
• 如要在新分頁中開啟清單，請依序按一下「在新分頁中顯示所有內容」 >「新分頁」。
• 如要在分割分頁中開啟清單，請依序按一下「顯示所有內容」 >「分割分頁」。

查看已儲存的查詢中繼資料

如要查看已儲存的查詢中繼資料，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。按一下要查看中繼資料的已儲存查詢名稱。

3. 按一下「資訊」，即可查看儲存查詢的相關資訊，例如所使用的區域和上次修改日期。

使用已儲存的查詢版本

您可以選擇在存放區內或外建立已儲存的查詢。系統會根據已儲存查詢的位置，以不同方式處理已儲存查詢的版本。

在存放區中儲存查詢版本

存放區是位於 BigQuery 或第三方供應商的 Git 存放區。您可以在存放區中使用工作區，對已儲存的查詢執行版本控制。詳情請參閱「使用檔案的版本控制功能」。

在存放區外進行已儲存查詢版本管理

請參閱以下各節，瞭解如何查看、比較及還原已儲存查詢的版本。

查看已儲存的查詢版本

如要查看已儲存的查詢版本，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。按一下要查看版本記錄的已儲存查詢名稱。

3. 按一下 history「版本記錄」，即可依日期由新到舊的順序查看已儲存的查詢版本清單。

比較已儲存的查詢版本

如要比較已儲存的查詢版本，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。按一下要比較版本資訊的已儲存查詢名稱。

3. 按一下 history「版本記錄」。

4. 按一下已儲存查詢版本旁的 more_vert「查看動作」，然後點選「比較」。比較窗格會隨即開啟，比較您選取的已儲存查詢版本與目前查詢。

5. 選用：目前的查詢也會顯示自動儲存的變更。如要明確儲存這些變更，請按一下「覆寫」。

6. 選用：如要比較版本內容，而非在個別檢視窗中比較，請按一下「比較」，然後點選「內嵌」。

還原已儲存的查詢版本

從比較窗格還原時，您可以比較先前儲存的查詢與目前版本，然後再選擇是否要還原。

1. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。按一下要還原先前版本的已儲存查詢名稱。
2. 按一下 history「版本記錄」。
3. 按一下要還原的已儲存查詢版本旁的 more_vert「View actions」，然後點選「Compare」。比較窗格會隨即開啟，比較您選取的已儲存查詢版本與最新查詢版本，包括任何自動儲存的變更。
4. 如果您想在比較後還原先前儲存的查詢版本，請按一下「還原」。
5. 按一下「確認」。

下載已儲存的查詢

如要下載已儲存的查詢，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「查詢」資料夾，並視需要展開「共用查詢」資料夾。按一下已儲存查詢的名稱即可開啟查詢。

3. 點選 [下載]。

刪除已儲存的查詢

如要刪除已儲存的查詢，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「Queries」資料夾，並視需要展開「Shared queries」資料夾。找出要刪除的已儲存查詢。

3. 按一下已儲存查詢旁的 more_vert「View actions」(查看動作)，然後按一下「Delete」(刪除)。

4. 如要確認刪除，請在對話方塊中輸入 delete。

5. 點選「刪除」。

傳統版已儲存查詢

請參閱下列各節，瞭解如何管理傳統儲存查詢。

分享傳統版已儲存的查詢

您可以分享已指定專案或公開瀏覽權限的傳統版儲存查詢。專案層級瀏覽權限可讓具備必要權限的主體檢視、更新或刪除查詢。公開瀏覽權限可讓擁有查詢連結的任何人查看查詢，但無法更新或刪除查詢。

您可以產生並分享傳統版儲存查詢的連結，藉此與其他使用者分享傳統版儲存查詢。

如要執行傳統共用查詢，使用者必須能存取查詢所存取的資料。詳情請參閱「授予資料集存取權」。

如果您打算共用經典儲存查詢，請考慮在查詢中加入說明其用途的評論。

1. 在「Explorer」窗格中，展開專案和「(Classic) 查詢」資料夾，然後找出要共用的傳統版儲存查詢。
2. 按一下查詢旁的 more_vert「查看動作」，然後點選「取得連結」。
3. 將連結分享給您要授予查詢存取權的使用者。

將傳統查詢儲存為已儲存查詢

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

   前往 BigQuery

2. 在「Explorer」窗格中，展開專案和「(Classic) 查詢」資料夾，並視需要展開「專案查詢」資料夾。

3. 按一下傳統儲存查詢的名稱即可開啟。

4. 依序點選 「儲存查詢 (傳統版)」>「儲存查詢為...」。

5. 在「儲存查詢」對話方塊中，輸入名稱並選擇查詢的位置。

6. 按一下 [儲存]。

遷移傳統版已儲存的查詢

如要批次遷移傳統版已儲存查詢，您必須具備必要角色。這些角色授予的權限會決定您可以遷移的傳統版儲存查詢類型。

您可以批次遷移下列傳統版已儲存查詢：

個人傳統版已儲存查詢

只有建立個人傳統版儲存查詢的使用者，才能查看這類查詢。這些類別會以 person 圖示標示。個人傳統版儲存查詢只能由擁有者遷移。

公開的傳統版已儲存查詢

擁有查詢連結的任何人都可看到公開的傳統版已儲存查詢。這些類別會以 share 圖示標示。只有擁有者可以遷移公開的傳統版已儲存查詢。

公開的傳統已儲存查詢的 IAM 權限，不會對應至 BigQuery Studio 已儲存查詢的權限。也就是說，從公開傳統儲存查詢遷移的 BigQuery Studio 儲存查詢，預設不會公開。您需要為已遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限，無論是在遷移期間或遷移後皆可。

如要在遷移期間為已遷移的 BigQuery Studio 已儲存查詢設定身分與存取權管理權限，可以選取現有的 BigQuery Studio 已儲存查詢，該查詢具有您要套用至已遷移的已儲存查詢的權限。BigQuery 會複製已選取的 BigQuery Studio 已儲存查詢所授予的權限，並套用至已遷移的已儲存查詢。您也可以手動新增要與之分享已遷移的儲存查詢的使用者或群組。

如果您在遷移期間未設定 IAM 權限，則只有您可以存取已遷移的 BigQuery Studio 已儲存查詢。

專案的傳統版已儲存查詢

凡是擁有必要權限的實體都能查看專案層級的已儲存查詢。這些欄會以 people 圖示標示。您可以批次遷移專案中的所有傳統版已儲存查詢。

專案的傳統儲存查詢的 IAM 權限，並非直接對應至 BigQuery Studio 儲存查詢的權限。您必須在遷移期間或遷移後，為已遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限。

如要在遷移期間為已遷移的 BigQuery Studio 已儲存查詢設定身分與存取權管理權限，可以選取現有的 BigQuery Studio 已儲存查詢，該查詢具有您要套用至已遷移的已儲存查詢的權限。BigQuery 會複製已選取的 BigQuery Studio 已儲存查詢所授予的權限，並套用至已遷移的已儲存查詢。您也可以手動新增要與之分享已遷移的儲存查詢的使用者或群組。

如果您在遷移期間未設定 IAM 權限，則只有您可以存取已遷移的 BigQuery Studio 已儲存查詢。

在傳統版已儲存查詢的批次遷移作業期間，BigQuery 會執行以下操作：

• 將所有遷移的傳統版已儲存查詢儲存為 BigQuery Studio 已儲存查詢，並儲存在所選區域。
• 將所有遷移的傳統版已儲存查詢轉換為唯讀的傳統版已儲存查詢。

遷移完成後，您可以透過 BigQuery Studio 的已儲存查詢和傳統查詢的唯讀版本，存取個人、公開和專案的傳統查詢。

遷移風險

批次遷移完成後，您將無法修改已遷移的傳統儲存查詢。遷移的個人、公開和專案傳統版已儲存查詢會變成唯讀。

BigQuery 會使用 Dataform API，將已遷移的 BigQuery Studio 儲存查詢新增至您的 Google Cloud 專案。如要還原這些變更，則必須手動清理。

批次遷移傳統版已儲存查詢

如要將專案中的傳統已儲存查詢大量遷移至 BigQuery Studio 的已儲存查詢，請按照下列步驟操作：

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案，然後按一下「(傳統版) 查詢」旁的 more_vert「查看動作」，接著點選「遷移傳統版已儲存的查詢」。

3. 在「傳統版已儲存查詢遷移作業」窗格中的「檢查遷移作業就緒狀態」部分，按一下「下一步」，確認您具備必要角色。

   您可以透過 IAM 權限，決定可遷移的傳統版已儲存查詢類型，以及傳統版已儲存查詢遷移窗格中可見的部分。

4. 在「區域」部分的「區域」下拉式選單中，選取 BigQuery 用來儲存已遷移的已儲存查詢的區域。

   建議您為 BigQuery Studio 程式碼資產選取預設區域。詳情請參閱「設定預設區域」。

5. 如要遷移所有個人舊版已儲存的查詢，請在「Migrate personal queries」部分勾選「Migrate all personal queries」核取方塊，然後按一下「Next」。

6. 如要遷移專案中的所有公開傳統版儲存查詢，請在「遷移公開查詢」部分執行下列操作：

   1. 勾選「遷移所有公開查詢」核取方塊。
   2. 在「SQL」SQL下拉式選單中，選取 BigQuery Studio 已儲存的查詢，該查詢須具備要套用至已遷移的已儲存查詢的 IAM 政策。

   3. 選用步驟：如要新增要與之分享已遷移的儲存查詢的使用者或群組，請按一下「Add User/Group」。

      如要公開分享已遷移的已儲存查詢，請將 allAuthenticatedUsers 設為主體，並授予 Code Viewer 角色。詳情請參閱「授予公開存取權」。

   4. 點選「下一步」。

7. 如要遷移專案層級的傳統版儲存查詢，請在「Migrate project queries」部分執行下列操作：

   1. 勾選「Migrate all project queries」核取方塊。
   2. 在「SQL」SQL下拉式選單中，選取 BigQuery Studio 已儲存的查詢，該查詢須具備要套用至已遷移的已儲存查詢的 IAM 政策。
   3. 選用步驟：如要新增要與之分享已遷移的儲存查詢的使用者或群組，請按一下「Add User/Group」。
   4. 點選「下一步」。

8. 如要確認您瞭解遷移風險，且想要批次遷移傳統版已儲存查詢，請在「確認」部分的「確認」欄位中輸入 confirm，然後按一下「下一步」。

9. 按一下「提交」。

視要遷移的查詢數量而定，遷移作業可能需要超過 15 分鐘的時間。

刪除傳統版已儲存的查詢

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

   前往 BigQuery

2. 在「Explorer」窗格中展開專案和「(Classic) 查詢」資料夾，並視需要展開「專案查詢」資料夾。

3. 找出要刪除的傳統儲存查詢。

4. 按一下查詢旁的 more_vert 「查看動作」，然後點選「刪除」。

5. 如要確認刪除，請在對話方塊中輸入 delete。

6. 點選「刪除」。

在 Dataplex Universal Catalog 中管理中繼資料

Dataplex Universal Catalog 可讓您儲存及管理已儲存查詢的中繼資料。根據預設，儲存的查詢會在 Dataplex Universal Catalog 中提供，無需額外設定。

您可以使用 Dataplex Universal Catalog 管理所有儲存的查詢位置中的儲存查詢。在 Dataplex Universal Catalog 中管理已儲存的查詢時，請遵守 Dataplex Universal Catalog 配額和限制和 Dataplex Universal Catalog 定價。

Dataplex 通用目錄會自動從已儲存的查詢中擷取下列中繼資料：

• 資料資產名稱
• 資料資產父項
• 資料資產位置
• 資料資產類型
• 對應的 Google Cloud 專案

Dataplex Universal Catalog 會將已儲存的查詢記錄為項目，並使用下列項目值：

系統項目群組

已儲存查詢的 系統項目群組為 @dataform。如要在 Dataplex Universal Catalog 中查看已儲存的查詢項目詳細資料，您必須查看 dataform 系統項目群組。如需查看項目群組中所有項目清單的操作說明，請參閱 Dataplex Universal Catalog 說明文件中的「查看項目群組詳細資料」。

系統項目類型

已儲存查詢的系統項目類型為 dataform-code-asset。如要查看已儲存查詢的詳細資料，您需要查看 dataform-code-asset 系統輸入類型、使用以面向為準的篩選器篩選結果，並將 dataform-code-asset 面向內的 type 欄位設為 SQL_QUERY。接著選取所選已儲存查詢的項目。如需有關如何查看所選項目類型詳細資料的操作說明，請參閱 Dataplex Universal Catalog 說明文件中的「查看項目類型的詳細資料」。如要瞭解如何查看所選項目的詳細資料，請參閱 Dataplex Universal Catalog 說明文件中的「查看項目詳細資料」。

系統切面類型

已儲存查詢的系統切面類型為 dataform-code-asset。如要為 Dataplex Universal Catalog 中的已儲存查詢提供額外背景資訊，請使用切面為已儲存的查詢項目加上註解、查看 dataform-code-asset 切面類型、使用以切面為基礎的篩選器篩選結果，並將 dataform-code-asset 切面中的 type 欄位設為 SQL_QUERY。如要瞭解如何使用切面標註項目，請參閱 Dataplex Universal Catalog 說明文件中的「管理切面並強化中繼資料」。

類型

已儲存查詢的類型為 SQL_QUERY。您可以使用 aspect:dataplex-types.global.dataform-code-asset.type=SQL_QUERY 查詢，在以切面為依據的篩選器中篩選 dataform-code-asset 系統輸入類型和 dataform-code-asset 切面類型中的已儲存查詢。

如要瞭解如何在 Dataplex Universal Catalog 中搜尋資產，請參閱 Dataplex Universal Catalog 說明文件中的「在 Dataplex Universal Catalog 中搜尋資料資產」一節。

後續步驟

• 如要進一步瞭解 BigQuery Studio 已儲存的查詢，請參閱已儲存查詢簡介 。
• 如要瞭解如何建立已儲存的查詢，請參閱「建立已儲存的查詢」。