控管資料集存取權

本文件將說明如何在 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.updatebigquery.datasets.get 權限,才能指派或更新資料集存取權控管。以下是包含 bigquery.datasets.updatebigquery.datasets.get 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataOwner
  • bigquery.admin

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

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

控管資料集存取權

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

主控台

  1. 從「Resources」(資源) 中選取資料集,然後點選視窗右側附近的 [Share dataset] (分享資料集)。

    將使用者加入資料集

  2. 在「Share Dataset」(分享資料集) 面板的「Dataset permissions」(資料集權限) 分頁中,點選 [Add members] (新增成員)。

  3. 在「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 帳戶的使用者
  4. 從「Select a role」(選取角色) 的清單中選取 [BigQuery],並為新成員選擇合適的預先定義身分與存取權管理角色。如要進一步瞭解每個預先定義 BigQuery 角色獲指派的權限,請參閱存取權控管頁面的角色一節。

  5. 按一下 [Done] (完成)

傳統版 UI

  1. 按一下資料集右側的下拉式箭頭,然後選擇 [Share Dataset] (分享資料集)。

  2. 在「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」(已授權的檢視表) - 將資料集的存取權授予特定檢視表

  3. 在文字方塊中輸入值。例如,如果您選擇 [User by e-mail] 或 [Group by e-mail],請輸入使用者或群組的電子郵件地址。

  4. 在「Add People」(新增成員) 欄位的右側,按一下 [Can view] (可以檢視),然後從清單中選擇適當的角色。

    將使用者加入資料集

  5. 按一下 [Add] (新增),然後按一下 [Save changes] (儲存變更)。

CLI

  1. 使用 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
    
  2. 變更 JSON 檔案的 "access" 區段。您可以新增或移除任何 specialGroup 項目:projectOwnersprojectWritersprojectReadersallAuthenticatedUsers。您也可以新增、移除或修改下列任何項目:userByEmailgroupByEmaildomain

    舉例來說,資料集 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"
      }
     ],
     ...
    }
    

  3. 完成編輯後,請使用 update 指令並利用 --source 旗標來納入 JSON 檔案。如果資料集屬於非預設專案,請使用下列格式將專案 ID 新增至資料集名稱:project_id:dataset

    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
    
  4. 如要驗證您的存取權控管設定變更,請再次輸入 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() 函式來更新屬性。

// 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() 函式來更新屬性。
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)
)

後續步驟