遮盖列数据

本文档介绍如何实现数据遮盖，以便有选择地遮盖敏感数据。通过实现数据遮盖，您可以为不同的用户组提供不同级别的可见性。如需了解一般信息，请参阅数据遮盖简介。

您可以通过向列添加数据政策来实现数据遮盖。要向列添加数据遮盖政策，您必须完成以下步骤：

  1. 创建至少包含一个政策标记的分类。
  2. 可选：向您创建的一个或多个政策标记上的一个或多个主账号授予 Data Catalog Fine-Grained Reader 角色。
  3. 为政策标记创建最多三个数据政策，以将遮盖规则和（表示用户或组的）主账号映射到该标记。
  4. 为列设置政策标记。这会将与政策标记关联的数据政策映射到选定的列。
  5. 将有权访问遮盖数据的用户分配给 BigQuery Masked Reader 角色。 最佳实践是在数据政策级层分配 BigQuery Masked Reader 角色。如果在项目级层或更高级层分配该角色，则用户将获得项目下所有数据政策的权限，这可能会导致权限多余而造成的问题。

您可以使用 Cloud de Confiance 控制台或 BigQuery Data Policy API 来处理数据政策。

完成这些步骤后，根据列运行查询的用户会收到未遮盖的数据、遮盖的数据或访问遭拒错误，具体取决于他们所属的群组以及授予的角色。如需了解详情，请参阅 Masked Reader 和 Fine-Grained Reader 角色如何交互。

或者，您也可以直接对列应用数据政策（预览版）。如需了解详情，请参阅直接对列使用数据政策遮盖数据。

使用政策标记遮盖数据

使用政策标记有选择性地遮盖敏感数据。

准备工作

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Data Catalog and BigQuery Data Policy APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. 新项目中会自动启用 BigQuery；但对于已存在的项目，您可能需要手动激活 BigQuery。

    Enable the BigQuery API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. 如果您要创建引用自定义遮盖例程的数据政策，请创建关联的遮盖 UDF，以便可在以下步骤中使用。

    6. 创建分类

    您必须为需要创建分类的用户或服务账号授予 Data Catalog Policy Tag Admin 角色。

    控制台

    1. 在Cloud de Confiance 控制台中打开政策标记分类页面。

      打开“政策标记分类”页面

    2. 点击创建分类。

    3. 在新建分类页面上，执行以下操作：

      1. 对于分类名称，输入您要创建的分类的名称。
      2. 对于说明，输入一项说明。
      3. 视需要更改项目下列出的项目。
      4. 视需要更改位置下列出的位置。
      5. 在政策标记下，输入政策标记名称和说明。
      6. 如需为政策标记添加子政策标记，请点击添加子标记。
      7. 如需添加另一个与政策标记级别相同的新政策标记，请点击 + 添加政策标记。
      8. 根据需要继续为您的分类添加政策标记和子政策标记。
      9. 为层次结构创建了政策标记后，点击创建。

    API

    如需使用现有分类，请调用 taxonomies.import，而无需执行以下过程中的前两个步骤。

    1. 调用 taxonomies.create 以创建分类。
    2. 调用 taxonomies.policytag.create 以创建政策标记。

    使用政策标记

    如需详细了解如何使用政策标记（例如如何查看或更新政策标记），请参阅使用政策标记。如需了解最佳实践，请参阅在 BigQuery 中使用政策标记的最佳实践。

    创建数据政策

    创建数据政策的用户或服务账号必须具有 bigquery.dataPolicies.create、bigquery.dataPolicies.setIamPolicy 和 datacatalog.taxonomies.get 权限。

    BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有 bigquery.dataPolicies.create 和 bigquery.dataPolicies.setIamPolicy 权限。Data Catalog Admin 和 Data Catalog Viewer 角色具有 datacatalog.taxonomies.get 权限。

    如果您要创建引用自定义遮盖例程的数据政策，还需要例程权限。

    对于自定义遮盖，请向用户授予 BigQuery Admin 或 BigQuery Data Owner 角色，以确保其具有例程和数据政策所需的权限。

    您最多可以为一个政策标记创建 9 个数据政策。其中一个政策预留用于列级访问权限控制设置。

    控制台

    1. 在Cloud de Confiance 控制台中打开政策标记分类页面。

      打开“政策标记分类”页面

    2. 点击要打开的分类的名称。
    3. 选择一个政策标记。
    4. 点击管理数据政策。
    5. 在数据政策名称部分，输入数据政策的名称。数据政策名称在数据政策所在的项目中必须是唯一的。
    6. 在遮盖规则部分，选择一个预定义的遮盖规则或自定义遮盖例程。如果您要选择自定义屏蔽例程，请确保您在项目级别拥有 bigquery.routines.get 和 bigquery.routines.list 权限。
    7. 在主账号部分，输入要授予其对该列的遮盖访问权限的一个或多个用户或群组的名称。请注意，您在此处输入的所有用户和群组均会被授予 BigQuery Masked Reader 角色。
    8. 点击提交。

    API

    1. 调用 create 方法。传入满足以下要求的 DataPolicy 资源：

      • dataPolicyType 字段设置为 DATA_MASKING_POLICY。
      • dataMaskingPolicy 字段标识要使用的遮盖数据规则或例程。
      • dataPolicyId 字段提供数据政策的名称，该名称在数据政策所在的项目中是唯一的。

    2. 调用 setIamPolicy 方法并传入 Policy。Policy 必须标识被授予遮盖数据访问权限的主账号，并为 role 字段指定 roles/bigquerydatapolicy.maskedReader。

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const datapolicy = require('@google-cloud/bigquery-datapolicies');
const {DataPolicyServiceClient} = datapolicy.v2;
const protos = datapolicy.protos.google.cloud.bigquery.datapolicies.v2;
const {status} = require('@grpc/grpc-js');

const dataPolicyServiceClient = new DataPolicyServiceClient();

/**
 * Creates a data policy to apply a data masking rule to a specific BigQuery table column. 
 * This is a primary mechanism for implementing column-level security in BigQuery.
 *
 * @param {string} projectId The Google Cloud project ID (for example, 'example-project-id')
 * @param {string} location The Google Cloud location. Example: 'us'
 * @param {string} dataPolicyId The user-assigned ID of the data policy. Example: 'example-data-policy-id'
 */
async function createDataPolicy(projectId, location, dataPolicyId) {
  const parent = `projects/${projectId}/locations/${location}`;

  const dataPolicy = {
    dataPolicyType: protos.DataPolicy.DataPolicyType.DATA_MASKING_POLICY,
    dataMaskingPolicy: {
      predefinedExpression:
        protos.DataMaskingPolicy.PredefinedExpression.SHA256,
    },
  };

  const request = {
    parent,
    dataPolicyId,
    dataPolicy,
  };

  try {
    const [response] = await dataPolicyServiceClient.createDataPolicy(request);
    console.log(`Successfully created data policy: ${response.name}`);
    console.log(`Data policy ID: ${response.dataPolicyId}`);
    console.log(`Data policy type: ${response.dataPolicyType}`);
    if (response.dataMaskingPolicy) {
      console.log(
        `Data masking expression: ${response.dataMaskingPolicy.predefinedExpression}`,
      );
    }
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(
        `Data policy '${dataPolicyId}' already exists in location '${location}' of project '${projectId}'.`,
      );
      console.log(
        'Consider updating the existing data policy or using a different dataPolicyId.',
      );
    } else {
      console.error('Error creating data policy:', err.message);
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    from google.api_core import exceptions
from google.cloud import bigquery_datapolicies_v2

client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def create_data_policy(project_id: str, location: str, data_policy_id: str) -> None:
    """Creates a data policy to apply a data masking rule to a specific BigQuery table column. 
    This is a primary mechanism for implementing column-level security in BigQuery.

    Args:
        project_id (str): The Google Cloud project ID.
        location (str): The geographic location of the data policy (for example, "us-central1").
        data_policy_id (str): The ID for the new data policy.
    """

    parent = f"projects/{project_id}/locations/{location}"

    # Define the data masking policy.
    # Here, we specify a SHA-256 predefined expression for data masking.
    data_masking_policy = bigquery_datapolicies_v2.DataMaskingPolicy(
        predefined_expression=bigquery_datapolicies_v2.DataMaskingPolicy.PredefinedExpression.SHA256
    )

    # Create the DataPolicy object.
    # We set the type to DATA_MASKING_POLICY and assign the defined masking policy.
    data_policy = bigquery_datapolicies_v2.DataPolicy(
        data_policy_type=bigquery_datapolicies_v2.DataPolicy.DataPolicyType.DATA_MASKING_POLICY,
        data_masking_policy=data_masking_policy,
    )

    request = bigquery_datapolicies_v2.CreateDataPolicyRequest(
        parent=parent,
        data_policy_id=data_policy_id,
        data_policy=data_policy,
    )

    try:
        response = client.create_data_policy(request=request)
        print(f"Successfully created data policy: {response.name}")
        print(f"Data Policy ID: {response.data_policy_id}")
        print(f"Data Policy Type: {response.data_policy_type.name}")
        print(
            "Data Masking Predefined Expression:"
            f" {response.data_masking_policy.predefined_expression.name}"
        )
    except exceptions.AlreadyExists as e:
        print(
            f"Error: Data policy '{data_policy_id}' already exists in project"
            f" '{project_id}' in location '{location}'. Use a unique ID or"
            " update the existing policy if needed."
        )

    except exceptions.NotFound as e:
        print(
            f"Error: The specified project '{project_id}' or location '{location}'"
            " was not found or is inaccessible. Make sure the project ID and"
            " location are correct and you have the necessary permissions."
        )
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

    为列设置政策标记

    通过将与数据政策关联的政策标记附加到列，对列设置数据政策。

    设置政策标记的用户或服务账号需要具有 datacatalog.taxonomies.get 和 bigquery.tables.setCategory 权限。Data Catalog Policy Tags Admin 和 Project Viewer 角色均包含 datacatalog.taxonomies.get。BigQuery Admin (roles/bigquery.admin) 和 BigQuery Data Owner (roles/bigquery.dataOwner) 角色均包含 bigquery.tables.setCategory。

    如需在Cloud de Confiance 控制台中查看组织中所有项目的分类和政策标记，用户需要 resourcemanager.organizations.get 权限，该权限包含在 Organization Viewer 角色中。

    控制台

    使用Cloud de Confiance 控制台修改架构，以便设置政策标记。

    1. 在 Cloud de Confiance 控制台中打开 BigQuery 页面。

      转到 BigQuery 页面

    2. 在 BigQuery Explorer 中，找到并选择要更新的表。系统会打开该表的表架构。

    3. 点击修改架构。

    4. 在当前架构屏幕中，选择目标列，然后点击添加政策标记。

    5. 在添加政策标记屏幕中，找到并选择要应用于该列的政策标记。

    6. 点击选择。屏幕应类似于如下所示：

      修改架构。

    7. 点击保存。

    bq

    1. 将架构写入本地文件。

      bq show --schema --format=prettyjson \
   project-id:dataset.table > schema.json

      其中：

      • project-id 是您的项目 ID。
      • dataset 是要更新的表所属的数据集的名称。
      • table 是要更新的表的名称。

    2. 修改 schema.json 以便为列设置政策标记。对于 policyTags 的 names 字段的值，请使用政策标记资源名称。

      [
 ...
 {
   "name": "ssn",
   "type": "STRING",
   "mode": "REQUIRED",
   "policyTags": {
     "names": ["projects/project-id/locations/location/taxonomies/taxonomy-id/policyTags/policytag-id"]
   }
 },
 ...
]

    3. 更新架构。

      bq update \
   project-id:dataset.table schema.json

    API

    对于现有表，请调用 tables.patch；对于新表，则调用 tables.insert。使用您传入的 Table 对象的 schema 属性在架构定义中设置政策标记。请参阅命令行示例架构，了解如何设置政策标记。

    使用现有表时，首选 tables.patch 方法，因为 tables.update 方法会替换整个表资源。

    执行访问权限控制

    为政策标记创建数据政策时，系统会自动强制执行访问权限控制。应用了该政策标记的所有列都会返回遮盖数据，以响应具有 Masked Reader 角色的用户的查询。

    如需停止强制执行访问权限控制，您必须先删除与分类中的政策标记关联的所有数据政策。如需了解详情，请参阅强制执行访问权限控制。

    获取数据政策

    如需获取有关数据政策的信息，请按照以下步骤操作：

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const {DataPolicyServiceClient} =
  require('@google-cloud/bigquery-datapolicies').v2;
const {status} = require('@grpc/grpc-js');

const client = new DataPolicyServiceClient();

/**
 * Gets a specific data policy from the BigQuery Data Policy API by its name.
 *
 * This sample demonstrates how to fetch the details of an existing data policy.
 * Data policies are used to define rules for data masking or row-level security
 * on BigQuery tables.
 *
 * @param {string} projectId The Google Cloud project ID (for example, 'example-project-id')
 * @param {string} [location='us'] The Google Cloud location of the data policy (For example, 'us', 'europe-west2').
 * @param {string} [dataPolicyId='example-data-policy'] The ID of the data policy to retrieve.
 */
async function getDataPolicy(
  projectId,
  location = 'us',
  dataPolicyId = 'example-data-policy',
) {
  const name = client.dataPolicyPath(projectId, location, dataPolicyId);

  const request = {
    name,
  };

  try {
    const [dataPolicy] = await client.getDataPolicy(request);
    console.log('Successfully retrieved data policy:');
    console.log(`  Name: ${dataPolicy.name}`);
    console.log(`  Type: ${dataPolicy.dataPolicyType}`);
    if (dataPolicy.dataMaskingPolicy) {
      console.log(
        `  Data Masking Policy: ${dataPolicy.dataMaskingPolicy.predefinedExpression || dataPolicy.dataMaskingPolicy.routine}`,
      );
    }
    if (dataPolicy.grantees && dataPolicy.grantees.length > 0) {
      console.log(`  Grantees: ${dataPolicy.grantees.join(', ')}`);
    }
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.error(
        `Error: Data policy '${dataPolicyId}' not found in location '${location}' for project '${projectId}'.`,
      );
      console.error(
        'Make sure the data policy ID, project ID, and location are correct.',
      );
    } else {
      console.error('Error retrieving data policy:', err.message);
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    from google.api_core import exceptions
from google.cloud import bigquery_datapolicies_v2


client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def get_data_policy(
    project_id: str,
    location: str,
    data_policy_id: str,
) -> None:
    """Gets a specific data policy from the BigQuery Data Policy API by its name.


    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the data policy (for example, "us", "eu").
        data_policy_id: The user-assigned ID of the data policy.
    """
    client = bigquery_datapolicies_v2.DataPolicyServiceClient()

    data_policy_name = client.data_policy_path(
        project=project_id,
        location=location,
        data_policy=data_policy_id,
    )

    try:
        response = client.get_data_policy(name=data_policy_name)

        print(f"Successfully retrieved data policy: {response.name}")
        print(f"  Data Policy ID: {response.data_policy_id}")
        print(f"  Data Policy Type: {response.data_policy_type.name}")
        if response.policy_tag:
            print(f"  Policy Tag: {response.policy_tag}")
        if response.grantees:
            print(f"  Grantees: {', '.join(response.grantees)}")
        if response.data_masking_policy:
            masking_policy = response.data_masking_policy
            if masking_policy.predefined_expression:
                print(
                    f"  Data Masking Predefined Expression: {masking_policy.predefined_expression.name}"
                )
            elif masking_policy.routine:
                print(f"  Data Masking Routine: {masking_policy.routine}")

    except exceptions.NotFound:
        print(f"Error: Data policy '{data_policy_name}' not found.")
        print("Make sure the data policy ID, project ID, and location are correct.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

    检查数据政策的 IAM 权限

    请按照以下步骤获取数据政策的 IAM 政策：

    API

    调用 testIamPermissions 方法。

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const {DataPolicyServiceClient} =
  require('@google-cloud/bigquery-datapolicies').v2;
const {status} = require('@grpc/grpc-js');

const client = new DataPolicyServiceClient();

/**
 * Get the IAM policy for a specified data policy resource from the BigQuery Data Policy API.
 * This is useful for auditing which members have which roles on the policy.
 *
 *
 * @param {string} projectId Google Cloud Project ID (For example, 'example-project-id')
 * @param {string} location Google Cloud Location (For example, 'us-central1')
 * @param {string} dataPolicyId The ID of the data policy (For example, 'example-data-policy-id')
 */
async function getIamPolicy(projectId, location, dataPolicyId) {
  const resourceName = client.dataPolicyPath(projectId, location, dataPolicyId);

  const request = {
    resource: resourceName,
  };

  try {
    const [policy] = await client.getIamPolicy(request);
    console.log(
      'Successfully retrieved IAM policy for data policy %s:',
      resourceName,
    );
    console.log(JSON.stringify(policy, null, 2));
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.error(
        `Error: Data Policy '${dataPolicyId}' not found in location '${location}' of project '${projectId}'. ` +
          'Make sure the data policy exists and the resource name is correct.',
      );
    } else {
      console.error(
        `Error getting IAM policy for data policy '${dataPolicyId}':`,
        err,
      );
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    from google.api_core import exceptions
from google.cloud import bigquery_datapolicies_v2
from google.iam.v1 import iam_policy_pb2

client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def get_data_policy_iam_policy(
    project_id: str,
    location: str,
    data_policy_id: str,
) -> None:
    """Get the IAM policy for a specified data policy resource from the BigQuery Data Policy API. 
    This is useful for auditing which members have which roles on the policy.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the data policy (for example, "us").
        data_policy_id: The ID of the data policy.
    """

    resource_name = client.data_policy_path(
        project=project_id,
        location=location,
        data_policy=data_policy_id,
    )

    request = iam_policy_pb2.GetIamPolicyRequest(resource=resource_name)

    try:
        policy = client.get_iam_policy(request=request)

        print(f"Successfully retrieved IAM policy for data policy: {resource_name}")
        print("Policy Version:", policy.version)
        if policy.bindings:
            print("Policy Bindings:")
            for binding in policy.bindings:
                print(f"  Role: {binding.role}")
                print(f"  Members: {', '.join(binding.members)}")
                if binding.condition.expression:
                    print(f"  Condition: {binding.condition.expression}")
        else:
            print("No bindings found in the policy.")

    except exceptions.NotFound:
        print(f"Error: Data policy '{resource_name}' not found.")
        print("Make sure the project ID, location, and data policy ID are correct.")
    except exceptions.GoogleAPIError as e:
        print(f"An API error occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

    列出数据政策

    请按照以下步骤列出数据政策：

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const {DataPolicyServiceClient} =
  require('@google-cloud/bigquery-datapolicies').v2;
const {status} = require('@grpc/grpc-js');

const client = new DataPolicyServiceClient();

/**
 * Lists all data policies in a given project and location.
 *
 * Data policies define rules for data masking, row-level security, or column-level security.
 *
 * @param {string} projectId The Google Cloud project ID. (for example, 'example-project-id')
 * @param {string} location The Google Cloud location of the data policies. (For example, 'us')
 */
async function listDataPolicies(projectId, location) {
  const parent = `projects/${projectId}/locations/${location}`;

  const request = {
    parent,
  };

  try {
    console.log(
      `Listing data policies for project: ${projectId} in location: ${location}`,
    );
    const [dataPolicies] = await client.listDataPolicies(request);

    if (dataPolicies.length === 0) {
      console.log(
        `No data policies found in location ${location} for project ${projectId}.`,
      );
      return;
    }

    console.log('Data Policies:');
    for (const dataPolicy of dataPolicies) {
      console.log(`  Data Policy Name: ${dataPolicy.name}`);
      console.log(`    ID: ${dataPolicy.dataPolicyId}`);
      console.log(`    Type: ${dataPolicy.dataPolicyType}`);
      if (dataPolicy.policyTag) {
        console.log(`    Policy Tag: ${dataPolicy.policyTag}`);
      }
      if (dataPolicy.grantees && dataPolicy.grantees.length > 0) {
        console.log(`    Grantees: ${dataPolicy.grantees.join(', ')}`);
      }
      if (dataPolicy.dataMaskingPolicy) {
        if (dataPolicy.dataMaskingPolicy.predefinedExpression) {
          console.log(
            `    Data Masking Predefined Expression: ${dataPolicy.dataMaskingPolicy.predefinedExpression}`,
          );
        } else if (dataPolicy.dataMaskingPolicy.routine) {
          console.log(
            `    Data Masking Routine: ${dataPolicy.dataMaskingPolicy.routine}`,
          );
        }
      }
    }

    console.log(`Successfully listed ${dataPolicies.length} data policies.`);
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.error(
        `Error: The project or location '${location}' for project '${projectId}' was not found. ` +
          'Make sure the project ID and location are correct and that the BigQuery Data Policy API is enabled.',
      );
    } else if (err.code === status.PERMISSION_DENIED) {
      console.error(
        `Error: Permission denied when listing data policies for project '${projectId}' in location '${location}'. ` +
          'Make sure the authenticated account has the necessary permissions (For example, bigquery.datapolicies.list).',
      );
    } else {
      console.error(`Error listing data policies: ${err.message}`);
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    import google.api_core.exceptions
from google.cloud import bigquery_datapolicies_v2

client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def list_data_policies(project_id: str, location: str) -> None:
    """Lists all data policies in a specified project.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the data policies (for example, "us", "us-central1").
    """

    parent = f"projects/{project_id}/locations/{location}"

    try:
        request = bigquery_datapolicies_v2.ListDataPoliciesRequest(parent=parent)

        print(
            f"Listing data policies for project '{project_id}' in location '{location}':"
        )
        page_result = client.list_data_policies(request=request)

        found_policies = False
        for data_policy in page_result:
            found_policies = True
            print(f"  Data Policy Name: {data_policy.name}")
            print(f"  Data Policy ID: {data_policy.data_policy_id}")
            print(f"  Data Policy Type: {data_policy.data_policy_type.name}")
            if data_policy.policy_tag:
                print(f"  Policy Tag: {data_policy.policy_tag}")
            if data_policy.grantees:
                print(f"  Grantees: {', '.join(data_policy.grantees)}")
            print("-" * 20)

        if not found_policies:
            print("No data policies found.")

    except google.api_core.exceptions.NotFound as e:
        print(f"Error: The specified project or location was not found or accessible.")
        print(f"Details: {e}")
        print(
            "Make sure the project ID and location are correct and you have the necessary permissions."
        )
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

    更新数据政策

    更新数据政策的用户或服务账号必须具有 bigquery.dataPolicies.update 权限。 如果要更新与数据政策关联的政策标记，则还需要 datacatalog.taxonomies.get 权限。

    如果要更新与数据政策关联的主账号，则需要 bigquery.dataPolicies.setIamPolicy 权限。

    BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有 bigquery.dataPolicies.update 和 bigquery.dataPolicies.setIamPolicy 权限。Data Catalog Admin 和 Data Catalog Viewer 角色具有 datacatalog.taxonomies.get 权限。

    控制台

    1. 在Cloud de Confiance 控制台中打开政策标记分类页面。

      打开“政策标记分类”页面

    2. 点击要打开的分类的名称。
    3. 选择一个政策标记。
    4. 点击管理数据政策。
    5. （可选）更改遮盖规则。
    6. 可选：添加或移除主账号。
    7. 点击提交。

    API

    如需更改数据遮盖规则，请调用 patch 方法并通过更新后的 dataMaskingPolicy 字段传入 DataPolicy 资源。

    要更改与数据政策关联的主账号，请调用 setIamPolicy 方法并传入 Policy 以更新被授予遮盖数据访问权限的主账号。

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const datapolicy = require('@google-cloud/bigquery-datapolicies');
const {DataPolicyServiceClient} = datapolicy.v2;
const protos = datapolicy.protos.google.cloud.bigquery.datapolicies.v2;
const {status} = require('@grpc/grpc-js');

const client = new DataPolicyServiceClient();

/**
 * Updates the data masking configuration of an existing data policy.
 * This example demonstrates how to use a FieldMask to selectively update the
 * `data_masking_policy` (for example, changing the masking expression from
 * ALWAYS_NULL to SHA256) without affecting other fields or recreating the policy.
 *
 * @param {string} projectId The Google Cloud project ID (For example, 'example-project-id').
 * @param {string} location The location of the data policy (For example, 'us').
 * @param {string} dataPolicyId The ID of the data policy to update (For example, 'example-data-policy-id').
 */
async function updateDataPolicy(projectId, location, dataPolicyId) {
  const resourceName = client.dataPolicyPath(projectId, location, dataPolicyId);

  const getRequest = {
    name: resourceName,
  };

  try {
    // To prevent race conditions, use the policy's etag in the update.
    const [currentDataPolicy] = await client.getDataPolicy(getRequest);
    const currentETag = currentDataPolicy.etag;

    // This example transitions a masking rule from ALWAYS_NULL to SHA256.
    const dataPolicy = {
      name: resourceName,
      etag: currentETag,
      dataMaskingPolicy: {
        predefinedExpression:
          protos.DataMaskingPolicy.PredefinedExpression.SHA256,
      },
    };

    // Use a field mask to selectively update only the data masking policy.
    const updateMask = {
      paths: ['data_masking_policy'],
    };

    const request = {
      dataPolicy,
      updateMask,
    };

    const [response] = await client.updateDataPolicy(request);
    console.log(`Successfully updated data policy: ${response.name}`);
    console.log(
      `New masking expression: ${response.dataMaskingPolicy.predefinedExpression}`
    );
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.error(
        `Error: Data policy '${resourceName}' not found. ` +
          'Make sure the data policy exists and the project, location, and data policy ID are correct.'
      );
    } else {
      console.error('Error updating data policy:', err.message, err);
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    from google.api_core import exceptions
from google.cloud import bigquery_datapolicies_v2
from google.protobuf import field_mask_pb2

client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def update_data_policy(
    project_id: str,
    location: str,
    data_policy_id: str
) -> None:
    """Updates the data masking configuration of an existing data policy.

    This example demonstrates how to use a FieldMask to selectively update the
    `data_masking_policy` (for example, changing the masking expression from
    ALWAYS_NULL to SHA256) without affecting other fields or recreating the policy.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location (for example, "us") of the data policy.
        data_policy_id: The ID of the data policy to update.
    """

    data_policy_name = client.data_policy_path(
        project=project_id,
        location=location,
        data_policy=data_policy_id,
    )

    # To prevent race conditions, use the policy's etag in the update.
    existing_policy = client.get_data_policy(name=data_policy_name)

    # This example transitions a masking rule from ALWAYS_NULL to SHA256.
    updated_data_policy = bigquery_datapolicies_v2.DataPolicy(
        name=data_policy_name,
        data_masking_policy=bigquery_datapolicies_v2.DataMaskingPolicy(
            predefined_expression=bigquery_datapolicies_v2.DataMaskingPolicy.PredefinedExpression.SHA256
        ),
        etag=existing_policy.etag,
    )

    # Use a field mask to selectively update only the data masking policy.
    update_mask = field_mask_pb2.FieldMask(
        paths=["data_masking_policy"]
    )
    request = bigquery_datapolicies_v2.UpdateDataPolicyRequest(
        data_policy=updated_data_policy,
        update_mask=update_mask,
    )

    try:
        response = client.update_data_policy(request=request)
        print(f"Successfully updated data policy: {response.name}")
        print(f"New data policy type: {response.data_policy_type.name}")
        if response.data_masking_policy:
            print(
                f"New masking expression: {response.data_masking_policy.predefined_expression.name}"
            )
    except exceptions.NotFound:
        print(f"Error: Data policy '{data_policy_name}' not found.")
        print("Make sure the data policy ID and location are correct.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

    删除数据政策

    创建数据政策的用户或服务账号必须具有 bigquery.dataPolicies.delete 权限。BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有此权限。

    控制台

    1. 在Cloud de Confiance 控制台中打开政策标记分类页面。

      打开“政策标记分类”页面

    2. 点击要打开的分类的名称。
    3. 选择一个政策标记。
    4. 点击管理数据政策。
    5. 点击要删除的数据政策旁边的 。
    6. 点击提交。
    7. 点击确认。

    API

    要删除数据政策，请调用 delete 方法。

    Node.js

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情，请参阅 BigQuery Node.js API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    const {DataPolicyServiceClient} =
  require('@google-cloud/bigquery-datapolicies').v2;
const {status} = require('@grpc/grpc-js');

const client = new DataPolicyServiceClient();

/**
 * Deletes a data policy from the BigQuery Data Policy API, which is identified by its project ID, location, and data policy ID.
 *
 * @param {string} projectId The Google Cloud project ID.
 * @param {string} location The Google Cloud location (For example, 'us').
 * @param {string} dataPolicyId The ID of the data policy to delete (For example, 'example-data-policy').
 */
async function deleteDataPolicy(projectId, location, dataPolicyId) {
  const name = client.dataPolicyPath(projectId, location, dataPolicyId);

  const request = {
    name,
  };

  try {
    await client.deleteDataPolicy(request);
    console.log(`Successfully deleted data policy: ${name}`);
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.error(
        `Data policy ${name} not found. Make sure the data policy ID and location are correct.`,
      );
    } else {
      console.error(`Error deleting data policy ${name}:`, err.message);
    }
  }
}

    Python

    试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

    如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

    在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 

    from google.api_core import exceptions as core_exceptions
from google.cloud import bigquery_datapolicies_v2

client = bigquery_datapolicies_v2.DataPolicyServiceClient()


def delete_data_policy(project_id: str, location: str, data_policy_id: str) -> None:
    """Deletes a data policy from the BigQuery Data Policy APIs.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the data policy (for example, "us").
        data_policy_id: The ID of the data policy to delete.
    """

    name = client.data_policy_path(
        project=project_id, location=location, data_policy=data_policy_id
    )

    try:
        client.delete_data_policy(name=name)
        print(f"Successfully deleted data policy: {name}")
    except core_exceptions.NotFound:
        print(f"Data policy '{name}' not found. It may have already been deleted.")
    except Exception as e:
        print(f"Error deleting data policy '{name}': {e}")

    通过将数据政策应用于列来遮盖数据

    除了创建政策标记，您还可以创建数据政策并将其直接应用于列。

    处理数据政策

    您可以使用 BigQuery Data Policy API 创建、更新和删除数据政策。如需直接对列应用数据政策，您无法使用 Cloud de Confiance 控制台中的政策标记分类页面。

    如需使用数据政策，请使用 v2.projects.locations.datapolicies 资源。

    创建数据政策

    创建数据政策的用户或服务账号必须具有 bigquery.dataPolicies.create 权限。

    BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有 bigquery.dataPolicies.create 权限。Data Catalog Admin 和 Data Catalog Viewer 角色具有 datacatalog.taxonomies.get 权限。

    如果您要创建引用自定义遮盖例程的数据政策，还需要例程权限。

    如果您使用自定义遮盖，请向用户授予 BigQuery Data Owner 角色，以确保其具有例程和数据政策所需的权限。

    API

    如需创建数据政策，请调用 create 方法。传入满足以下要求的 DataPolicy 资源：

    • dataPolicyType 字段设置为 DATA_MASKING_POLICY 或 RAW_DATA_ACCESS_POLICY。
    • dataMaskingPolicy 字段标识要使用的遮盖数据规则或例程。
    • dataPolicyId 字段提供数据政策的名称，该名称在数据政策所在的项目中是唯一的。

    SQL

    如需创建具有遮盖访问权限的数据政策，请使用 CREATE DATA_POLICY 语句并将 data_policy_type 的值设置为 DATA_MASKING_POLICY：

        CREATE[ OR REPLACE] DATA_POLICY [IF NOT EXISTS] `myproject.region-us.data_policy_name`
    OPTIONS (
      data_policy_type="DATA_MASKING_POLICY",
      masking_expression="ALWAYS_NULL"
    );

    如需创建具有原始访问权限的数据政策，请使用 CREATE DATA_POLICY 语句并将 data_policy_type 的值设置为 RAW_DATA_ACCESS_POLICY：

        CREATE[ OR REPLACE] DATA_POLICY [IF NOT EXISTS] `myproject.region-us.data_policy_name`
    OPTIONS (data_policy_type="RAW_DATA_ACCESS_POLICY");

    如果未指定 data_policy_type 的值，则默认值为 RAW_DATA_ACCESS_POLICY。 

        CREATE[ OR REPLACE] DATA_POLICY [IF NOT EXISTS] myproject.region-us.data_policy_name;

    • data_policy_type 字段设置为 DATA_MASKING_POLICY 或 RAW_DATA_ACCESS_POLICY。 创建数据政策后，您便无法更新此字段。
    • masking_expression 字段标识要使用的遮盖数据规则或例程。

    更新数据政策

    更新数据政策的用户或服务账号必须具有 bigquery.dataPolicies.update 权限。

    BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有 bigquery.dataPolicies.update 权限。

    API

    如需更改数据遮盖规则，请调用 patch 方法并通过更新后的 dataMaskingPolicy 字段传入 DataPolicy 资源。

    SQL

    使用 ALTER DATA_POLICY 语句更新数据遮盖规则。例如：

        ALTER DATA_POLICY `myproject.region-us.data_policy_name`
    SET OPTIONS (
      data_policy_type="DATA_MASKING_POLICY",
      masking_expression="SHA256"
    );

    您还可以授予针对数据政策的精细访问权限控制访问权限。

    用于授予针对数据政策的精细访问权限控制访问权限和用于管理数据政策的权限是不同的。如需控制精细访问权限控制权限，您必须更新数据政策的 grantees 字段。如需控制对数据政策的访问权限，请使用 setIamPolicy 方法设置 IAM 角色。

    如需为数据政策设置授权对象，请使用 v2 patch 方法。如需管理数据政策权限，请使用 v1 setIamPolicy 方法。

    API

    如需授予针对数据政策的精细访问权限控制访问权限，请调用 patch 方法，并传入包含更新后的 grantees 字段的 DataPolicy 资源。

    SQL

    如需授予针对数据政策的精细访问权限控制访问权限，请使用 GRANT FINE_GRAINED_READ 语句添加 grantees。 例如：

        GRANT FINE_GRAINED_READ ON DATA_POLICY `myproject.region-us.data_policy_name`
    TO "principal://goog/subject/user1@example.com","principal://goog/subject/user2@example.com"

    如需撤销数据政策的精细访问权限控制访问权限，请使用 REVOKE FINE_GRAINED_READ 语句移除 grantees。 例如：

        REVOKE FINE_GRAINED_READ ON DATA_POLICY `myproject.region-us.data_policy_name`
    FROM "principal://goog/subject/user1@example.com","principal://goog/subject/user2@example.com"

    删除数据政策

    创建数据政策的用户或服务账号必须具有 bigquery.dataPolicies.delete 权限。BigQuery Data Policy Admin、BigQuery Admin 和 BigQuery Data Owner 角色具有此权限。

    API

    要删除数据政策，请调用 delete 方法。

    SQL

    使用 DROP DATA_POLICY 语句删除数据政策：

        DROP DATA_POLICY `myproject.region-us.data_policy_name`;

    直接对列分配数据政策

    您可以直接对列分配数据政策，而无需使用政策标记。

    准备工作

    如需获得直接对列分配数据政策所需的权限，请让您的管理员为您授予表的 BigQuery Data Policy Admin (roles/bigquerydatapolicy.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    此预定义角色包含直接对列分配数据政策所需的权限。如需查看所需的确切权限，请展开所需权限部分：

    所需权限

    您需要具备以下权限才能直接对列分配数据政策：

    • bigquery.tables.update
    • bigquery.tables.setColumnDataPolicy
    • bigquery.dataPolicies.attach

    您也可以使用自定义角色或其他预定义角色来获取这些权限。

    分配数据政策

    如需直接对列分配数据政策，请执行以下操作之一：

    SQL

    如需将数据政策附加到列，请使用 CREATE TABLE、ALTER TABLE ADD COLUMN 或 ALTER COLUMN SET OPTIONS DDL 语句。

    以下示例使用 CREATE TABLE 语句并对列设置数据政策：

        CREATE TABLE myproject.table1 (
    name INT64 OPTIONS (data_policies=["{'name':'myproject.region-us.data_policy_name1'}",
                                      "{'name':'myproject.region-us.data_policy_name2'}"])
    );

    以下示例使用 ALTER COLUMN SET OPTIONS 向表的现有列添加数据政策：

    ALTER TABLE myproject.table1
ALTER COLUMN column_name SET OPTIONS (
  data_policies += ["{'name':'myproject.region-us.data_policy_name1'}",
                    "{'name':'myproject.region-us.data_policy_name2'}"]);

    API

    如需为列分配数据政策，请对表调用 patch 方法，并使用适用的数据政策更新表架构。

    取消分配数据政策

    如需直接对列取消分配数据政策，请执行以下操作之一：

    SQL

    如需将数据政策从列中分离，请使用 ALTER COLUMN SET OPTIONS DDL 语句。

    以下示例使用 ALTER COLUMN SET OPTIONS 从表的现有列中移除所有数据政策：

    ALTER TABLE myproject.table1
ALTER COLUMN column_name SET OPTIONS (
  data_policies = []);

    以下示例使用 ALTER COLUMN SET OPTIONS 替换表的现有列中的数据政策：

    ALTER TABLE myproject.table1
ALTER COLUMN column_name SET OPTIONS (
  data_policies = ["{'name':'myproject.region-us.new_data_policy_name'}"]);

    API

    如需取消为列分配数据政策，请对表调用 patch 方法，并使用空数据政策或更新后的数据政策更新表架构。

    限制

    直接对列分配数据政策会受到以下限制：

    • 您必须使用 v2.projects.locations.datapolicies 资源。
    • 您不能同时将政策标记和数据政策应用于同一列。
    • 您最多可以为一列附加 8 个数据政策。
    • 一个表最多可以通过其列引用 1,000 个唯一的数据政策。
    • 一个查询最多可以引用 2,000 个数据政策。
    • 只有在没有表列引用数据政策时，才能删除相应数据政策。
    • 如果用户仅具有 maskedAccess 角色，则 tabledata.list API 调用会失败。
    • 如果用户没有原始数据访问权限，则对受列数据政策保护的表执行的表复制操作会失败。
    • 跨区域表复制操作不支持受列数据政策保护的表。
    • 列数据政策在 BigQuery Omni 区域中不可用。
    • 如果目标表具有列数据政策，则旧版 SQL 会失败。
    • 加载作业不支持具有列数据政策的用户指定架构。
    • 如果您覆盖目标表，系统会从该表中移除任何现有政策标记，除非您使用 --destination_schema 标志指定具有列数据政策的架构。
    • 默认情况下，数据遮盖不支持分区列或聚簇列。这是数据遮盖的一般限制，并非特定于列数据政策。对分区列或聚簇列进行数据遮盖可能会大幅增加查询成本。
    • 您无法直接在 BigQuery 中适用于 Apache Iceberg 的 BigLake 表、对象表、非 BigLake 外部表、Apache Iceberg 外部表和 Delta Lake 的列中分配数据政策。
    • 只能在数据政策级层授予精细访问权限。如需了解详情，请参阅更新数据政策。