控管資料集存取權

本文件將說明如何在 BigQuery 中控管資料集的存取權。

您可以呼叫 datasets.insert API 方法，藉以在資料集建立期間套用存取權控管。

資料集建立期間，您無法透過 GCP 主控台、BigQuery 傳統網頁版 UI 或指令列工具套用存取權控管。

您可以透過以下方式，在建立資料集之後對資料集套用存取權控管：

使用傳統版 BigQuery 網頁版 UI
- 目前您無法使用 GCP 主控台指派存取權控管。
使用 bq update CLI 指令
呼叫 datasets.patch API 方法

總覽

您可以使用專案層級身分與存取權管理 (IAM) 角色和資料集層級存取權控管來共用 BigQuery 資料表和資料檢視的存取權。目前，您無法直接將存取權控制套用至資料表或資料檢視。

專案層級存取權控制可以決定要允許哪些使用者、群組和服務帳戶存取專案中的所有資料集、資料表、資料檢視及資料表資料。資料集層級存取權控制可以決定要允許哪些使用者、群組和服務帳戶存取特定資料集中的資料表、視圖及資料表資料。

例如，如果您將專案層級的 bigquery.dataOwner 角色指派給使用者，該使用者便可以建立、更新及刪除專案所有資料集中的資料表和資料檢視。如果您指派資料集層級的 OWNER 角色，則該使用者只能建立、更新及刪除該資料集中的資料表和資料檢視。資料集層級 OWNER 原始角色相當於授予資料集的 bigquery.dataOwner 角色。

如果您為使用者或群組指派專案層級限制較多的角色，則也必須授予個別資料集的存取權。例如，如果您授予使用者或群組專案層級的 bigquery.user 角色，則該使用者可以建立資料集，並且可以針對這些資料集中的資料表執行查詢工作。如要查詢資料集中並非由該使用者建立的資料表，您至少必須針對該使用者需要查詢的每個資料集，將資料集層級的 READER 存取權指派給該使用者。資料集層級 READER 原始角色相當於授予資料集的 bigquery.dataViewer 角色。

如要深入瞭解預先定義的專案層級身分與存取權管理角色和資料集層級存取權控管，請參閱存取權控管一文。

必要權限

如要指派或更新資料集存取權控管，您必須具備資料集層級的 OWNER 存取權，或者必須取得含有 bigquery.datasets.update 權限的專案層級身分與存取權管理角色。以下是擁有 bigquery.datasets.update 權限的預先定義專案層級身分與存取權管理角色：

此外，因為 bigquery.user 角色擁有 bigquery.datasets.create 權限，所以經指派為 bigquery.user 角色的使用者可以更新自己建立的任何資料集。當接受 bigquery.user 角色指派的使用者建立資料集時，該使用者即被授予該資料集的 OWNER 存取權。 OWNER 存取權可讓使用者完全控管該資料集。

如要深入瞭解 BigQuery 中的身分與存取權管理角色和權限，請參閱存取權控制一文。如要深入瞭解資料集層級角色，請參閱資料集的原始角色。

控管資料集存取權

如何指派資料集的存取權控管：

主控台

從「Resources」(資源) 中選取所需資料集，然後按一下視窗右側附近的 [Share dataset] (分享資料集)。
在「Share Dataset」(分享資料集) 面板的「Dataset permissions」(資料集權限) 分頁中，按一下 [Add members](新增成員)。
在「Add members」(新增成員) 面板中，輸入您想新增到「New members」(新成員) 文字方塊中的使用者或群組電子郵件地址。
針對「Select a role」(選取角色)，選取 [BigQuery] 並為新成員選擇合適的預先定義身分與存取權管理角色。如要進一步瞭解每個預先定義 BigQuery 角色獲指派的權限，請參閱存取權控管頁面的角色一節。
依序按一下 [Save] (儲存) 及 [Done] (完成)。

傳統版 UI

按一下資料集右側的下拉式箭頭，然後選擇 [Share Dataset](分享資料集)。
在「Share Dataset」(分享資料集) 對話方塊中，針對「Add People」(新增成員)，按一下欄位左側的下拉式選單，然後選擇適當的選項。當您使用傳統網頁版 UI 為資料集套用存取權控管時，可將存取權授予下列使用者和群組：
- 依電子郵件指定的使用者 - 將資料集的存取權授予個別 Google 帳戶
- 依電子郵件指定的群組 - 將資料集的存取權授予 Google 群組的所有成員
- 網域 - 將資料集的存取權授予某個 Google 網域中的所有使用者和群組
- 所有已驗證的使用者 - 將資料集的存取權授予所有 Google 帳戶持有人 (公開資料集)
- 專案擁有者 - 將資料集的存取權授予所有專案擁有者
- 專案檢視者 - 將資料集的存取權授予所有專案檢視者
- 專案編輯者 - 將資料集的存取權授予所有專案編輯者
- 已授權的資料檢視 - 將資料集的存取權授予某個資料檢視
  
  附註：擁有者 (projectOwners)、檢視者 (projectReaders) 和編輯者 (projectWriters) 都是原始專案層級角色。我們建議您改用身分與存取權管理專案層級角色。
在文字方塊中輸入值。例如，如果您選擇 [User by e-mail] (依電子郵件指定的使用者) 或 [Group by e-mail] (依電子郵件指定的群組)，請輸入使用者或群組的電子郵件地址。
在「Add People」(新增成員) 欄位的右側，按一下 [Can view] (可以檢視)，然後從清單中選擇適當的角色。
- [Can view] (可以檢視) (READER) 授予資料集 bigquery.dataViewer 存取權。
- [Can edit] (可以編輯) (WRITER) 授予資料集 bigquery.dataEditor 存取權。
- [Is owner] (是擁有者) (OWNER) 授予資料集 bigquery.dataOwner 存取權。
  
  如要深入瞭解這些資料集角色，請參閱資料集的原始角色。
按一下 [Add] (新增)，然後點選 [Save changes] (儲存變更)。

指令列

使用 show 指令將現有的資料集資訊 (包括存取權控制) 寫入 JSON 檔案。如果資料集位於預設專案以外的專案中，請使用下列格式將專案 ID 新增至資料集名稱： [PROJECT_ID]:[DATASET]。
```
bq show --format=prettyjson [PROJECT_ID]:[DATASET] > [PATH_TO_FILE]
```
其中：
- [PROJECT_ID] 是您的專案 ID。
- [DATASET] 是您的資料集名稱。
- [PATH_TO_FILE] 是您本機上的 JSON 檔案路徑。
  
  範例：
  
  輸入下列指令，將 mydataset 的存取權控管寫入 JSON 檔案。mydataset 位於預設專案中。
  
  bq show --format=prettyjson mydataset > /tmp/mydataset.json
  
  輸入下列指令，將 mydataset 的存取權控管寫入 JSON 檔案。mydataset 位於 myotherproject 中。
  
  bq show --format=prettyjson myotherproject:mydataset > /tmp/mydataset.json

變更 JSON 檔案的 "access" 區段。您可以新增或移除任何 specialGroup 項目：projectOwners、projectWriters、 projectReaders 和 allAuthenticatedUsers。您也可以新增、移除或修改下列任一項目： userByEmail、groupByEmail 和 domain。

例如，資料集 JSON 檔案的存取權區段會如下所示：

{
 "access": [
  {
   "role": "READER",
   "specialGroup": "projectReaders"
  },
  {
   "role": "WRITER",
   "specialGroup": "projectWriters"
  },
  {
   "role": "OWNER",
   "specialGroup": "projectOwners"
  },
  {
   "role": "READER",
   "specialGroup": "allAuthenticatedUsers"
  },
  {
   "role": "READER",
   "domain": "[DOMAIN_NAME]"
  },
  {
   "role": "WRITER",
   "userByEmail": "[USER_EMAIL]"
  },
  {
   "role": "READER",
   "groupByEmail": "[GROUP_EMAIL]"
  }
 ],
 ...
}

編輯完成後，請使用 update 指令並使用 --source 標記加入 JSON 檔案。如果資料集位於預設專案以外的專案中，請使用下列格式將專案 ID 新增至資料集名稱： [PROJECT_ID]:[DATASET]。

注意： 當您套用包含存取權控制的 JSON 檔案時，現有的存取權控制會遭到覆寫。
```
bq update --source [PATH_TO_FILE] [PROJECT_ID]:[DATASET]
```
其中：
- [PATH_TO_FILE] 是您本機上的 JSON 檔案路徑。
- [PROJECT_ID] 是您的專案 ID。
- [DATASET] 是您的資料集名稱。
  
  範例：
  
  輸入下列指令，更新 mydataset 的存取權控管。mydataset 位於預設專案中。
  
  bq update --source /tmp/mydataset.json mydataset
  
  輸入下列指令，更新 mydataset 的存取權控管。mydataset 位於 myotherproject 中。
  
  bq update --source /tmp/mydataset.json myotherproject:mydataset
如要驗證您的存取權控管變更，請再次輸入 show 指令，而不要將資訊寫入檔案。

bq show --format=prettyjson [DATASET]

或

bq show --format=prettyjson [PROJECT_ID]:[DATASET]

API

使用定義的資料集資源呼叫 datasets.insert，以便在建立資料集時套用存取權控管。呼叫 datasets.patch 並使用資料集資源中的 access 屬性更新您的存取權控管。

由於 datasets.update 方法會取代整個資料集資源，因此更新存取權控管時建議使用 datasets.patch 方法。

詳情請參閱資料集。

Go

利用資料集的存取權控制設定 dataset.access_entries 屬性。然後呼叫 client.update_dataset() 函式來更新屬性。

前往 GitHub 查看意見回饋

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
// Append a new access control entry to the existing access list.
update := bigquery.DatasetMetadataToUpdate{
	Access: append(meta.Access, &bigquery.AccessEntry{
		Role:       bigquery.ReaderRole,
		EntityType: bigquery.UserEmailEntity,
		Entity:     "sample.bigquery.dev@gmail.com"},
	),
}

// Leverage the ETag for the update to assert there's been no modifications to the
// dataset since the metadata was originally read.
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

在試行此示例之前，請至 BigQuery 快速入門導覽課程：使用用戶端程式庫，按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。

利用資料集的存取權控管設定 dataset.access_entries 屬性，然後呼叫 client.update_dataset() 函式來更新屬性。

前往 GitHub 查看意見回饋

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)

entry = bigquery.AccessEntry(
    role="READER",
    entity_type="userByEmail",
    entity_id="sample.bigquery.dev@gmail.com",
)

entries = list(dataset.access_entries)
entries.append(entry)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ["access_entries"])  # API request

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

後續步驟

如要進一步瞭解如何建立資料集，請參閱建立資料集一文。
如要進一步瞭解如何列出專案中的資料集，請參閱列出資料集一文。
要進一步瞭解資料集中繼資料，請參閱取得資料集相關資訊一文。
要進一步瞭解如何變更資料集屬性，請參閱更新資料集相關頁面。
要進一步瞭解如何建立及管理標籤，請參閱建立及管理標籤一文。

本頁內容對您是否有任何幫助？請提供意見：

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新：七月 2, 2019。

控管資料集存取權

總覽

必要權限

控管資料集存取權

主控台

傳統版 UI

指令列

API

Go

Python

後續步驟

傳送您對下列選項的寶貴意見...