本頁面由 Cloud Translation API 翻譯而成。

使用資料列層級安全性

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

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

在資料表上建立或更新資料列層級存取政策
在資料表上結合資料列層級存取政策
列出資料表的資料列層級存取政策
從資料表刪除資料列層級存取權政策
使用資料列層級存取政策查詢資料表

注意： 在外部身分識別資訊提供者中管理使用者的存取權時，請將 Google 帳戶主要 ID 的例項 (例如 user:kiran@example.com、group:support@example.com 和 domain:example.com) 替換為適當的Workforce Identity Federation 主要 ID。

限制

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

事前準備

授予身分與存取權管理 (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 控制台中列出資料表的資料列層級存取權政策時，系統會顯示此角色，並與政策授予者清單的成員建立關聯。

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

如要建立或更新資料列層級存取權政策，請使用下列任一 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 清單中合併一系列使用者和群組。
- 您無法在 JSON 欄上套用資料列層級存取權政策。如要瞭解資料列層級安全防護機制的其他限制，請參閱「限制」一節。

範例

建立新的資料列存取權政策。只有使用者 abc@example.com 可以存取該資料表。只會顯示 region = 'APAC' 的資料列：

CREATE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (region = 'APAC');

請改為更新要套用至服務帳戶 example@exampleproject.iam.gserviceaccount.com 的存取權政策：

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

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

CREATE ROW ACCESS POLICY sales_us_filter
ON project.dataset.my_table
GRANT TO ('user:john@example.com',
          'group:sales-us@example.com',
          'group:sales-managers@example.com')
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    |
+-----------------+--------------+
| xyz@example.com | europe-west1 |
| abc@example.com | us-west1     |
| abc@example.com | 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 apac_filter
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (region IN ('us-west1', 'us-west2'));

CREATE OR REPLACE ROW ACCESS POLICY apac_filter
ON project.dataset.my_table
GRANT TO ('user:xyz@example.com')
FILTER USING (region = 'europe-west1');

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

結合資料列層級存取權政策

如果有兩個或更多資料列層級存取權政策授予使用者或群組存取相同資料表的權限，則使用者或群組可存取任何政策涵蓋的所有資料。舉例來說，下列政策會授予使用者 abc@example.com 對 my_table 資料表中指定資料列的存取權：

CREATE ROW ACCESS POLICY shoes
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (product_category = 'shoes');

CREATE OR REPLACE ROW ACCESS POLICY blue_products
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (color = 'blue');

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

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

CREATE ROW ACCESS POLICY shoes_and_blue_products
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (product_category = 'shoes' OR color = 'blue');

另一方面，如要指定依附多個條件為真值的存取權，請使用含有 AND 運算子的篩選器。舉例來說，下列資料列層級存取權政策只會授予 abc@example.com 存取權，且只有在 product_category 欄位設為 shoes 且 color 欄位設為 blue 的資料列才會授予存取權：

CREATE ROW ACCESS POLICY blue_shoes
ON project.dataset.my_table
GRANT TO ('user:abc@example.com')
FILTER USING (product_category = 'shoes' AND color = 'blue');

有了上述的資料列層級存取權政策，abc@example.com 就能存取藍色鞋子的資訊，但無法存取紅色鞋子或藍色汽車的資訊。

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

您可以使用 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 角色和權限，請參閱「預先定義的角色與權限」一文。

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

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

主控台

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

前往 BigQuery
按一下資料表名稱查看詳細資料，然後點選「View row access policies」(查看資料列存取權政策)。
當「資料列存取權政策」面板開啟時，您會看到資料表中所有資料列層級存取權政策的清單，並依名稱和每項政策的 filter_expression 排序。
如要查看資料列層級存取權政策影響的所有角色和使用者，請按一下政策旁的「查看」。舉例來說，在下圖的「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 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 角色。

您必須在所有相關的資料欄層級安全防護機制中，具備 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 資料列層級安全性的最佳做法。

使用資料列層級安全性

限制

事前準備

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

所需權限

bigquery.filteredDataViewer 角色

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

範例

結合資料列層級存取權政策

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

所需權限

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

主控台

bq

API

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

所需權限

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

範例

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

所需權限

查看查詢結果

工作統計資料

範例

後續步驟

`bigquery.filteredDataViewer` 角色