列データをマスキングする

このドキュメントでは機密データを選択的に難読化するためにデータマスキングを実装する方法について説明します。データマスキングを実装すると、ユーザーグループごとに異なる可視性を提供できます。一般的な情報については、データマスキングの概要をご覧ください。

データマスキングを実装するには、列にデータポリシーを追加します。データマスキングポリシーを列に追加するには、次の手順を行う必要があります。

1 つ以上のポリシータグを含む分類を作成します。
省略可: 作成した 1 つ以上のポリシータグの 1 つ以上のプリンシパルに「Data Catalog のきめ細かい読み取り」のロールを付与します。
ポリシータグに最大 3 つのデータポリシーを作成し、マスキングルールとプリンシパル（ユーザーまたはグループを表す）をそのタグにマッピングします。
ポリシータグを列に設定します。これにより、ポリシータグに関連付けられているデータポリシーが、選択した列にマッピングされます。
マスクされたデータにアクセスできるユーザーを「BigQuery のマスクされた読み取り」のロールに割り当てます。ベストプラクティスとして、データポリシーレベルで BigQuery のマスクされた読み取りロールを割り当てることをおすすめします。プロジェクトレベル以上でロールを割り当てると、プロジェクト内のすべてのデータポリシーに対する権限がユーザーに付与されます。これにより、過剰な権限が原因で問題が発生する場合があります。

データポリシーを操作するには、 Google Cloud コンソールまたは BigQuery Data Policy API を使用します。

これらの手順を完了すると、所属しているグループと付与されたロールに応じて、その列に対してクエリを実行するユーザーに、マスクされていないデータ、マスクされたデータ、またはアクセス拒否エラーが表示されます。詳細については、マスクされた読み取りロールときめ細かい読み取りロールの仕組みをご覧ください。

また、列にデータポリシーを直接適用することもできます（プレビュー）。詳細については、列でデータポリシーを使用してデータを直接マスクするをご覧ください。

ポリシータグを使用してデータをマスクする

ポリシータグを使用して、センシティブデータを選択的に難読化します。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

Verify that billing is enabled for your Google Cloud project.

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

Verify that billing is enabled for your Google Cloud project.

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

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
カスタムマスキングルーティンを参照するデータポリシーを作成する場合は、関連するマスキング UDF を作成して、以降のステップで使用できるようにします。

分類の作成

分類を作成するユーザーまたはサービスアカウントには、Data Catalog ポリシータグ管理者ロールが必要です。

コンソール

Google Cloud コンソールで [ポリシータグの分類] ページを開きます。
[ポリシータグの分類] ページを開く
[分類の作成] をクリックします。
[新しい分類] ページで次の操作を行います。
1. [分類名] に、作成する分類の名前を入力します。
2. [説明] に、説明を入力します。
3. 必要に応じて、[プロジェクト] に表示されているプロジェクトを変更します。
4. 必要に応じて、[場所] に表示されている場所を変更します。
5. [ポリシータグ] に、ポリシータグの名前と説明を入力します。
6. ポリシータグの子ポリシータグを追加するには、[サブタグを追加] をクリックします。
7. 別のポリシータグと同じレベルに新しいポリシータグを追加するには、[+ ポリシータグを追加] をクリックします。
8. 必要に応じて、分類にポリシータグと子ポリシータグをさらに追加します。
9. ポリシータグの階層の作成が完了したら、[作成] をクリックします。

API

既存の分類を使用するには、次の手順の最初の 2 つのステップの代わりに taxonomies.import を呼び出します。

taxonomies.create を呼び出して分類を作成します。
taxonomies.policytag.create を呼び出してポリシータグを作成します。

ポリシータグを使用する

ポリシータグの操作方法（ポリシータグの表示や更新の方法など）の詳細については、ポリシータグの操作をご覧ください。ベストプラクティスについては、BigQuery でポリシータグを使用するためのベストプラクティスをご覧ください。

データポリシーを作成する

データポリシーを作成するユーザーまたはサービスアカウントには、bigquery.dataPolicies.create、bigquery.dataPolicies.setIamPolicy、datacatalog.taxonomies.get 権限が必要です。

bigquery.dataPolicies.create 権限と bigquery.dataPolicies.setIamPolicy 権限は、BigQuery Data Policy 管理者、BigQuery 管理者、BigQuery データオーナーのロールに含まれています。datacatalog.taxonomies.get 権限は、Data Catalog 管理者と Data Catalog 閲覧者のロールに含まれています。

カスタムマスキングルーチンを参照するデータポリシーを作成する場合は、ルーチン権限も必要です。

カスタムマスキングの場合は、ユーザーがルーチンとデータポリシーの両方に必要な権限を得られるように、BigQuery 管理者ロールまたは BigQuery データオーナーのロールを付与します。

ポリシータグには、最大 9 個のデータポリシーを作成できます。これらのポリシーのうち 1 つは、列レベルのアクセス制御設定用に予約されています。

コンソール

Google Cloud コンソールで [ポリシータグの分類] ページを開きます。
[ポリシータグの分類] ページを開く
分類の名前をクリックして開きます。
ポリシータグを選択します。
[データポリシーを管理] をクリックします。
[データポリシー名] に、データポリシーの名前を入力します。データポリシー名は、データポリシーが存在するプロジェクト内で一意である必要があります。
[マスキングルール] で、事前定義されたマスキングルールまたはカスタムマスキングルーティンを選択します。カスタムマスキングルーチンを選択する場合は、プロジェクトレベルの bigquery.routines.get 権限と bigquery.routines.list 権限の両方があることを確認してください。
[プリンシパル] に、列に対するマスクアクセスを許可する 1 人以上のユーザーまたはグループの名前を入力します。ここに入力するすべてのユーザーとグループには、「BigQuery のマスクされた読み取り」のロールが付与されています。
[送信] をクリックします。

API

create メソッドを呼び出します。次の要件を満たす DataPolicy リソースを渡します。
- dataPolicyType フィールドが DATA_MASKING_POLICY に設定されている。
- dataMaskingPolicy フィールドが、使用するデータマスキングルールまたはルーチンを識別する。
- dataPolicyId フィールドに指定されているデータポリシー名が、そのポリシーが存在するプロジェクト内で一意である。
setIamPolicy メソッドを呼び出し、Policy を渡します。Policy は、マスクされたデータへのアクセス権が付与されているプリンシパルを識別し、role フィールドに roles/bigquerydatapolicy.maskedReader を指定する必要があります。

Node.js

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証情報を設定するをご覧ください。

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 のリファレンスドキュメントをご覧ください。

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 権限が必要です。datacatalog.taxonomies.get は、Data Catalog ポリシータグ管理者とプロジェクト閲覧者のロールに含まれています。bigquery.tables.setCategory は、BigQuery 管理者（roles/bigquery.admin）と BigQuery データオーナー（roles/bigquery.dataOwner）のロールに含まれています。

Google Cloud コンソールで組織内のすべてのプロジェクトの分類とポリシータグを表示するには、resourcemanager.organizations.get 権限が必要です。この権限は、組織閲覧者のロールに含まれています。

コンソール

Google Cloud コンソールを使用してスキーマを変更し、ポリシータグを設定します。

Google Cloud コンソールで [BigQuery] ページを開きます。

[BigQuery] ページに移動
BigQuery Explorer で、更新するテーブルを見つけて選択します。そのテーブルのテーブルスキーマが開きます。
[スキーマを編集] をクリックします。
[現在のスキーマ] 画面でターゲット列を選択し、[ポリシータグを追加] をクリックします。
[ポリシータグを追加] 画面で、列に適用するポリシータグを選択します。
[選択] をクリックします。画面は次のようになります。
[保存] をクリックします。

bq

ローカルファイルにスキーマを書き込みます。
```
bq show --schema --format=prettyjson \
   project-id:dataset.table > schema.json
```
ここで
- project-id は、プロジェクト ID です。
- dataset は、更新しているテーブルを含むデータセットの名前です。
- table は、更新するテーブルの名前です。

schema.json を変更して、列にポリシータグを設定します。policyTags の names フィールドの値には、ポリシータグのリソース名を使用します。

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

スキーマを更新します。

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

API

既存のテーブルの場合は tables.patch を呼び出し、新しいテーブルの場合は tables.insert を呼び出します。渡した Table オブジェクトの schema プロパティを使用して、スキーマ定義でポリシータグを設定します。ポリシータグの設定方法については、コマンドラインのサンプルスキーマを参照してください。

既存のテーブルを操作する場合は、tables.patch メソッドの方が適切です。tables.update メソッドはテーブルリソース全体を置き換えるからです。

アクセス制御の適用

ポリシータグのデータポリシーを作成すると、アクセス制御が自動的に適用されます。このポリシータグが適用されたすべての列は、「マスクされた読み取り」のロールを持つユーザーからのクエリに応じて、マスクされたデータを返します。

アクセス制御の適用を停止するには、ポリシータグに関連付けられているすべてのデータポリシーを分類内で削除する必要があります。詳細については、アクセス制御を適用するをご覧ください。

データポリシーを取得する

データポリシーに関する情報を取得する手順は次のとおりです。

Node.js

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

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

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

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

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

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.dataPolicies.update 権限と bigquery.dataPolicies.setIamPolicy 権限は、BigQuery Data Policy 管理者、BigQuery 管理者、BigQuery データオーナーのロールに含まれています。datacatalog.taxonomies.get 権限は、Data Catalog 管理者と Data Catalog 閲覧者のロールに含まれています。

コンソール

Google Cloud コンソールで [ポリシータグの分類] ページを開きます。
[ポリシータグの分類] ページを開く
分類の名前をクリックして開きます。
ポリシータグを選択します。
[データポリシーを管理] をクリックします。
必要に応じて、マスキングルールを変更します。
省略可: プリンシパルを追加または削除します。
[送信] をクリックします。

API

データマスキングルールを変更するには、patch メソッドを呼び出し、dataMaskingPolicy フィールドが更新された DataPolicy リソースを渡します。

データポリシーに関連付けられたプリンシパルを変更するには、setIamPolicy メソッドを呼び出し、マスクされたデータへのアクセスが許可されているプリンシパルを更新する Policy を渡します。

Node.js

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

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 管理者、BigQuery 管理者、BigQuery データオーナーのロールに含まれています。

コンソール

Google Cloud コンソールで [ポリシータグの分類] ページを開きます。
[ポリシータグの分類] ページを開く
分類の名前をクリックして開きます。
ポリシータグを選択します。
[データポリシーを管理] をクリックします。
削除するデータポリシーの横にあるをクリックします。
[送信] をクリックします。
[確認] をクリックします。

API

データポリシーを削除するには、delete メソッドを呼び出します。

Node.js

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

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 を使用して、データポリシーの作成、更新、削除を行うことができます。列にデータポリシーを直接適用する場合、 Google Cloud コンソールの [ポリシータグの分類] ページは使用できません。

データポリシーを操作するには、v2.projects.locations.datapolicies リソースを使用します。

データポリシーを作成する

データポリシーを作成するユーザーまたはサービスアカウントには、bigquery.dataPolicies.create 権限が必要です。

bigquery.dataPolicies.create 権限は、BigQuery Data Policy 管理者、BigQuery 管理者、BigQuery データオーナーのロールに含まれています。datacatalog.taxonomies.get 権限は、Data Catalog 管理者と Data Catalog 閲覧者のロールに含まれています。

カスタムマスキングルーチンを参照するデータポリシーを作成する場合は、ルーチン権限も必要です。

カスタムマスキングを使用する場合は、ユーザーがルーチンとデータポリシーの両方に必要な権限を得られるように、BigQuery データオーナーのロールを付与します。

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.dataPolicies.update 権限は、BigQuery Data Policy 管理者、BigQuery 管理者、BigQuery データオーナーのロールに含まれています。

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"

データポリシーを削除する

API

データポリシーを削除するには、delete メソッドを呼び出します。

SQL

DROP DATA_POLICY ステートメントを使用してデータポリシーを削除します。

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

列にデータポリシーを直接割り当てる

ポリシータグを使用せずに、列にデータポリシーを直接割り当てることができます。

始める前に

列にデータポリシーを直接割り当てるために必要な権限を取得するには、テーブルに対する BigQuery データポリシー管理者（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 つのテーブルは、列を通じて最大 1,000 個の一意のデータポリシーを参照できます。
1 つのクエリで参照できるデータポリシーは最大 2,000 個です。
データポリシーを削除できるのは、テーブル列が参照していない場合のみです。
ユーザーに maskedAccess ロールのみが付与されている場合、tabledata.list API 呼び出しは失敗します。
ユーザーが元データにアクセスできない場合、列データポリシーで保護されたテーブルに対するテーブルコピーオペレーションは失敗します。
リージョン間のテーブルコピーオペレーションは、列データポリシーで保護されたテーブルをサポートしていません。
BigQuery Omni リージョンでは、列データポリシーは使用できません。
ターゲットテーブルに列データポリシーがある場合、レガシー SQL は失敗します。
読み込みジョブは、列データポリシーを含むユーザー指定のスキーマをサポートしていません。
宛先テーブルを上書きすると、--destination_schema フラグを使用して列データポリシーを含むスキーマを指定しない限り、既存のポリシータグがテーブルから削除されます。
デフォルトでは、データマスキングはパーティション分割列またはクラスタ化列をサポートしていません。これは、列データポリシーに固有の制限ではなく、データマスキングの一般的な制限です。パーティション分割列またはクラスタ列に対するデータマスキングは、クエリ費用を大幅に増加させる可能性があります。
BigQuery 内の Apache Iceberg 用 BigLake テーブル、オブジェクトテーブル、BigLake 以外の外部テーブル、Apache Iceberg 外部テーブル、Delta Lake の列にデータポリシーを直接割り当てることはできません。
詳細なアクセス権は、データポリシーレベルでのみ付与できます。詳細については、データポリシーを更新するをご覧ください。