使用 IAM 控管資源的存取權

本文說明如何查看、授予及撤銷 BigQuery 資料集和資料集內資源 (資料表、檢視區塊和常式) 的存取權控管。雖然模型也是資料集層級的資源，但您無法使用 IAM 角色授予個別模型的存取權。

您可以透過 Google Cloud 允許政策，授予資源的存取權。這類政策又稱為 Identity and Access Management (IAM) 政策，會附加於資源。每個資源只能附加一項允許政策。 允許政策會控管資源本身的存取權，以及繼承允許政策的任何資源後代。

如要進一步瞭解允許政策，請參閱 IAM 說明文件中的「政策結構」。

本文假設您已熟悉 Google Cloud中的身分與存取權管理 (IAM)。

限制

• 複製的日常安排不會包含日常安排存取控制清單 (ACL)。
• 外部或連結資料集中的常式不支援存取控制項。
• 外部或連結資料集中的資料表不支援存取控制項。
• 無法使用 Terraform 設定日常安排存取權控管機制。
• 您無法使用 Google Cloud SDK 設定例行存取控管機制。
• 無法使用 BigQuery 資料控管語言 (DCL) 設定例行存取權控管。
• Data Catalog 不支援例行存取權控管。如果使用者已有條件地授予常式層級存取權，他們就不會在 BigQuery 側邊面板中看到自己的常式。如要解決這個問題，請改為授予資料集層級的存取權。
• 「INFORMATION_SCHEMA.OBJECT_PRIVILEGES」檢視畫面不會顯示日常作業的存取權控管。

事前準備

授予身分與存取權管理 (IAM) 角色，讓使用者取得執行本文各項工作所需的權限。

必要的角色

如要取得修改資源 IAM 政策所需的權限，請要求管理員授予您專案的 BigQuery 資料擁有者 (roles/bigquery.dataOwner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備修改資源 IAM 政策所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要修改資源的 IAM 政策，必須具備下列權限：

• 如要取得資料集的存取權政策： bigquery.datasets.get
• 如要設定資料集的存取權政策，請按照下列步驟操作： bigquery.datasets.update
• 如要取得資料集的存取權政策 (僅限Google Cloud 控制台)： bigquery.datasets.getIamPolicy
• 如何設定資料集的存取權政策 (僅限使用控制台)： bigquery.datasets.setIamPolicy
• 如要取得資料表或檢視區塊的政策： bigquery.tables.getIamPolicy
• 如要設定資料表或檢視區塊的政策： bigquery.tables.setIamPolicy
• 如要取得日常作業的存取權政策： bigquery.routines.getIamPolicy
• 如何設定日常安排的存取權政策： bigquery.routines.setIamPolicy
• 如要建立 bq 工具或 SQL BigQuery 工作 (選用)： bigquery.jobs.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

使用資料集存取權控制

您可以授予 IAM 主體預先定義或自訂的角色，決定主體在資料集中的權限，藉此提供資料集存取權。這也稱為將「允許政策」附加至資源。授予存取權後，您可以查看資料集的存取權控管設定，也可以撤銷資料集的存取權。

授予資料集存取權

使用 BigQuery 網頁版 UI 或 bq 指令列工具建立資料集時，無法授予資料集存取權。您必須先建立資料集，再授予存取權。API 可讓您在建立資料集時，透過呼叫 datasets.insert 方法，搭配已定義的資料集資源，授予存取權。

專案是資料集的父項資源，而資料集則是資料表、檢視表、常式和模型的父項資源。在專案層級授予角色時，資料集和資料集資源會繼承該角色及其權限。同樣地，在資料集層級授予角色時，該角色及其權限會由資料集內的資源繼承。

您可以授予 IAM 角色，提供資料集存取權，或使用 IAM 條件有條件地授予存取權。如要進一步瞭解如何授予有條件的存取權，請參閱「使用 IAM 條件控管存取權」。

注意： 授予資料集存取權後，系統不會自動在「探索工具」窗格中列出該資料集。如要在「Explorer」窗格中查看專案，請參閱「為專案加上星號」一節。

如要授予 IAM 角色資料集存取權，但不想使用條件，請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中展開專案，然後選取要共用的資料集。

3. 依序點選 「共用」「權限」。

4. 按一下 「新增主體」。

5. 在「New principals」(新增主體) 欄位中輸入主體。

6. 在「選取角色」清單中，選取預先定義的角色或自訂角色。

7. 按一下 [儲存]。

8. 如要返回資料集資訊，請按一下「關閉」。

SQL

如要授予主體資料集存取權，請使用 GRANT DCL 陳述式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   GRANT `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   TO "USER_LIST"

   取代下列項目：

   • ROLE_LIST：要授予的角色或以半形逗號分隔的角色清單
   • RESOURCE_NAME：您要授予存取權的資料集名稱

   • USER_LIST：以半形逗號分隔的使用者清單，當中列有獲派角色的使用者

     如需有效格式的清單，請參閱 user_list。

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

以下範例會將 BigQuery 資料檢視者角色授予 myDataset：

GRANT `roles/bigquery.dataViewer`
ON SCHEMA `myProject`.myDataset
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要將現有資料集的資訊 (包括存取權控管設定) 寫入 JSON 檔案，請使用 bq show 指令：

   bq show \
       --format=prettyjson \
       PROJECT_ID:DATASET > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：資料集名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑

3. 變更 JSON 檔案的 access 區段。您可以新增任何 specialGroup 項目：projectOwners、projectWriters、projectReaders 和 allAuthenticatedUsers。您也可以新增下列任何項目：userByEmail、groupByEmail 和 domain。

   舉例來說，資料集 JSON 檔案中的 access 區段應會與以下內容類似：

   {
    "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"
     }
    ],
    ...
   }

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

   注意：如果您套用了含有存取權控管設定的 JSON 檔案，現有的存取權控管設定會遭到覆寫。

     bq update 
   
     --source PATH_TO_FILE 
   
     PROJECT_ID:DATASET
     

5. 如要驗證存取權控管設定變更，請再次使用 bq show 指令，但不要將資訊寫入檔案：

   bq show --format=prettyjson PROJECT_ID:DATASET

Terraform

使用 google_bigquery_dataset_iam 資源更新資料集的存取權。

重要事項： google_bigquery_dataset_iam 提供的不同資源可能會彼此衝突，也可能與 google_bigquery_dataset_access 資源衝突。使用 Terraform 變更存取權控管設定前，請詳閱google_bigquery_dataset_iam說明文件。

設定資料集的存取權政策

以下範例說明如何使用 google_bigquery_dataset_iam_policy 資源，為 mydataset 資料集設定 IAM 政策。這會取代已附加至資料集的現有政策：

# This file sets the IAM policy for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.admin"
    members = [
      "user:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "group:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataEditor"
    members = [
      "serviceAccount:[e-mail]",
    ]
  }
}

resource "google_bigquery_dataset_iam_policy" "dataset_iam_policy" {
  dataset_id  = google_bigquery_dataset.default.dataset_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

設定資料集的角色成員資格

以下範例說明如何使用 google_bigquery_dataset_iam_binding 資源，為 mydataset 資料集設定特定角色的成員資格。這會取代該角色現有的任何成員資格。 資料集 IAM 政策中的其他角色會保留：

# This file sets membership in an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_binding" "dataset_iam_binding" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.jobUser"

  members = [
    "user:[e-mail]",
    "group:[e-mail]"
  ]
}

為單一主體設定角色成員資格

以下範例說明如何使用 google_bigquery_dataset_iam_member 資源更新 mydataset 資料集的 IAM 政策，將角色授予一個主體。更新這項 IAM 政策不會影響已獲授資料集角色的任何其他主體存取權。

# This file adds a member to an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_member" "dataset_iam_member" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.user"
  member     = "user:[e-mail]"
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

API

如要在建立資料集時套用存取權控管設定，請使用定義的資料集資源呼叫 datasets.insert 方法。如要更新存取權控管設定，請呼叫 datasets.patch 方法，並使用 Dataset 資源中的 access 屬性。

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

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

將新項目附加至現有清單，藉此設定新的存取清單 (使用 DatasetMetadataToUpdate 型別)。然後呼叫 dataset.Update() 函式來更新屬性。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// grantAccessToDataset creates a new ACL conceding the READER role to the group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func grantAccessToDataset(w io.Writer, projectID, datasetID string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"

	ctx := context.Background()

	// Create BigQuery handler.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Create dataset handler
	dataset := client.Dataset(datasetID)

	// Get metadata
	meta, err := dataset.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Metadata: %w", err)
	}

	// Find more details about BigQuery Entity Types here:
	// https://pkg.go.dev/cloud.google.com/go/bigquery#EntityType
	//
	// Find more details about BigQuery Access Roles here:
	// https://pkg.go.dev/cloud.google.com/go/bigquery#AccessRole

	entityType := bigquery.GroupEmailEntity
	entityID := "[e-mail]"
	roleType := bigquery.ReaderRole

	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       roleType,
			EntityType: entityType,
			Entity:     entityID,
		}),
	}

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

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)
	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entities: %v\n", access.Entity)
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Entity;
import com.google.cloud.bigquery.Acl.Group;
import com.google.cloud.bigquery.Acl.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.ArrayList;
import java.util.List;

public class GrantAccessToDataset {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Group to add to the ACL
    String entityEmail = "[e-mail]";

    grantAccessToDataset(projectId, datasetName, entityEmail);
  }

  public static void grantAccessToDataset(
      String projectId, String datasetName, String entityEmail) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Create a new Entity with the corresponding type and email
      // "[e-mail]"
      // For more information on the types of Entities available see:
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity
      // and
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity.Type
      Entity entity = new Group(entityEmail);

      // Create a new ACL granting the READER role to the group with the entity email
      // "[e-mail]"
      // For more information on the types of ACLs available see:
      // https://cloud.google.com/storage/docs/access-control/lists
      Acl newEntry = Acl.of(entity, Role.READER);

      // Get a copy of the ACLs list from the dataset and append the new entry.
      List<Acl> acls = new ArrayList<>(dataset.getAcl());
      acls.add(newEntry);

      // Update the ACLs by setting the new list.
      Dataset updatedDataset = bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println(
          "ACLs of dataset \""
              + updatedDataset.getDatasetId().getDataset()
              + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("ACLs were not updated \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Dataset#metadata 方法，將新項目附加至現有清單，藉此設定新的存取清單。然後呼叫 Dataset#setMetadata() 函式來更新屬性。

/**
 * TODO(developer): Update and un-comment below lines.
 */

// const datasetId = "my_project_id.my_dataset_name";

// ID of the user or group from whom you are adding access.
// const entityId = "[e-mail]";

// One of the "Basic roles for datasets" described here:
// https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
// const role = "READER";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

// Type of entity you are granting access to.
// Find allowed allowed entity type names here:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#resource:-dataset
const entityType = 'groupByEmail';

async function grantAccessToDataset() {
  const [dataset] = await client.dataset(datasetId).get();

  // The 'access entries' array is immutable. Create a copy for modifications.
  const entries = [...dataset.metadata.access];

  // Append an AccessEntry to grant the role to a dataset.
  // Find more details about the AccessEntry object in the BigQuery documentation:
  // https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
  entries.push({
    role,
    [entityType]: entityId,
  });

  // Assign the array of AccessEntries back to the dataset.
  const metadata = {
    access: entries,
  };

  // Update will only succeed if the dataset
  // has not been modified externally since retrieval.
  //
  // See the BigQuery client library documentation for more details on metadata updates:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest

  // Update just the 'access entries' property of the dataset.
  await client.dataset(datasetId).setMetadata(metadata);

  console.log(
    `Role '${role}' granted for entity '${entityId}' in '${datasetId}'.`
  );
}

Python

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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

from google.api_core.exceptions import PreconditionFailed
from google.cloud import bigquery
from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Update and uncomment the lines below.

# ID of the dataset to grant access to.
# dataset_id = "my_project_id.my_dataset"

# ID of the user or group receiving access to the dataset.
# Alternatively, the JSON REST API representation of the entity,
# such as the view's table reference.
# entity_id = "[e-mail]"

# One of the "Basic roles for datasets" described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
# role = "READER"

# Type of entity you are granting access to.
# Find allowed allowed entity type names here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/enums#class-googlecloudbigqueryenumsentitytypesvalue
entity_type = EntityTypes.GROUP_BY_EMAIL

# Instantiate a client.
client = bigquery.Client()

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# The `access_entries` list is immutable. Create a copy for modifications.
entries = list(dataset.access_entries)

# Append an AccessEntry to grant the role to a dataset.
# Find more details about the AccessEntry object here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)

# Assign the list of AccessEntries back to the dataset.
dataset.access_entries = entries

# Update will only succeed if the dataset
# has not been modified externally since retrieval.
#
# See the BigQuery client library documentation for more details on `update_dataset`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client#google_cloud_bigquery_client_Client_update_dataset
try:
    # Update just the `access_entries` property of the dataset.
    dataset = client.update_dataset(
        dataset,
        ["access_entries"],
    )

    # Show a success message.
    full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
    print(
        f"Role '{role}' granted for entity '{entity_id}'"
        f" in dataset '{full_dataset_id}'."
    )
except PreconditionFailed:  # A read-modify-write error
    print(
        f"Dataset '{dataset.dataset_id}' was modified remotely before this update. "
        "Fetch the latest version and retry."
    )

授予資料集存取權的預先定義角色

您可以授予下列 IAM 預先定義角色資料集存取權。

注意： 雖然可以授予資料集的 BigQuery 管理員或 BigQuery Studio 管理員權限，但請勿在資料集層級授予這些角色。BigQuery 資料擁有者也會授予資料集的所有權限，且是權限較低的角色。BigQuery 管理員和 BigQuery Studio 管理員通常是在專案層級授予。

角色	說明
BigQuery 資料擁有者 (roles/bigquery.dataOwner)	如果授予資料集權限，這個角色會提供下列權限： 資料集和資料集內所有資源 (資料表和檢視表、模型和處理常式) 的所有權限。 注意：在專案層級獲派資料擁有者角色的主體，也可以建立新資料集，並列出他們有權存取的專案資料集。
BigQuery 資料編輯者 (roles/bigquery.dataEditor)	如果授予資料集權限，這個角色會提供下列權限： 取得資料集的中繼資料和權限。 資料表和檢視畫面： 建立、更新、取得、列出及刪除資料集的資料表和檢視區塊。 讀取 (查詢)、匯出、複製及更新資料表資料。 建立、更新及刪除索引。 建立及還原快照。 具備資料集常式和模型的所有權限。 注意：在專案層級獲派資料編輯者角色的主體，也可以建立新的資料集，並列出他們有權存取的專案資料集。
BigQuery 資料檢視者 (roles/bigquery.dataViewer)	如果授予資料集權限，這個角色會提供下列權限： 取得資料集的中繼資料和權限。 列出資料集的資料表、檢視區塊和模型。 取得資料集資料表和檢視區塊的中繼資料和存取權控管。 讀取 (查詢)、複製及匯出資料表資料，並建立快照。 列出及叫用資料集的處理常式。
BigQuery 中繼資料檢視器 (roles/bigquery.metadataViewer)	如果授予資料集權限，這個角色會提供下列權限： 取得資料集的中繼資料和存取權控制。 取得資料表和檢視區塊的中繼資料和存取權控制。 從資料集的模型和常式取得中繼資料。 列出資料集中的資料表、檢視區塊、模型和常式。

資料集權限

開頭為 bigquery.datasets 的權限大多適用於資料集層級。 bigquery.datasets.create 不支援。如要建立資料集，必須在父項容器 (專案) 上授予角色 bigquery.datasets.create 權限。

下表列出資料集的所有權限，以及可套用權限的最低層級資源。

權限	資源	動作
bigquery.datasets.create	專案	在專案中建立新資料集。
bigquery.datasets.get	資料集	取得資料集的中繼資料和存取權控制。如要在控制台中查看權限，也必須具備 bigquery.datasets.getIamPolicy 權限。
bigquery.datasets.getIamPolicy	資料集	控制台需要這項權限，才能授予使用者權限，取得資料集的存取控制項。失敗時維持開放狀態。此外，控制台也需要 bigquery.datasets.get 權限才能查看資料集。
bigquery.datasets.update	資料集	更新資料集的中繼資料和存取權控管設定。在控制台中更新存取權控管時，也需要 bigquery.datasets.setIamPolicy 權限。
bigquery.datasets.setIamPolicy	資料集	控制台需要這項權限，才能授予使用者設定資料集存取控制項的權限。失敗時維持開放狀態。此外，控制台也需要 bigquery.datasets.update 權限才能更新資料集。
bigquery.datasets.delete	資料集	刪除資料集。
bigquery.datasets.createTagBinding	資料集	將標記附加至資料集。
bigquery.datasets.deleteTagBinding	資料集	從資料集卸離標籤。
bigquery.datasets.listTagBindings	資料集	列出資料集的標記。
bigquery.datasets.listEffectiveTags	資料集	列出資料集的有效標記 (已套用和已繼承)。
bigquery.datasets.link	資料集	建立 連結的資料集。
bigquery.datasets.listSharedDatasetUsage	專案	列出您在專案中可存取資料集的共用資料集使用統計資料。您必須要有這個權限，才能查詢 INFORMATION_SCHEMA.SHARED_DATASET_USAGE 檢視畫面。

查看資料集的存取權控制

您可以選擇下列任一選項，查看資料集的明確設定存取權控管。如要查看繼承的角色，請使用 BigQuery 網頁版 UI 存取資料集。

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中展開專案並選取資料集。

3. 依序點選 「共用」>「權限」。

   資料集的存取權控管會顯示在「資料集權限」窗格中。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要取得現有政策並以 JSON 格式輸出至本機檔案，請在 Cloud Shell 中使用 bq show 指令：

   bq show \
      --format=prettyjson \
      PROJECT_ID:DATASET > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：資料集名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑

SQL

預先發布版

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

查詢 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 檢視區塊。 如要查詢資料集的存取權控管，必須指定 object_name。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   SELECT
   COLUMN_LIST
   FROM
     PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
   WHERE
   object_name = "DATASET";

   取代下列項目：

   • COLUMN_LIST：以逗號分隔的清單，當中列有INFORMATION_SCHEMA.OBJECT_PRIVILEGES 檢視區塊的資料欄
   • PROJECT_ID：您的專案 ID
   • REGION：區域限定符
   • DATASET：專案中資料集的名稱

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

範例：

這項查詢會取得 mydataset 的存取權控管。

SELECT
object_name, privilege_type, grantee
FROM
my_project.`region-us`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
WHERE
object_name = "mydataset";

輸出內容應如下所示：

+------------------+-----------------------------+-------------------------+
|   object_name    |  privilege_type             | grantee                 |
+------------------+-----------------------------+-------------------------+
| mydataset        | roles/bigquery.dataOwner    | projectOwner:myproject  |
| mydataset        | roles/bigquery.dataViwer    | user:[e-mail]   |
+------------------+-----------------------------+-------------------------+

API

如要查看資料集的存取權控管設定，請呼叫 datasets.get 方法，搭配已定義的dataset 資源。

存取權控管會顯示在 dataset 資源的 access 屬性中。

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫 client.Dataset().Metadata() 函式。存取權政策位於 Access 屬性中。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// viewDatasetAccessPolicies retrieves the ACL for the given dataset
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func viewDatasetAccessPolicies(w io.Writer, projectID, datasetID string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"

	ctx := context.Background()

	// Create new client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get dataset's metadata.
	meta, err := client.Dataset(datasetID).Metadata(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Client.Dataset.Metadata: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)

	// Iterate over access permissions.
	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entity: %v\n", access.Entity)
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.List;

public class GetDatasetAccessPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    getDatasetAccessPolicy(projectId, datasetName);
  }

  public static void getDatasetAccessPolicy(String projectId, String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Show ACL details.
      // Find more information about ACL and the Acl Class here:
      // https://cloud.google.com/storage/docs/access-control/lists
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl
      List<Acl> acls = dataset.getAcl();
      System.out.println("ACLs in dataset \"" + dataset.getDatasetId().getDataset() + "\":");
      System.out.println(acls.toString());
      for (Acl acl : acls) {
        System.out.println();
        System.out.println("Role: " + acl.getRole());
        System.out.println("Entity: " + acl.getEntity());
      }
    } catch (BigQueryException e) {
      System.out.println("ACLs info not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Dataset#getMetadata() 函式擷取資料集中繼資料。 存取權政策位於產生的中繼資料物件的 access 屬性中。

/**
 * TODO(developer): Update and un-comment below lines
 */
// const datasetId = "my_project_id.my_dataset";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const bigquery = new BigQuery();

async function viewDatasetAccessPolicy() {
  const dataset = bigquery.dataset(datasetId);

  const [metadata] = await dataset.getMetadata();
  const accessEntries = metadata.access || [];

  // Show the list of AccessEntry objects.
  // More details about the AccessEntry object in the BigQuery documentation:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest
  console.log(
    `${accessEntries.length} Access entries in dataset '${datasetId}':`
  );
  for (const accessEntry of accessEntries) {
    console.log(`Role: ${accessEntry.role || 'null'}`);
    console.log(`Special group: ${accessEntry.specialGroup || 'null'}`);
    console.log(`User by Email: ${accessEntry.userByEmail || 'null'}`);
  }
}

Python

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫 client.get_dataset() 函式。存取政策位於 dataset.access_entries 屬性。

from google.cloud import bigquery

# Instantiate a client.
client = bigquery.Client()

# TODO(developer): Update and uncomment the lines below.

# Dataset from which to get the access policy.
# dataset_id = "my_dataset"

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# Show the list of AccessEntry objects.
# More details about the AccessEntry object here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
print(
    f"{len(dataset.access_entries)} Access entries found "
    f"in dataset '{dataset_id}':"
)

for access_entry in dataset.access_entries:
    print()
    print(f"Role: {access_entry.role}")
    print(f"Special group: {access_entry.special_group}")
    print(f"User by Email: {access_entry.user_by_email}")

撤銷資料集存取權

如要撤銷資料集的存取權，請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」面板中展開專案並選取資料集。

3. 在詳細資料面板中，依序點選「共用」>「權限」。

4. 在「資料集權限」對話方塊中，展開要撤銷存取權的主體。

5. 按一下 「移除主體」。

6. 在「要移除主體的角色嗎？」對話方塊中，按一下「移除」。

7. 如要返回資料集詳細資料，請按一下「關閉」。

注意： 如果無法撤銷資料集的存取權，主體可能是從資源階層中較高的層級繼承存取權。

SQL

如要移除主體的資料集存取權，請使用 REVOKE DCL 陳述式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   REVOKE `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   FROM "USER_LIST"

   取代下列項目：

   • ROLE_LIST：要撤銷的角色或以半形逗號分隔的角色清單
   • RESOURCE_NAME：要撤銷權限的資源名稱

   • USER_LIST：以逗號分隔的使用者清單，這些使用者的角色將遭到撤銷

     如需有效格式的清單，請參閱 user_list。

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

以下範例會撤銷 myDataset 的 BigQuery 資料擁有者角色：

REVOKE `roles/bigquery.dataOwner`
ON SCHEMA `myProject`.myDataset
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要將現有資料集的資訊 (包括存取權控管設定) 寫入 JSON 檔案，請使用 bq show 指令：

   bq show \
       --format=prettyjson \
       PROJECT_ID:DATASET > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：資料集名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑

3. 變更 JSON 檔案的 access 區段。您可以移除任何 specialGroup 項目：projectOwners、projectWriters、projectReaders 和 allAuthenticatedUsers。您也可以移除下列任何項目：userByEmail、groupByEmail 和 domain。

   舉例來說，資料集 JSON 檔案中的 access 區段應會與以下內容類似：

   {
    "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"
     }
    ],
    ...
   }

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

   注意：如果您套用了含有存取權控管設定的 JSON 檔案，現有的存取權控管設定會遭到覆寫。

     bq update 
   
         --source PATH_TO_FILE 
   
         PROJECT_ID:DATASET
     

5. 如要驗證存取權控管設定變更，請使用 show 指令，但不要將資訊寫入檔案：

   bq show --format=prettyjson PROJECT_ID:DATASET

API

呼叫 datasets.patch 方法，並使用 Dataset 資源中的 access 屬性更新存取權控管設定。

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

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

從現有清單中移除 DatasetMetadataToUpdate 類型的項目，藉此設定新的存取清單。 然後呼叫 dataset.Update() 函式來更新屬性。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// revokeAccessToDataset creates a new ACL removing the dataset access to "[e-mail]" entity
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func revokeAccessToDataset(w io.Writer, projectID, datasetID, entity string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// entity := "[e-mail]"

	ctx := context.Background()

	// Create BigQuery client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get dataset handler
	dataset := client.Dataset(datasetID)

	// Get dataset metadata
	meta, err := dataset.Metadata(ctx)
	if err != nil {
		return err
	}

	// Create new access entry list by copying the existing and omiting the access entry entity value
	var newAccessList []*bigquery.AccessEntry
	for _, entry := range meta.Access {
		if entry.Entity != entity {
			newAccessList = append(newAccessList, entry)
		}
	}

	// Only proceed with update if something in the access list was removed.
	// Additionally, we use the ETag from the initial metadata to ensure no
	// other changes were made to the access list in the interim.
	if len(newAccessList) < len(meta.Access) {
		update := bigquery.DatasetMetadataToUpdate{
			Access: newAccessList,
		}
		meta, err = dataset.Update(ctx, update, meta.ETag)
		if err != nil {
			return err
		}
	} else {
		return fmt.Errorf("any access entry was revoked")
	}

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)

	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entity: %v\n", access.Entity)
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Entity;
import com.google.cloud.bigquery.Acl.Group;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.List;

public class RevokeDatasetAccess {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Group to remove from the ACL
    String entityEmail = "[e-mail]";

    revokeDatasetAccess(projectId, datasetName, entityEmail);
  }

  public static void revokeDatasetAccess(String projectId, String datasetName, String entityEmail) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Create a new Entity with the corresponding type and email
      // "[e-mail]"
      // For more information on the types of Entities available see:
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity
      // and
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity.Type
      Entity entity = new Group(entityEmail);

      // To revoke access to a dataset, remove elements from the Acl list.
      // Find more information about ACL and the Acl Class here:
      // https://cloud.google.com/storage/docs/access-control/lists
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl
      // Remove the entity from the ACLs list.
      List<Acl> acls =
          dataset.getAcl().stream().filter(acl -> !acl.getEntity().equals(entity)).toList();

      // Update the ACLs by setting the new list.
      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("ACLs of \"" + datasetName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("ACLs were not updated \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Dataset#get() 方法擷取目前的中繼資料，然後從現有清單中移除指定項目，即可更新資料集存取清單。修改存取權屬性，排除所需實體，然後呼叫 Dataset#setMetadata() 函式，套用更新後的存取權清單。

/**
 * TODO(developer): Update and un-comment below lines
 */

// const datasetId = "my_project_id.my_dataset"

// ID of the user or group from whom you are revoking access.
// const entityId = "[e-mail]"

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const bigquery = new BigQuery();

async function revokeDatasetAccess() {
  const [dataset] = await bigquery.dataset(datasetId).get();

  // To revoke access to a dataset, remove elements from the access list.
  //
  // See the BigQuery client library documentation for more details on access entries:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest

  // Filter access entries to exclude entries matching the specified entity_id
  // and assign a new list back to the access list.
  dataset.metadata.access = dataset.metadata.access.filter(entry => {
    return !(
      entry.entity_id === entityId ||
      entry.userByEmail === entityId ||
      entry.groupByEmail === entityId
    );
  });

  // Update will only succeed if the dataset
  // has not been modified externally since retrieval.
  //
  // See the BigQuery client library documentation for more details on metadata updates:
  // https://cloud.google.com/bigquery/docs/updating-datasets

  // Update just the 'access entries' property of the dataset.
  await dataset.setMetadata(dataset.metadata);

  console.log(`Revoked access to '${entityId}' from '${datasetId}'.`);
}

Python

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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

from google.cloud import bigquery
from google.api_core.exceptions import PreconditionFailed

# TODO(developer): Update and uncomment the lines below.

# ID of the dataset to revoke access to.
# dataset_id = "my-project.my_dataset"

# ID of the user or group from whom you are revoking access.
# Alternatively, the JSON REST API representation of the entity,
# such as a view's table reference.
# entity_id = "[e-mail]"

# Instantiate a client.
client = bigquery.Client()

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# To revoke access to a dataset, remove elements from the AccessEntry list.
#
# See the BigQuery client library documentation for more details on `access_entries`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.Dataset#google_cloud_bigquery_dataset_Dataset_access_entries

# Filter `access_entries` to exclude entries matching the specified entity_id
# and assign a new list back to the AccessEntry list.
dataset.access_entries = [
    entry for entry in dataset.access_entries
    if entry.entity_id != entity_id
]

# Update will only succeed if the dataset
# has not been modified externally since retrieval.
#
# See the BigQuery client library documentation for more details on `update_dataset`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client#google_cloud_bigquery_client_Client_update_dataset
try:
    # Update just the `access_entries` property of the dataset.
    dataset = client.update_dataset(
        dataset,
        ["access_entries"],
    )

    # Notify user that the API call was successful.
    full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
    print(f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'")
except PreconditionFailed:  # A read-modify-write error.
    print(
        f"Dataset '{dataset.dataset_id}' was modified remotely before this update. "
        "Fetch the latest version and retry."
    )

使用資料表和檢視區塊存取權控管

BigQuery 會將檢視表視為資料表資源。您可以授予 IAM 主體預先定義或自訂角色，藉此提供資料表或檢視區塊的存取權，並決定主體可對資料表或檢視區塊執行的操作。這也稱為將「允許政策」附加至資源。授予存取權後，您可以查看資料表或檢視表的存取權控管機制，也可以撤銷資料表或檢視表的存取權。

授予資料表或檢視表的存取權

如要進行精細的存取權控管，您可以授予特定資料表或檢視區預先定義或自訂的 IAM 角色。資料表或檢視區也會沿用在資料集層級和更高層級指定的存取權控管。舉例來說，如果您將資料集的 BigQuery 資料擁有者角色授予主體，該主體也會取得資料集中資料表和檢視區塊的 BigQuery 資料擁有者權限。

如要授予資料表或檢視區塊的存取權，請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中展開專案，然後選取要共用的資料表或檢視區塊。

3. 點選「分享」圖示 。

4. 按一下 「新增主體」。

5. 在「New principals」(新增主體) 欄位中輸入主體。

6. 在「選取角色」清單中，選取預先定義的角色或自訂角色。

7. 按一下 [儲存]。

8. 如要返回表格或查看詳細資料，請按一下「關閉」。

SQL

如要授予主體資料表或檢視區塊的存取權，請使用 GRANT DCL 陳述式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   GRANT `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   TO "USER_LIST"

   取代下列項目：

   • ROLE_LIST：要授予的角色或以半形逗號分隔的角色清單

   • RESOURCE_TYPE：角色套用的資源類型

     支援的值包括 TABLE、VIEW、MATERIALIZED VIEW 和 EXTERNAL TABLE。

   • RESOURCE_NAME：要授予權限的資源名稱

   • USER_LIST：以半形逗號分隔的使用者清單，當中列有獲派角色的使用者

     如需有效格式的清單，請參閱 user_list。

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

以下範例會授予 myTable 的 BigQuery 資料檢視者角色：

GRANT `roles/bigquery.dataViewer`
ON TABLE `myProject`.myDataset.myTable
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要授予資料表或檢視表的存取權，請使用 bq add-iam-policy-binding 指令：

   bq add-iam-policy-binding --member=MEMBER_TYPE:MEMBER --role=ROLE
     --table=true RESOURCE

   更改下列內容：

   • MEMBER_TYPE：成員類型，例如 user、group、serviceAccount 或 domain。
   • MEMBER：成員的電子郵件地址或網域名稱。
   • ROLE：要授予成員的角色。
   • RESOURCE：要更新政策的資料表或檢視區塊名稱。

Terraform

使用 google_bigquery_table_iam 資源更新資料表的存取權。

重要事項： google_bigquery_table_iam 提供的不同資源可能會互相衝突。建議您先詳閱 google_bigquery_table_iam 說明文件，再使用 Terraform 變更存取權控管設定。

設定資料表的存取政策

以下範例說明如何使用 google_bigquery_table_iam_policy 資源，為 mytable 資料表設定 IAM 政策。這會取代已附加至資料表的任何現有政策：

# This file sets the IAM policy for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:[e-mail]",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "table_iam_policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

設定表格的角色成員資格

以下範例說明如何使用 google_bigquery_table_iam_binding 資源，為 mytable 資料表設定特定角色的成員資格。這會取代該角色現有的任何成員資格。 系統會保留資料表 IAM 政策中的其他角色。

# This file sets membership in an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_binding" "table_iam_binding" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataOwner"

  members = [
    "group:[e-mail]",
  ]
}

為單一主體設定角色成員資格

以下範例說明如何使用 google_bigquery_table_iam_member 資源，更新 mytable 資料表的 IAM 政策，將角色授予一個主體。更新這項 IAM 政策不會影響已獲授資料集角色的任何其他主體存取權。

# This file adds a member to an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_member" "table_iam_member" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataEditor"
  member     = "serviceAccount:[e-mail]"
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

API

1. 如要擷取目前的政策，請呼叫 tables.getIamPolicy 方法。

2. 編輯政策，新增成員或存取控管，或兩者皆是。 如要瞭解政策的格式規定，請參閱「政策」參考主題。

   注意： 設定政策前，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免同時更新。
   
   在政策檔案中，version 的值仍為 1。這個版本號碼是指 IAM 政策結構定義版本，而非政策版本。etag 的值是政策版本號碼。

3. 呼叫 tables.setIamPolicy ，寫入更新後的政策。

   注意： 系統不允許沒有任何成員的空繫結，否則會導致錯誤。

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫資源的 IAM().SetPolicy() 函式，儲存資料表或檢視表的存取權政策變更。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"cloud.google.com/go/iam"
)

// grantAccessToResource creates a new ACL conceding the VIEWER role to the group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func grantAccessToResource(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// resourceID := "myresource"

	ctx := context.Background()

	// Create new client
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource policy.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Find more details about IAM Roles here:
	// https://pkg.go.dev/cloud.google.com/go/iam#RoleName
	entityID := "[e-mail]"
	roleType := iam.Viewer

	// Add new policy.
	policy.Add(fmt.Sprintf("group:%s", entityID), roleType)

	// Update resource's policy.
	err = client.Dataset(datasetID).Table(resourceID).IAM().SetPolicy(ctx, policy)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Get resource policy again expecting the update.
	policy, err = client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;

public class GrantAccessToTableOrView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_TABLE_NAME";
    // Role to add to the policy access
    Role role = Role.of("roles/bigquery.dataViewer");
    // Identity to add to the policy access
    Identity identity = Identity.user("[e-mail]");
    grantAccessToTableOrView(projectId, datasetName, resourceName, role, identity);
  }

  public static void grantAccessToTableOrView(
      String projectId, String datasetName, String resourceName, Role role, Identity identity) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Add new user identity to current IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);
      policy = policy.toBuilder().addIdentity(role, identity).build();

      // Update the IAM policy by setting the new one.
      bigquery.setIamPolicy(tableId, policy);

      System.out.println("IAM policy of resource \"" + resourceName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("IAM policy was not updated. \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫 Table#getIamPolicy() 函式，擷取資料表或檢視表的現行 IAM 政策，新增繫結來修改政策，然後使用 Table#setIamPolicy() 函式儲存存取權政策的變更。

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID";
// const datasetId = "YOUR_DATASET_ID";
// const tableId = "YOUR_TABLE_ID";
// const principalId = "YOUR_PRINCIPAL_ID";
// const role = "YOUR_ROLE";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function grantAccessToTableOrView() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(tableId);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings array.
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // To grant access to a table or view
  // add bindings to the Table or View policy.
  //
  // Find more details about Policy and Binding objects here:
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Binding
  const binding = {
    role,
    members: [principalId],
  };
  policy.bindings.push(binding);

  // Set the IAM access policy with updated bindings.
  await table.setIamPolicy(policy);

  // Show a success message.
  console.log(
    `Role '${role}' granted for principal '${principalId}' on resource '${datasetId}.${tableId}'.`
  );
}

await grantAccessToTableOrView();

Python

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫 client.set_iam_policy() 函式，儲存資料表或檢視區塊的存取權政策變更。

from google.cloud import bigquery

# TODO(developer): Update and uncomment the lines below.

# Google Cloud Platform project.
# project_id = "my_project_id"

# Dataset where the table or view is.
# dataset_id = "my_dataset"

# Table or view name to get the access policy.
# resource_name = "my_table"

# Principal to grant access to a table or view.
# For more information about principal identifiers see:
# https://cloud.google.com/iam/docs/principal-identifiers
# principal_id = "user:[e-mail]"

# Role to grant to the principal.
# For more information about BigQuery roles see:
# https://cloud.google.com/bigquery/docs/access-control
# role = "roles/bigquery.dataViewer"

# Instantiate a client.
client = bigquery.Client()

# Get the full table or view name.
full_resource_name = f"{project_id}.{dataset_id}.{resource_name}"

# Get the IAM access policy for the table or view.
policy = client.get_iam_policy(full_resource_name)

# To grant access to a table or view, add bindings to the IAM policy.
#
# Find more details about Policy and Binding objects here:
# https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy
# https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Binding
binding = {
    "role": role,
    "members": [principal_id, ],
}
policy.bindings.append(binding)

# Set the IAM access policy with updated bindings.
updated_policy = client.set_iam_policy(full_resource_name, policy)

# Show a success message.
print(
    f"Role '{role}' granted for principal '{principal_id}'"
    f" on resource '{full_resource_name}'."
)

授予資料表和檢視表存取權的預先定義角色

BigQuery 會將檢視表視為資料表資源。如要進行精細的存取權控管，您可以對特定資料表或檢視表授予預先定義或自訂的 IAM 角色。資料表或檢視區也會沿用在資料集層級和更高層級指定的存取權控管。舉例來說，如果您將資料集上的 BigQuery 資料擁有者角色授予主體，該主體也會擁有資料集內資料表和檢視區塊的資料擁有者權限。

以下預先定義的 IAM 角色具有表格或檢視區塊的權限。

注意： 雖然可以將 BigQuery 管理員或 BigQuery Studio 管理員權限授予資料表或檢視區塊，但您不應在資料表或檢視區塊層級授予這些角色。BigQuery 資料擁有者也會授予資料表和檢視區塊的所有權限，且權限較低。BigQuery 管理員和 BigQuery Studio 管理員通常是在專案層級授予。

角色	說明
BigQuery 資料擁有者 (roles/bigquery.dataOwner)	如果授予資料表或檢視表，這個角色會授予下列權限： 資料表或檢視表的所有權限。 資料列存取政策的所有權限，但不包括覆寫時間回溯限制的權限。 設定類別和資料欄層級的資料政策。 注意：在資料集層級獲派資料擁有者角色的主體，也可以在資料集中建立新資料表及列出資料表。
BigQuery 資料編輯者 (roles/bigquery.dataEditor)	如果授予資料表或檢視表，這個角色會授予下列權限： 取得中繼資料、更新中繼資料、取得存取權控管設定，以及刪除資料表或檢視區塊。 取得 (查詢)、匯出、複製及更新資料表資料。 建立、更新及刪除索引。 建立及還原快照。 注意：在資料集層級獲派資料編輯者角色的主體，也可以建立新資料表，並列出資料集中的資料表。
BigQuery 資料檢視者 (roles/bigquery.dataViewer)	如果授予資料表或檢視表，這個角色會授予下列權限： 取得資料表或檢視表的中繼資料和存取權控管。 取得 (查詢)、匯出及複製資料表資料。 建立快照。 注意：在資料集層級獲派資料檢視者角色的主體，也可以列出資料集中的資料表。
BigQuery 中繼資料檢視器 (roles/bigquery.metadataViewer)	如果授予資料表或檢視表，這個角色會授予下列權限： 取得資料表或檢視表的中繼資料和存取權控管。 注意：在資料集層級獲派中繼資料檢視者角色的主體，也可以列出資料集中的資料表。

資料表和檢視表的權限

BigQuery 會將檢視表視為資料表資源。所有資料表層級的權限都會套用至檢視畫面。

開頭為 bigquery.tables 的權限大多適用於資料表層級。 bigquery.tables.create 和 bigquery.tables.list 則不會。如要建立及列出資料表或檢視區塊，必須在父項容器 (資料集或專案) 上，將 bigquery.tables.create 和 bigquery.tables.list 權限授予角色。

下表列出資料表和檢視區塊的所有權限，以及可授予權限的最低層級資源。

權限	資源	動作
bigquery.tables.create	資料集	在資料集中建立新資料表。
bigquery.tables.createIndex	資料表	在資料表上建立搜尋索引。
bigquery.tables.deleteIndex	資料表	刪除資料表中的搜尋索引。
bigquery.tables.createSnapshot	資料表	建立資料表的快照。建立快照需要資料表和資料集層級的幾項額外權限。詳情請參閱權限與角色一文，瞭解如何建立資料表快照。
bigquery.tables.deleteSnapshot	資料表	刪除資料表快照。
bigquery.tables.delete	資料表	刪除資料表。
bigquery.tables.createTagBinding	資料表	在資料表上建立資源標記繫結。
bigquery.tables.deleteTagBinding	資料表	刪除資料表中的資源標記繫結。
bigquery.tables.listTagBindings	資料表	列出資料表的資源標記繫結。
bigquery.tables.listEffectiveTags	資料表	列出資料表的有效標記 (已套用和已繼承)。
bigquery.tables.export	資料表	匯出資料表資料。執行匯出工作也需要 bigquery.jobs.create 權限。
bigquery.tables.get	資料表	取得資料表中繼資料。
bigquery.tables.getData	資料表	查詢資料表的資料。執行查詢工作也需要 bigquery.jobs.create 權限。
bigquery.tables.getIamPolicy	資料表	取得資料表的存取權控管。
bigquery.tables.list	資料集	列出資料集中的所有資料表和資料表的中繼資料。
bigquery.tables.replicateData	資料表	複製資料表資料。您必須具備這項權限，才能建立 materialized view 副本。
bigquery.tables.restoreSnapshot	資料表	還原資料表快照。
bigquery.tables.setCategory	資料表	在資料表的結構定義中設定政策標記。
bigquery.tables.setColumnDataPolicy	資料表	在資料表上設定資料欄層級存取政策。
bigquery.tables.setIamPolicy	資料表	設定資料表的存取權控管。
bigquery.tables.update	資料表	更新表格。如要在主控台中更新資料表中繼資料，也需要 metadata. bigquery.tables.get 權限。
bigquery.tables.updateData	資料表	更新資料表資料。
bigquery.tables.updateIndex	資料表	更新資料表中的搜尋索引。

查看資料表或檢視表的存取權控管

如要查看資料表或檢視區塊的存取控制項，請選擇下列任一選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中，展開專案和資料集，然後選取資料表或檢視區塊。

3. 點選「分享」圖示 。

   資料表或檢視區塊存取權控制項會顯示在「共用」窗格中。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要取得現有存取權政策，並以 JSON 格式輸出至本機檔案，請在 Cloud Shell 中使用 bq get-iam-policy 指令：

   bq get-iam-policy \
       --table=true \
       PROJECT_ID:DATASET.RESOURCE > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：資料集名稱
   • RESOURCE：要查看政策的資料表或檢視畫面名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑

SQL

預先發布版

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

查詢 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 檢視區塊。 如要查詢資料表或檢視表的存取權控管，查詢必須指定 object_schema 和 object_name。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   SELECT
   COLUMN_LIST
   FROM
     PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
   WHERE
   object_schema = "DATASET" AND object_name = "TABLE";

   取代下列項目：

   • COLUMN_LIST：以逗號分隔的清單，當中列有INFORMATION_SCHEMA.OBJECT_PRIVILEGES 檢視區塊的資料欄
   • PROJECT_ID：您的專案 ID
   • REGION：區域限定符
   • DATASET：包含資料表或檢視表的資料集名稱
   • TABLE：資料表或檢視區塊的名稱

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

範例：

SELECT
object_name, privilege_type, grantee
FROM
my_project.`region-us`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
WHERE
object_schema = "mydataset" AND object_name = "mytable";

+------------------+-----------------------------+--------------------------+
|   object_name    |  privilege_type             | grantee                  |
+------------------+-----------------------------+--------------------------+
| mytable          | roles/bigquery.dataEditor   | group:[e-mail]|
| mytable          | roles/bigquery.dataOwner    | user:[e-mail]|
+------------------+-----------------------------+--------------------------+

API

如要擷取目前的政策，請呼叫 tables.getIamPolicy 方法。

注意： 如果是檢視區塊，請在這個 API 呼叫中，將 tables 設為 resource 的值。

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫資源的 IAM().Policy() 函式。然後呼叫 Roles() 函式，取得資料表或檢視區塊的存取權政策。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// viewTableOrViewAccessPolicies retrieves the ACL for the given resource
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func viewTableOrViewAccessPolicies(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "my-dataset-id"
	// resourceID := "my-resource-id"

	ctx := context.Background()

	// Create new client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource's policy access.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.Policy;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;

public class GetTableOrViewAccessPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_RESOURCE_NAME";
    getTableOrViewAccessPolicy(projectId, datasetName, resourceName);
  }

  public static void getTableOrViewAccessPolicy(
      String projectId, String datasetName, String resourceName) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Get the table IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);

      // Show policy details.
      // Find more information about the Policy Class here:
      // https://cloud.google.com/java/docs/reference/google-cloud-core/latest/com.google.cloud.Policy
      System.out.println(
          "IAM policy info of resource \"" + resourceName + "\" retrieved succesfully");
      System.out.println();
      System.out.println("IAM policy info: " + policy.toString());
    } catch (BigQueryException e) {
      System.out.println("IAM policy info not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Table#getIamPolicy() 函式，擷取資料表或檢視區塊的 IAM 政策。 存取權政策詳細資料會顯示在傳回的政策物件中。

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID"
// const datasetId = "YOUR_DATASET_ID"
// const resourceName = "YOUR_RESOURCE_NAME";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function viewTableOrViewAccessPolicy() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(resourceName);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings if they don't exist
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // Show policy details.
  // Find more details for the Policy object here:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Policy
  console.log(`Access Policy details for table or view '${resourceName}'.`);
  console.log(`Bindings: ${JSON.stringify(policy.bindings, null, 2)}`);
  console.log(`etag: ${policy.etag}`);
  console.log(`Version: ${policy.version}`);
}

撤銷資料表或檢視表的存取權

如要撤銷表格或檢視畫面的存取權，請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」面板中展開專案和資料集，然後選取資料表或檢視表。

3. 在詳細資料面板中，按一下「分享」。

4. 在「共用」對話方塊中，展開要撤銷存取權的主體。

5. 按一下「刪除」圖示 。

6. 在「要移除主體的角色嗎？」對話方塊中，按一下「移除」。

7. 如要返回表格或查看詳細資料，請按一下「關閉」。

注意： 如果無法撤銷存取權，主體可能是從資源階層的較高層級繼承存取權。

SQL

如要移除主體對資料表或檢視區塊的存取權，請使用 REVOKE DCL 陳述式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   REVOKE `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   FROM "USER_LIST"

   取代下列項目：

   • ROLE_LIST：要撤銷的角色或以半形逗號分隔的角色清單

   • RESOURCE_TYPE：要撤銷角色授權的資源類型

     支援的值包括 TABLE、VIEW、MATERIALIZED VIEW 和 EXTERNAL TABLE。

   • RESOURCE_NAME：要撤銷權限的資源名稱

   • USER_LIST：以逗號分隔的使用者清單，這些使用者的角色將遭到撤銷

     如需有效格式的清單，請參閱 user_list。

3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

以下範例會撤銷 myTable 的 BigQuery 資料擁有者角色：

REVOKE `roles/bigquery.dataOwner`
ON TABLE `myProject`.myDataset.myTable
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要撤銷資料表或檢視表的存取權，請使用 bq remove-iam-policy-binding 指令：

   bq remove-iam-policy-binding --member=MEMBER_TYPE:MEMBER --role=ROLE
   --table=true RESOURCE

   更改下列內容：

   • MEMBER_TYPE：成員類型，例如 user、group、serviceAccount 或 domain
   • MEMBER：成員的電子郵件地址或網域名稱
   • ROLE：要從成員撤銷的角色
   • RESOURCE：要更新政策的資料表或檢視區塊名稱

API

1. 如要擷取目前的政策，請呼叫 tables.getIamPolicy 方法。

2. 編輯政策，移除成員或繫結，或兩者皆移除。 如要瞭解政策的格式規定，請參閱「政策」參考主題。

   注意： 設定政策時，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免同時更新。
   
   在政策檔案中，version 的值仍為 1。這個版本號碼是指 IAM 政策結構定義版本，而非政策版本。etag 的值是政策版本號碼。

3. 呼叫 tables.setIamPolicy ，寫入更新後的政策。

注意： 系統不允許沒有任何成員的空繫結，否則會導致錯誤。

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

呼叫 policy.Remove() 函式， 移除存取權。 然後呼叫 IAM().SetPolicy() 函式，儲存資料表或檢視區塊的存取權政策變更。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"cloud.google.com/go/iam"
)

// revokeTableOrViewAccessPolicies creates a new ACL removing the VIEWER role to group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func revokeTableOrViewAccessPolicies(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// resourceID := "myresource"

	ctx := context.Background()

	// Create new client
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource policy.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Find more details about IAM Roles here:
	// https://pkg.go.dev/cloud.google.com/go/iam#RoleName
	entityID := "[e-mail]"
	roleType := iam.Viewer

	// Revoke policy access.
	policy.Remove(fmt.Sprintf("group:%s", entityID), roleType)

	// Update resource's policy.
	err = client.Dataset(datasetID).Table(resourceID).IAM().SetPolicy(ctx, policy)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Get resource policy again expecting the update.
	policy, err = client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

public class RevokeAccessToTableOrView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_RESOURCE_NAME";
    // Role to remove from the access policy
    Role role = Role.of("roles/bigquery.dataViewer");
    // Identity to remove from the access policy
    Identity user = Identity.user("[e-mail]");
    revokeAccessToTableOrView(projectId, datasetName, resourceName, role, user);
  }

  public static void revokeAccessToTableOrView(
      String projectId, String datasetName, String resourceName, Role role, Identity identity) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Remove either identities or roles, or both from bindings and replace it in
      // the current IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);
      // Create a copy of an immutable map.
      Map<Role, Set<Identity>> bindings = new HashMap<>(policy.getBindings());

      // Remove all identities with a specific role.
      bindings.remove(role);
      // Update bindings.
      policy = policy.toBuilder().setBindings(bindings).build();

      // Remove one identity in all the existing roles.
      for (Role roleKey : bindings.keySet()) {
        if (bindings.get(roleKey).contains(identity)) {
          // Create a copy of an immutable set if the identity is present in the role.
          Set<Identity> identities = new HashSet<>(bindings.get(roleKey));
          // Remove identity.
          identities.remove(identity);
          bindings.put(roleKey, identities);
          if (bindings.get(roleKey).isEmpty()) {
            // Remove the role if it has no identities.
            bindings.remove(roleKey);
          }
        }
      }
      // Update bindings.
      policy = policy.toBuilder().setBindings(bindings).build();

      // Update the IAM policy by setting the new one.
      bigquery.setIamPolicy(tableId, policy);

      System.out.println("IAM policy of resource \"" + resourceName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("IAM policy was not updated. \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Table#getIamPolicy() 方法，擷取資料表或檢視區塊的目前 IAM 政策。修改政策，移除所需角色或主體，然後使用 Table#setIamPolicy() 方法套用更新後的政策。

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID"
// const datasetId = "YOUR_DATASET_ID"
// const tableId = "YOUR_TABLE_ID"
// const roleToRemove = "YOUR_ROLE"
// const principalToRemove = "YOUR_PRINCIPAL_ID"

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function revokeAccessToTableOrView() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(tableId);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings array.
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // To revoke access to a table or view,
  // remove bindings from the Table or View policy.
  //
  // Find more details about Policy objects here:
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy

  if (principalToRemove) {
    // Create a copy of bindings for modifications.
    const bindings = [...policy.bindings];

    // Filter out the principal from each binding.
    for (const binding of bindings) {
      if (binding.members) {
        binding.members = binding.members.filter(
          m => m !== principalToRemove
        );
      }
    }

    // Filter out bindings with empty members.
    policy.bindings = bindings.filter(
      binding => binding.members && binding.members.length > 0
    );
  }

  if (roleToRemove) {
    // Filter out all bindings with the roleToRemove
    // and assign a new list back to the policy bindings.
    policy.bindings = policy.bindings.filter(b => b.role !== roleToRemove);
  }

  // Set the IAM access policy with updated bindings.
  await table.setIamPolicy(policy);

  // Both role and principal are removed
  if (roleToRemove !== null && principalToRemove !== null) {
    console.log(
      `Role '${roleToRemove}' revoked for principal '${principalToRemove}' on resource '${datasetId}.${tableId}'.`
    );
  }

  // Only role is removed
  if (roleToRemove !== null && principalToRemove === null) {
    console.log(
      `Role '${roleToRemove}' revoked for all principals on resource '${datasetId}.${tableId}'.`
    );
  }

  // Only principal is removed
  if (roleToRemove === null && principalToRemove !== null) {
    console.log(
      `Access revoked for principal '${principalToRemove}' on resource '${datasetId}.${tableId}'.`
    );
  }

  // No changes were made
  if (roleToRemove === null && principalToRemove === null) {
    console.log(
      `No changes made to access policy for '${datasetId}.${tableId}'.`
    );
  }
}

使用日常作業的存取權控管

預先發布版

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要提供意見回饋或尋求這項功能的支援，請傳送電子郵件至 [e-mail]。

您可以授予 IAM 主體](/iam/docs/principal-identifiers#allow)預先定義或自訂角色，藉此提供日常安排的存取權，並決定主體可對日常安排執行的操作。這也稱為將允許政策附加至資源。授予存取權後，你可以查看日常作業的存取權控管設定，並撤銷日常作業的存取權。

授予處理常式存取權

如要進行精細的存取權控管，您可以針對特定日常安排授予預先定義或自訂的 IAM 角色。這項常式也會沿用在資料集層級和更高層級指定的存取權控管機制。舉例來說，如果您將資料集的 BigQuery 資料擁有者角色授予主體，該主體也會擁有資料集中常式的資料擁有者權限。

選取下列選項之一：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中，依序展開專案、資料集和「Routines」，然後選取所需常式。

3. 點選「分享」圖示 。

4. 按一下 「新增成員」。

5. 在「New members」(新增成員) 欄位中輸入主體。

6. 在「選取角色」清單中，選取預先定義的角色或自訂角色。

7. 按一下 [儲存]。

8. 如要返回日常安排資訊，請按一下「完成」。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要將現有常式資訊 (包括存取權控管設定) 寫入 JSON 檔案，請使用 bq get-iam-policy 指令：

   bq get-iam-policy \
       PROJECT_ID:DATASET.ROUTINE \
       > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：包含要更新常式的資料集名稱
   • ROUTINE：要更新的資源名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑
   注意： 設定政策時，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免同時更新。
   
   在政策檔案中，version 的值仍為 1。這個版本號碼是指 IAM 政策結構定義版本，而非政策版本。etag 的值是政策版本號碼。

3. 變更 JSON 檔案的 bindings 區段。繫結會將一或多個主體繫結至單一 role。主體可以是使用者帳戶、服務帳戶、Google 群組和網域。舉例來說，常式 JSON 檔案中的 bindings 區段應會與以下內容類似：

   {
     "bindings": [
       {
         "role": "roles/bigquery.dataViewer",
         "members": [
           "user:[e-mail]",
           "group:[e-mail]",
           "domain:example.com",
         ]
       },
     ],
     "etag": "BwWWja0YfJA=",
     "version": 1
   }

   注意： 系統不允許沒有任何成員的空繫結，否則會導致錯誤。

4. 如要更新存取權政策，請使用 bq set-iam-policy 指令：

   bq set-iam-policy PROJECT_ID:DATASET.ROUTINE PATH_TO_FILE

5. 如要驗證存取權控管設定變更，請再次使用 bq get-iam-policy 指令，但不要將資訊寫入檔案：

   bq get-iam-policy --format=prettyjson \\
       PROJECT_ID:DATASET.ROUTINE

API

1. 如要擷取目前的政策，請呼叫 routines.getIamPolicy 方法。

2. 編輯政策，新增主體和/或繫結。 如要瞭解政策的格式規定，請參閱「政策」參考主題。

   注意： 設定政策前，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免同時更新。
   
   在政策檔案中，version 的值仍為 1。這個版本號碼是指 IAM 政策結構定義版本，而非政策版本。etag 的值是政策版本號碼。

3. 呼叫 routines.setIamPolicy 寫入更新後的政策。

注意： 系統不允許沒有任何成員的空繫結，否則會導致錯誤。

授予日常作業存取權的預先定義角色

如要進行精細的存取權控管，您可以針對特定日常安排授予預先定義或自訂的 IAM 角色。這項常式也會沿用在資料集層級和更高層級指定的存取權控管機制。舉例來說，如果您將資料集中的資料擁有者角色授予主體，該主體也會透過繼承，取得資料集中常式的資料擁有者權限。

以下預先定義的 IAM 角色具有常式權限。

注意： 雖然可以授予處理常式 BigQuery 管理員或 BigQuery Studio 管理員權限，但請勿在處理常式層級授予這些角色。BigQuery 資料編輯者也會授予常式的所有權限，且是權限較少的角色。BigQuery 管理員和 BigQuery Studio 管理員通常是在專案層級授予。

角色	說明
BigQuery 資料擁有者 (roles/bigquery.dataOwner)	如果授予日常安排，這個角色會授予下列權限： 具備所有日常作業相關權限。 您不應在常式層級授予資料擁有者角色。資料編輯者也擁有所有例行程序的權限，但權限較少。 注意：在資料集層級獲派「資料擁有者」角色的主體，可以建立資料集中的常式，並列出這些常式。
BigQuery 資料編輯者 (roles/bigquery.dataEditor)	如果授予日常安排，這個角色會授予下列權限： 具備所有日常作業相關權限。 注意：在資料集層級獲派資料編輯者角色的主體，可以在資料集中建立和列出常式。
BigQuery 資料檢視者 (roles/bigquery.dataViewer)	如果授予日常安排，這個角色會授予下列權限： 在查詢中參照他人建立的常式。 注意：在資料集層級獲派資料檢視者角色的主體，也可以列出資料集中的常式。
BigQuery 中繼資料檢視器 (roles/bigquery.metadataViewer)	如果授予日常安排，這個角色會授予下列權限： 在查詢中參照他人建立的常式。 注意：在資料集層級獲派中繼資料檢視者角色的主體，也可以列出資料集中的常式。

處理常式權限

以 bigquery.routines 開頭的大部分權限都適用於日常安排層級。 bigquery.routines.create 和 bigquery.routines.list 則不會。如要建立及列出常式，必須在父項容器 (資料集) 中，將 bigquery.routines.create 和 bigquery.routines.list 權限授予角色。

下表列出所有例行程序權限，以及可授予這些權限的最低層級資源。

權限	資源	說明
bigquery.routines.create	資料集	在資料集中建立常式。如要執行含有 CREATE FUNCTION 陳述式的工作，也需要 bigquery.jobs.create 權限。
bigquery.routines.delete	處理常式	刪除日常安排。
bigquery.routines.get	處理常式	參考他人建立的日常安排。此外，如要執行參照常式的查詢工作，您也需要 bigquery.jobs.create 權限，並具備存取常式所參照任何資源 (例如資料表或檢視表) 的權限。
bigquery.routines.list	資料集	列出資料集中的處理常式，並顯示處理常式的中繼資料。
bigquery.routines.update	處理常式	更新處理常式定義和中繼資料。
bigquery.routines.getIamPolicy	處理常式	取得日常作業的存取權控管。
bigquery.routines.setIamPolicy	處理常式	設定日常作業的存取控管機制。

查看日常安排的存取權控管

如要查看日常作業的存取權控管設定，請選擇下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」窗格中，依序展開專案、資料集和「Routines」，然後選取常式。

3. 點選「分享」圖示 。

   「共用」窗格會顯示日常生活的存取權控管機制。

bq

bq get-iam-policy 指令不支援查看日常作業的存取權控管。

SQL

「INFORMATION_SCHEMA.OBJECT_PRIVILEGES」檢視畫面不會顯示日常作業的存取權控管。

API

如要擷取目前的政策，請呼叫 routines.getIamPolicy 方法。

撤銷處理常式的存取權

如要撤銷常式存取權，請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在「Explorer」面板中，依序展開專案、資料集和「Routines」，然後選取常式。

3. 在詳細資料面板中，依序點選「共用」>「權限」。

4. 在「日常安排權限」對話方塊中，展開要撤銷存取權的主體。

5. 按一下 「移除主體」。

6. 在「要移除主體的角色嗎？」對話方塊中，按一下「移除」。

7. 按一下 [關閉]。

注意： 如果無法撤銷存取權，主體可能是從資源階層中較高的層級繼承存取權。 如需編輯主體存取權的操作說明，請參閱「授予或撤銷單一角色」一文。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要將現有常式資訊 (包括存取權控管設定) 寫入 JSON 檔案，請使用 bq get-iam-policy 指令：

   bq get-iam-policy --routine PROJECT_ID:DATASET.ROUTINE > PATH_TO_FILE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • DATASET：包含要更新常式的資料集名稱
   • ROUTINE：要更新的資源名稱
   • PATH_TO_FILE：本機上 JSON 檔案的路徑
   注意： 設定政策時，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免發生並行更新。

   在政策檔案中，version 的值仍為 1。這個數字是指 IAM 政策結構定義版本，而非政策版本。etag 值是政策版本號碼。

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

   舉例來說，常式 JSON 檔案中的 access 區段應會與以下內容類似：

   {
    "bindings": [
      {
        "role": "roles/bigquery.dataViewer",
        "members": [
          "user:[e-mail]",
          "group:[e-mail]",
          "domain:google.com",
        ]
      },
    ],
    "etag": "BwWWja0YfJA=",
    "version": 1
   }

   注意： 系統不允許沒有任何成員的空繫結，否則會導致錯誤。

4. 如要更新存取權政策，請使用 bq set-iam-policy 指令：

   bq set-iam-policy --routine PROJECT_ID:DATASET.ROUTINE PATH_TO_FILE

5. 如要驗證存取權控管設定變更，請再次使用 get-iam-policy 指令，但不要將資訊寫入檔案：

   bq get-iam-policy --routine --format=prettyjson PROJECT_ID:DATASET.ROUTINE

API

1. 如要擷取目前的政策，請呼叫 routines.getIamPolicy 方法。

2. 編輯政策，新增主體或繫結，或兩者皆新增。 如要瞭解政策的格式規定，請參閱「政策」參考主題。

   注意： 設定政策時，請務必先擷取目前的政策，取得 etag 的目前值。更新後的政策檔案必須包含與要取代的現行政策相同的 etag 值，否則更新會失敗。這項功能可避免同時更新。
   
   在政策檔案中，version 的值仍為 1。這個版本號碼是指 IAM 政策結構定義版本，而非政策版本。etag 的值是政策版本號碼。

查看資源的繼承存取權控管

您可以使用 BigQuery 網頁版 UI 檢查資源的已繼承 IAM 角色。您必須具備適當的權限，才能在控制台中查看繼承設定。如要檢查資料集、資料表、檢視區塊或常式的繼承項目，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在「Explorer」窗格中選取資料集，或展開資料集並選取資料表、檢視區塊或常式。

3. 如要分享資料集，請按一下「共用」。如要分享表格、檢視畫面或日常安排，請按一下「分享」。

4. 確認已啟用「在表格顯示繼承的角色」選項。

   

5. 展開表格中的角色。

6. 在「繼承」欄中，六邊形圖示會指出角色是否繼承自父項資源。

   

拒絕存取資源

預先發布版

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

注意： 如要提供意見回饋或詢問與這個搶先版相關的問題，請傳送電子郵件至 [e-mail]。

IAM 拒絕政策可讓您設定 BigQuery 資源的存取權防護措施。您可以定義拒絕規則，防止所選主體使用特定權限，無論主體具備何種角色均適用。

如要瞭解如何建立、更新及刪除拒絕政策，請參閱「拒絕存取資源」一文。

特殊情況

在部分 BigQuery 權限上建立 IAM 拒絕政策時，請考慮下列情境：

• 存取授權資源 (檢視區塊、常式、資料集或預存程序) 可讓您建立、捨棄或操控資料表，以及讀取和修改資料表資料，即使您沒有直接執行這些作業的權限也沒問題。此外，它還能取得模型資料或中繼資料，以及在基礎資料表上叫用其他預存程序。這項功能表示授權資源具有下列權限：

  • bigquery.tables.get
  • bigquery.tables.list
  • bigquery.tables.getData
  • bigquery.tables.updateData
  • bigquery.tables.create
  • bigquery.tables.delete
  • bigquery.routines.get
  • bigquery.routines.list
  • bigquery.datasets.get
  • bigquery.models.getData
  • bigquery.models.getMetadata

  如要拒絕存取這些授權資源，請在建立拒絕政策時，將下列其中一個值新增至 deniedPrincipal 欄位：

  值	用途
  principalSet://goog/public:all	封鎖所有主體，包括授權資源。
  principalSet://bigquery.googleapis.com/projects/PROJECT_NUMBER/*	封鎖指定專案中的所有 BigQuery 授權資源。PROJECT_NUMBER 是系統自動為 INT64 類型的專案產生的專屬 ID。

• 如要免除特定主體的拒絕政策，請在拒絕政策的 exceptionPrincipals 欄位中指定這些主體。例如：exceptionPrincipals: "principalSet://bigquery.googleapis.com/projects/1234/*"。

• BigQuery 會為工作擁有者快取查詢結果 24 小時，工作擁有者可存取這些結果，不必具備含有資料的資料表 bigquery.tables.getData 權限。因此，在 bigquery.tables.getData 權限中新增 IAM 拒絕政策，不會封鎖工作擁有者存取快取結果，直到快取過期為止。如要禁止工作擁有者存取快取結果，請對 bigquery.jobs.create 權限建立個別的拒絕政策。

• 使用拒絕政策封鎖資料讀取作業時，為避免發生非預期的資料存取行為，建議您一併檢查並撤銷資料集上的所有現有訂閱項目。

• 如要建立 IAM 拒絕政策，禁止使用者查看資料集存取權控管，請拒絕下列權限：

  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy

• 如要建立 IAM 拒絕政策，禁止更新資料集存取權控管設定，請拒絕下列權限：

  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy

後續步驟

瞭解如何使用 projects.testIamPermissions 方法測試使用者對資源的存取權。