控管資料集存取權

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

您也可以在 Cloud IAM 資源階層中的較高層級設定 BigQuery 權限。如要進一步瞭解 Cloud IAM 資源階層，請參閱 Cloud IAM 說明文件中的使用資源階層控管存取權頁面。

總覽

目前，您無法授予資料表、檢視表、資料欄或資料列的權限。資料集是 BigQuery 支援存取權控管的最低層級資源。

資料集層級權限可以決定要允許哪些使用者、群組和服務帳戶存取特定資料集中的資料表、檢視表及資料表資料。舉例來說，如果您將 bigquery.dataOwner Cloud IAM 角色授予特定資料集的使用者，該使用者即可建立、更新及刪除資料集中的資料表和檢視表。

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

透過 Cloud Console、BigQuery 傳統網頁版 UI 或指令列工具建立資料集時，您無法套用存取權控管設定。

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

使用 Cloud Console 或 BigQuery 傳統網頁版 UI
使用 bq update CLI 指令
呼叫 datasets.patch API 方法
使用用戶端程式庫

所需權限

您至少要具備 bigquery.datasets.update 和 bigquery.datasets.get 權限，才能指派或更新資料集存取權控管。以下是包含 bigquery.datasets.update 和 bigquery.datasets.get 權限的預先定義 Cloud IAM 角色：

bigquery.dataOwner
bigquery.admin

此外，當具備 bigquery.datasets.create 權限的使用者建立資料集時，該使用者會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者更新自己建立的資料集。

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

控管資料集存取權

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

主控台

從「Resources」(資源) 中選取資料集，然後點選視窗右側附近的 [Share dataset] (分享資料集)。
在「Share Dataset」(分享資料集) 面板的「Dataset permissions」(資料集權限) 分頁中，點選 [Add members] (新增成員)。
在「Add members」(新增成員) 面板中，於「New members」(新成員) 文字方塊中輸入您要新增的實體。您可以新增下列任何實體：
- 「Google account e-mail」(Google 帳戶電子郵件地址)：授予個人 Google 帳戶存取資料集的權限
- 「Google Group」(Google 群組)：將資料集存取權限授予 Google 群組的所有成員
- 「Google Apps Domain」(Google Apps 網域)：將資料集的存取權限授予特定 Google 網域中的所有使用者和群組
- 「Service account」(服務帳戶)：將資料集的存取權限授予服務帳戶
- 「Anybody」(任何人)：輸入「allUsers」即可將存取權限授予一般大眾
- 「All Google accounts」(所有 Google 帳戶)：輸入「allAuthenticatedUsers」即可將存取權授予任何登入 Google 帳戶的使用者
注意：如要將授權檢視表新增到資料集的存取權控管，您必須使用傳統網頁版 UI。如要進一步瞭解授權檢視表，請參閱建立授權的檢視表一文。
從「Select a role」(選取角色) 的清單中選取 [BigQuery]，並為新成員選擇合適的預先定義身分與存取權管理角色。如要進一步瞭解每個預先定義 BigQuery 角色獲指派的權限，請參閱存取權控管頁面的角色一節。
按一下 [Done] (完成)。

傳統版 UI

按一下資料集右側的下拉式箭頭，然後選擇 [Share Dataset] (分享資料集)。
在「Share Dataset」對話方塊中，針對「Add People」，按一下欄位左側的下拉式選單，然後選擇適當的選項。當您使用傳統網頁版 UI 為資料集套用存取權控管時，可將存取權授予下列使用者和群組：
- 「User by e-mail」(依電子郵件指定的使用者) - 將資料集的存取權授予個別 Google 帳戶
- 「Group by e-mail」(依電子郵件指定的群組) - 將資料集的存取權授予 Google 群組的所有成員
- 「Domain」(網域) - 將資料集的存取權授予特定 Google 網域中的所有使用者和群組
- [All Authenticated Users] - 將資料集的存取權授予所有 Google 帳戶持有人 (公開資料集)
- [Project Owners] - 將資料集的存取權授予所有專案擁有者
- [Project Viewers] - 將資料集的存取權授予所有專案檢視者
- [Project Editors] - 將資料集的存取權授予所有專案編輯者
- 「Authorized View」(已授權的檢視表) - 將資料集的存取權授予特定檢視表
  
  附註：擁有者 (projectOwners)、檢視者 (projectReaders) 和編輯者 (projectWriters) 都是原始專案層級角色。建議您改用預先定義的 Cloud IAM 角色。
在文字方塊中輸入值。例如，如果您選擇 [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] (儲存變更)。

CLI

使用 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 檔案。位於預設專案中。
```
  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

在試行這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考資料說明文件。

利用資料集的存取權控制設定 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)
)

後續步驟

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