使用資料列層級安全防護機制

本文說明如何在 BigQuery 中使用資料列層級安全防護機制，限制資料表資料列層級的資料存取權。閱讀本文件前，請先參閱「BigQuery 資料列層級安全性簡介」，概略瞭解資料列層級安全性。

您可以透過資料列層級存取權政策執行下列工作：

• 在資料表上建立或更新資料列層級存取權政策
• 合併資料表的資料列層級存取權政策
• 列出資料表的資料列層級存取權政策
• 從資料表刪除資料列層級存取權政策
• 查詢具有資料列層級存取權政策的資料表

注意： Google Cloud 使用外部識別資訊提供者，因此您必須使用員工身分聯盟主體 ID。將 Google 帳戶主體 ID (例如 user:[e-mail]、group:[e-mail] 和 domain:example.com) 替換為適當的員工身分聯盟主體 ID。

限制

在 Google Cloud 控制台中選取資料表時，「Preview」(預覽) 分頁無法顯示具有資料列存取權政策的資料表預覽畫面。如要查看資料表內容，請執行查詢。

事前準備

授予 Identity and Access Management (IAM) 角色，讓使用者具備執行本文件中各項工作所需的權限。執行工作所需的權限 (如有) 會列在工作的「必要權限」部分。

建立或更新資料列層級存取權政策

您可以使用資料定義語言 (DDL) 陳述式，在 BigQuery 資料表建立或更新資料列層級存取權政策。

所需權限

如要在 BigQuery 資料表建立資料列層級存取權政策，您必須具備下列 IAM 權限：

• bigquery.rowAccessPolicies.create
• bigquery.rowAccessPolicies.setIamPolicy
• bigquery.tables.getData (在目標資料表和已授予子查詢資料列層級存取權政策中參照的任何資料表)
• bigquery.jobs.create (執行 DDL 查詢工作)

如要更新 BigQuery 資料表的資料列層級存取權政策，您需要下列 IAM 權限：

• bigquery.rowAccessPolicies.update
• bigquery.rowAccessPolicies.setIamPolicy
• bigquery.tables.getData (在目標資料表和已授予子查詢資料列層級存取權政策中參照的任何資料表)
• bigquery.jobs.create (執行 DDL 查詢工作)

下列各項預先定義的 IAM 角色，都包含建立及更新資料列層級存取權政策所需的權限：

• roles/bigquery.admin
• roles/bigquery.dataOwner

bigquery.filteredDataViewer 角色

建立資料列層級存取權政策時，BigQuery 會自動將 bigquery.filteredDataViewer 角色授予被授權者清單中的成員。在 Google Cloud 控制台中列出資料表的資料列層級存取權政策時，這個角色會與政策授予對象清單的成員一併顯示。

注意： 請勿透過 IAM 直接將 bigquery.filteredDataViewer 角色套用至資源。bigquery.filteredDataViewer 是系統管理的角色。請務必使用資料列層級存取權政策授予角色。詳情請參閱「資料列層級安全性的最佳做法」。

建立或更新資料列層級存取權政策

設定資料表的資料列層級存取權時，至少需要兩項資料列存取權政策：

• 授予資料表完整存取權的政策。第一個資料列存取權政策應授予存取權給需要完整存取資料表中資料的使用者和群組，以便維護或支援資料。例如，BigQuery 管理員和服務帳戶使用 DML 陳述式轉換資料表資料。
• 第二項政策會篩選存取權。這項政策會根據商業邏輯使用篩選器，將存取權授予特定群組。

如要建立或更新資料列層級存取權政策，請使用下列其中一個 DDL 陳述式：

• CREATE ROW ACCESS POLICY 會建立新的資料列層級存取權政策。

• 如果指定資料表沒有同名的資料列層級存取權政策，CREATE ROW ACCESS POLICY IF NOT EXISTS 陳述式會建立新的資料列層級存取權政策。

• CREATE OR REPLACE ROW ACCESS POLICY 陳述式會更新指定資料表中同名的現有資料列層級存取政策。

  重點回顧：

  • 資料表中的每個資料列層級存取權政策都必須有不重複的名稱。
  • 與 WHERE 子句類似，filter_expression 會比對您要向 grantee_list 成員顯示的資料。
  • 您可以在 grantee_list 清單中合併一系列使用者和群組，但必須以半形逗號分隔，並分別加上引號。
  • grantee_list 中的所有身分都必須存在。如果任何身分不存在，系統就不會建立政策，且陳述式會失敗。
  • 您無法對 JSON 資料欄套用資料列層級存取權政策。如要瞭解資料列層級安全性的其他限制，請參閱「限制」

範例

以下範例說明如何為不同類型的主體 ID (包括 Google 帳戶和聯合身分) 建立及更新資料列存取權政策。如要進一步瞭解聯合身分，請參閱「Workload Identity Federation」。

建立新政策並授予 Google 帳戶存取權

建立新的資料列存取政策。只有使用者 [e-mail] 才能存取資料表。只有 region = 'APAC' 的資料列會顯示：

CREATE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (region = 'APAC');

建立新政策，並將存取權授予員工身分集區中的單一身分

建立新的資料列存取政策。只有工作團隊身分集區中的單一身分可以存取資料表，格式如下：principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/IDENTITY。只有 region = 'APAC' 的資料列會顯示：

CREATE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('principal://iam.googleapis.com/locations/global/workforcePools/example-contractors/subject/[e-mail]')
FILTER USING (region = 'APAC');

更新政策，授予服務帳戶存取權

更新 apac_filter 存取權政策，套用至服務帳戶 example@exampleproject.：

CREATE OR REPLACE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('serviceAccount:example@exampleproject.')
FILTER USING (region = 'APAC');

建立政策並授予使用者和群組存取權

建立資料列存取政策，將存取權授予一位使用者和兩個群組：

CREATE ROW ACCESS POLICY sales_us_filter
ON project.dataset.my_table
GRANT TO ('user:[e-mail]',
          'group:[e-mail]',
          'group:[e-mail]')
FILTER USING (region = 'US');

建立政策，並將存取權授予群組中的員工身分

建立資料列存取權政策，並使用下列格式，將存取權授予群組中的所有員工身分principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/IDENTITY：

CREATE ROW ACCESS POLICY sales_us_filter
ON project.dataset.my_table
GRANT TO ('principal://iam.googleapis.com/locations/global/workforcePools/example-contractors/subject/[e-mail]',
          'principal://iam.googleapis.com/locations/global/workforcePools/example-contractors/subject/[e-mail]')
FILTER USING (region = 'US');

建立政策並授予所有已驗證使用者存取權

建立資料列存取權政策，並將 allAuthenticatedUsers 設為被授權者：

CREATE ROW ACCESS POLICY us_filter
ON project.dataset.my_table
GRANT TO ('allAuthenticatedUsers')
FILTER USING (region = 'US');

建立政策並根據目前使用者進行篩選

建立資料列存取權政策，並根據目前使用者設定篩選器：

CREATE ROW ACCESS POLICY my_row_filter
ON dataset.my_table
GRANT TO ('domain:example.com')
FILTER USING (email = SESSION_USER());

建立政策並篩選資料欄

建立資料列存取權政策，並對 ARRAY 類型的資料欄套用篩選器：

CREATE ROW ACCESS POLICY my_reports_filter
ON project.dataset.my_table
GRANT TO ('domain:example.com')
FILTER USING (SESSION_USER() IN UNNEST(reporting_chain));

建立政策並使用區域比較

建立含有子查詢的資料列存取政策，以取代為每位使用者設定區域比較的政策：

請看下表，lookup_table：

+-----------------+--------------+
|      email      |    region    |
+-----------------+--------------+
| [e-mail] | europe-west1 |
| [e-mail] | us-west1     |
| [e-mail] | us-west2     |
+-----------------+--------------+

CREATE OR REPLACE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('domain:example.com')
FILTER USING (region IN (
    SELECT
      region
    FROM
      lookup_table
    WHERE
      email = SESSION_USER()));

在 lookup_table 上使用子查詢，即可避免建立多個資料列存取權政策。舉例來說，上述陳述式產生的結果與下列陳述式相同，但查詢次數較少：

CREATE OR REPLACE ROW ACCESS POLICY us_filter
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (region IN ('us-west1', 'us-west2'));

CREATE OR REPLACE ROW ACCESS POLICY eu_filter
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (region = 'europe-west1');

如要進一步瞭解語法和可用選項，請參閱 CREATE ROW ACCESS POLICY DDL 陳述式參考資料。

合併資料列層級存取政策

如果兩項以上的資料列層級存取權政策，向使用者或群組授予相同資料表的存取權，則使用者或群組可以存取任何政策涵蓋的所有資料。舉例來說，下列政策會授予使用者 [e-mail] my_table 資料表中指定資料列的存取權：

CREATE ROW ACCESS POLICY shoes
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (product_category = 'shoes');

CREATE OR REPLACE ROW ACCESS POLICY blue_products
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (color = 'blue');

在上述範例中，使用者 [e-mail] 可以存取 my_table 資料表 中 product_category 欄位設為 shoes 的資料列 ，[e-mail] 也可以存取 color 欄位設為 blue 的資料列。 舉例來說，[e-mail] 可以存取包含紅色鞋子和藍色汽車資訊的資料列。

這項存取權等同於下列單一資料列層級存取權政策提供的存取權：

CREATE ROW ACCESS POLICY shoes_and_blue_products
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (product_category = 'shoes' OR color = 'blue');

另一方面，如要指定取決於多個條件是否為真的存取權，請使用含有 AND 運算子的篩選器。舉例來說，下列資料列層級存取權政策只會將 [e-mail] 存取權授予 product_category 欄位設為 shoes 且 color 欄位設為 blue 的資料列：

CREATE ROW ACCESS POLICY blue_shoes
ON project.dataset.my_table
GRANT TO ('user:[e-mail]')
FILTER USING (product_category = 'shoes' AND color = 'blue');

有了上述資料列層級存取權政策，[e-mail] 就能存取藍色鞋子的資訊，但無法存取紅色鞋子或藍色汽車的資訊。

列出資料表資料列層級存取權政策

您可以使用 Google Cloud 控制台、bq 指令列工具或 RowAccessPolicies.List API 方法，列出及查看資料表的所有資料列層級存取權政策。

所需權限

如要列出 BigQuery 資料表的資料列層級存取權政策，您必須具備 bigquery.rowAccessPolicies.list IAM 權限。

如要查看 BigQuery 資料表資料列層級存取權政策的成員，您必須具備 bigquery.rowAccessPolicies.getIamPolicy IAM 權限。

下列各項預先定義的 IAM 角色，都包含列出及查看資料列層級存取權政策所需的權限：

• roles/bigquery.admin
• roles/bigquery.dataOwner

如要進一步瞭解 BigQuery 的 IAM 角色和權限，請參閱「預先定義的角色和權限」。

列出資料表資料列層級存取權政策

如要列出資料列層級存取權政策，請按照下列步驟操作：

控制台

1. 如要查看資料列層級存取權政策，請前往 Google Cloud 控制台的 BigQuery 頁面。

   前往「BigQuery」

2. 按一下資料表名稱，開啟詳細資料窗格，然後依序點選「More」(更多) >「View row access policies」(查看資料列存取權政策)。

3. 「Row access policies」(資料列存取權政策) 面板開啟時，您會看到資料表上所有資料列層級存取權政策的清單 (依名稱排列)，以及各項政策的 filter_expression。

   

4. 如要查看受資料列層級存取權政策影響的所有角色和使用者，請按一下政策旁的「VIEW」(查看)。舉例來說，在下圖中，您可以在「View permissions」(查看權限) 面板中看到被授權者清單的成員具有 bigquery.filteredDataViewer 角色。

   

   重要事項： 在政策中新增及移除成員，只能使用 DDL 陳述式。

bq

輸入 bq ls 指令，並提供 --row_access_policies 旗標。必須提供資料集和資料表名稱。

    bq ls --row_access_policies dataset.table

舉例來說，下列指令會列出資料集 (ID 為 my_dataset) 中資料表 (名稱為 my_table) 的資料列層級存取權政策資訊：

    bq ls --row_access_policies my_dataset.my_table

API

使用 REST API 參考資料部分的 RowAccessPolicies.List 方法。

刪除資料列層級存取權政策

如果您具備相關權限，可以使用 DDL 陳述式刪除資料表中的一或多項資料列層級存取權政策。

所需權限

如要捨棄資料列層級存取權政策，您必須具備下列 IAM 權限：

• bigquery.rowAccessPolicies.delete
• bigquery.rowAccessPolicies.setIamPolicy
• bigquery.jobs.create (執行 DDL 查詢工作)

如要同時捨棄資料表的所有資料列層級存取權政策，您必須具備下列 IAM 權限：

• bigquery.rowAccessPolicies.delete
• bigquery.rowAccessPolicies.setIamPolicy
• bigquery.rowAccessPolicies.list
• bigquery.jobs.create (執行 DDL 查詢工作)

下列各項預先定義的 IAM 角色，都包含刪除資料列層級存取權政策所需的權限：

• roles/bigquery.admin
• roles/bigquery.dataOwner

如要進一步瞭解 BigQuery 的 IAM 角色和權限，請參閱「預先定義的角色和權限」。

刪除資料列層級存取權政策

如要從資料表刪除資料列存取權政策，請使用下列 DDL 陳述式：

• DROP ROW ACCESS POLICY 陳述式會刪除指定資料表的資料列層級存取權政策。

• 如果指定資料表有資料列存取權政策，DROP ROW ACCESS POLICY IF EXISTS 陳述式會刪除資料列層級存取權政策。

• DROP ALL ROW ACCESS POLICIES 陳述式會刪除指定資料表的所有資料列層級存取權政策。

重要事項： 您無法使用 DROP ROW ACCESS POLICY 刪除資料表的最後一項資料列層級存取權政策。否則會發生錯誤。如要刪除資料表的最後一項資料列層級存取權政策，請改用 DROP ALL ROW ACCESS POLICIES。如要進一步瞭解如何捨棄資料表的最後一項資料列層級存取權政策，請參閱「資料列層級安全性的最佳做法」。

範例

從資料表刪除資料列層級存取權政策：

DROP ROW ACCESS POLICY my_row_filter ON project.dataset.my_table;

刪除資料表中的所有資料列層級存取權政策：

DROP ALL ROW ACCESS POLICIES ON project.dataset.my_table;

如要進一步瞭解如何刪除資料列層級存取權政策，請參閱 DROP ROW ACCESS POLICY DDL 陳述式參考資料。

查詢設有資料列存取政策的資料表

使用者必須先具備 BigQuery 資料表的存取權，才能查詢該資料表，即使他們位於該資料表資料列存取政策的 grantee_list 也是如此。如果沒有這項權限，查詢就會失敗，並顯示 access denied 錯誤。

所需權限

如要查詢具有資料列層級存取權政策的 BigQuery 資料表，您必須具備資料表的 bigquery.tables.getData 權限。您也需要 bigquery.rowAccessPolicies.getFilteredData 權限。

如要透過預先定義的角色取得這些權限，您必須使用 IAM 取得資料表的 roles/bigquery.dataViewer 角色，並透過資料列層級存取權政策取得資料表的 roles/bigquery.filteredDataViewer IAM 角色。

注意： 請勿透過 IAM 直接將 bigquery.filteredDataViewer 角色套用至資源。bigquery.filteredDataViewer 是系統管理的角色。請務必使用資料列層級存取權政策授予角色。詳情請參閱「資料列層級安全性的最佳做法」。

您必須具備datacatalog.categories.fineGrainedGet權限，才能存取所有相關資料欄，並啟用資料欄層級安全性。如要透過預先定義的角色取得這項權限，您需要 datacatalog.categoryFineGrainedReader 角色。

查看查詢結果

在 Google Cloud 控制台中，當您查詢具有資料列層級存取權政策的資料表時，BigQuery 會顯示橫幅通知，指出結果可能會依資料列層級存取權政策篩選。即使您是政策的受益人清單成員，系統仍會顯示這則通知。

工作統計資料

使用 Job API 查詢具有資料列層級存取權政策的資料表時，BigQuery 會在 Job 回應物件中，指出查詢是否讀取任何具有資料列存取權政策的資料表：

範例

為求簡潔，這個 Job 物件回應已經過截斷：

{
  "configuration": {
    "jobType": "QUERY",
    "query": {
      "priority": "INTERACTIVE",
      "query": "SELECT * FROM dataset.table",
      "useLegacySql": false
    }
  },
  ...
  "statistics": {
    ...
    rowLevelSecurityStatistics: {
      rowLevelSecurityApplied: true
    },
    ...
  },
  "status": {
    "state": "DONE"
  },
  ...
}

後續步驟

• 如要瞭解資料列層級安全性如何與其他 BigQuery 功能和服務搭配運作，請參閱「搭配使用資料列層級安全性與其他 BigQuery 功能」。

• 如要瞭解資料列層級安全性的最佳做法，請參閱「BigQuery 資料列層級安全性的最佳做法」。