열 데이터 마스킹

이 문서에서는 민감한 정보를 선택적으로 숨길 수 있도록 데이터 마스킹을 구현하는 방법을 보여줍니다. 데이터 마스킹을 구현하면 여러 사용자 그룹에 서로 다른 수준의 가시성을 제공할 수 있습니다. 일반적인 정보는 데이터 마스킹 소개를 참조하세요.

열에 데이터 정책을 추가하여 데이터 마스킹을 구현합니다. 열에 데이터 마스킹 정책을 추가하려면 다음 단계를 완료해야 합니다.

1. 하나 이상의 정책 태그가 있는 분류를 만드세요.
2. (선택사항) 생성한 정책 태그 중 하나 이상에서 Data Catalog 세분화된 권한의 리더 역할을 하나 이상의 주 구성원에게 부여합니다.
3. 정책 태그에 최대 3개의 데이터 정책을 만들어 마스킹 규칙 및 주 구성원(사용자 또는 그룹을 나타냄)을 해당 태그에 매핑합니다.
4. 열에 정책 태그를 설정합니다. 그러면 정책 태그와 연결된 데이터 정책이 선택한 열에 매핑됩니다.
5. 마스킹된 데이터에 액세스해야 하는 사용자를 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

1. 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

2. 커스텀 마스킹 루틴을 참조하는 데이터 정책을 만드는 경우 다음 단계에서 사용할 수 있도록 연결된 마스킹 UDF를 만듭니다.

분류 만들기

분류를 만드는 사용자나 서비스 계정에 Data Catalog 정책 태그 관리자 역할을 부여해야 합니다.

콘솔

1. Google Cloud 콘솔에서 정책 태그 분류 페이지를 엽니다.

   정책 태그 분류 페이지 열기

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.dataPolicies.create 및 bigquery.dataPolicies.setIamPolicy 권한은 BigQuery 데이터 정책 관리자, BigQuery 관리자, BigQuery 데이터 소유자 역할에 포함되어 있습니다. datacatalog.taxonomies.get 권한은 Data Catalog 관리자 역할과 Data Catalog 뷰어 역할에 포함되어 있습니다.

커스텀 마스킹 루틴을 참조하는 데이터 정책을 만드는 경우 루틴 권한도 필요합니다.

커스텀 마스킹의 경우 사용자에게 BigQuery 관리자 또는 BigQuery 데이터 소유자 역할을 부여하여 루틴과 데이터 정책 모두에 필요한 권한을 부여합니다.

정책 태그에 데이터 정책을 최대 9개까지 만들 수 있습니다. 이러한 정책 중 하나는 열 수준 액세스 제어 설정용으로 예약되어 있습니다.

콘솔

1. Google Cloud 콘솔에서 정책 태그 분류 페이지를 엽니다.

   정책 태그 분류 페이지 열기

2. 열려는 분류 이름을 클릭합니다.
3. 정책 태그를 선택합니다.
4. 데이터 정책 관리를 클릭합니다.
5. 데이터 정책 이름에 데이터 정책 이름을 입력합니다. 데이터 정책 이름은 데이터 정책이 있는 프로젝트 내에서 고유해야 합니다.
6. 마스킹 규칙의 경우 사전 정의된 마스킹 규칙 또는 커스텀 마스킹 루틴을 선택합니다. 커스텀 마스킹 루틴을 선택하는 경우 프로젝트 수준의 bigquery.routines.get 및 bigquery.routines.list 권한이 모두 있는지 확인합니다.
7. 주 구성원에 열에 대한 마스킹된 액세스 권한을 부여하려는 하나 이상의 사용자 또는 그룹 이름을 입력합니다. 여기에 입력하는 모든 사용자 및 그룹에 BigQuery 마스킹된 리더 역할이 부여됩니다.
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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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 권한이 필요합니다.

참고: 열당 정책 태그 1개만 할당할 수 있습니다.

콘솔

Google Cloud 콘솔을 사용하여 스키마를 수정해 정책 태그를 설정합니다.

1. Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.

   BigQuery 페이지로 이동

2. BigQuery 탐색기에서 업데이트할 테이블을 찾아 선택합니다. 테이블의 테이블 스키마가 열립니다.

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.update 메서드가 전체 테이블 리소스를 대체하므로 tables.patch 메서드를 사용하는 것이 좋습니다.

액세스 제어 적용

정책 태그에 데이터 정책을 만들면 액세스 제어가 자동으로 적용됩니다. 해당 정책 태그가 적용된 모든 열은 마스킹된 리더 역할이 있는 사용자의 쿼리에 대한 응답으로 마스킹된 데이터를 반환합니다.

액세스 제어 적용을 중지하려면 먼저 분류에서 정책 태그와 연결된 모든 데이터 정책을 삭제해야 합니다. 자세한 내용은 액세스 제어 적용을 참조하세요.

데이터 정책 가져오기

데이터 정책에 관한 정보를 확인하려면 다음 단계를 따르세요.

Node.js

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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 데이터 정책 관리자, BigQuery 관리자, BigQuery 데이터 소유자 역할에 포함되어 있습니다. datacatalog.taxonomies.get 권한은 Data Catalog 관리자 역할과 Data Catalog 뷰어 역할에 포함되어 있습니다.

콘솔

1. Google Cloud 콘솔에서 정책 태그 분류 페이지를 엽니다.

   정책 태그 분류 페이지 열기

2. 열려는 분류 이름을 클릭합니다.
3. 정책 태그를 선택합니다.
4. 데이터 정책 관리를 클릭합니다.
5. 원하는 경우 마스킹 규칙을 변경합니다.
6. (선택사항) 주 구성원을 추가하거나 삭제합니다.
7. 제출을 클릭합니다.

API

데이터 마스킹 규칙을 변경하려면 patch 메서드를 호출하고 업데이트된 dataMaskingPolicy 필드와 함께 DataPolicy 리소스에 전달합니다.

데이터 정책과 연결된 주 구성원을 변경하려면 setIamPolicy 메서드를 호출하고 마스킹된 데이터에 대한 액세스 권한이 부여된 주 구성원을 업데이트하는 Policy에 전달합니다.

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 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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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 데이터 정책 관리자, BigQuery 관리자, BigQuery 데이터 소유자 역할에 포함되어 있습니다.

콘솔

1. Google Cloud 콘솔에서 정책 태그 분류 페이지를 엽니다.

   정책 태그 분류 페이지 열기

2. 열려는 분류 이름을 클릭합니다.
3. 정책 태그를 선택합니다.
4. 데이터 정책 관리를 클릭합니다.
5. 삭제할 데이터 정책 옆에 있는 를 클릭합니다.
6. 제출을 클릭합니다.
7. 확인을 클릭합니다.

API

데이터 정책을 삭제하려면 delete 메서드를 호출합니다.

Node.js

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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}")

열에 데이터 정책을 적용하여 데이터 마스킹

프리뷰

이 제품이나 기능에는 서비스별 약관이 적용됩니다. 정식 버전(GA) 이전 제품과 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: 이 기능에 대한 의견을 제공하거나 지원을 요청하려면 [e-mail]으로 이메일을 보내세요.

정책 태그를 만드는 대신 데이터 정책을 만들어 열에 직접 적용할 수 있습니다.

데이터 정책 작업

BigQuery Data Policy API를 사용하여 데이터 정책을 만들고, 업데이트하고, 삭제할 수 있습니다. 열에 직접 데이터 정책을 적용하려면 Google Cloud 콘솔의 정책 태그 분류 페이지를 사용할 수 없습니다.

데이터 정책을 사용하려면 v2.projects.locations.datapolicies 리소스를 사용하세요.

데이터 정책 만들기

데이터 정책을 만드는 사용자 또는 서비스 계정에는 bigquery.dataPolicies.create 권한이 있어야 합니다.

bigquery.dataPolicies.create 권한은 BigQuery 데이터 정책 관리자, 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 데이터 정책 관리자, 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/[e-mail]","principal://goog/subject/[e-mail]"

데이터 정책에서 세분화된 액세스 제어 액세스 권한을 취소하려면 REVOKE FINE_GRAINED_READ 문을 사용하여 grantees를 삭제합니다. 예를 들면 다음과 같습니다.

    REVOKE FINE_GRAINED_READ ON DATA_POLICY `myproject.region-us.data_policy_name`
    FROM "principal://goog/subject/[e-mail]","principal://goog/subject/[e-mail]"

데이터 정책 삭제

데이터 정책을 만드는 사용자 또는 서비스 계정에는 bigquery.dataPolicies.delete 권한이 있어야 합니다. 이 권한은 BigQuery 데이터 정책 관리자, BigQuery 관리자, BigQuery 데이터 소유자 역할에 포함되어 있습니다.

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,000개의 고유 데이터 정책을 참조할 수 있습니다.
• 쿼리는 최대 2,000개의 데이터 정책을 참조할 수 있습니다.
• 데이터 정책은 참조하는 테이블 열이 없는 경우에만 삭제할 수 있습니다.
• 사용자에게 maskedAccess 역할만 있는 경우 tabledata.list API 호출이 실패합니다.
• 사용자에게 원시 데이터 액세스 권한이 없는 경우 열 데이터 정책으로 보호되는 테이블에서 테이블 복사 작업이 실패합니다.
• 교차 리전 테이블 복사 작업은 열 데이터 정책으로 보호되는 테이블을 지원하지 않습니다.
• BigQuery Omni 리전에서는 열 데이터 정책을 사용할 수 없습니다.
• 대상 테이블에 열 데이터 정책이 있으면 기존 SQL이 실패합니다.
• 로드 작업은 열 데이터 정책이 있는 사용자 지정 스키마를 지원하지 않습니다.
• 대상 테이블을 덮어쓰면 --destination_schema 플래그를 사용하여 열 데이터 정책이 있는 스키마를 지정하지 않는 한 기존 정책 태그가 테이블에서 삭제됩니다.
• 기본적으로 데이터 마스킹은 파티션을 나눈 열 또는 클러스터링된 열을 지원하지 않습니다. 이는 열 데이터 정책에 국한되지 않는 데이터 마스킹의 일반적인 제한사항입니다. 파티션을 나눈 열 또는 클러스터링된 열에 데이터 마스킹을 적용하면 쿼리 비용이 크게 증가할 수 있습니다.
• BigQuery의 Apache Iceberg용 BigLake 테이블, 객체 테이블, BigLake가 아닌 외부 테이블, Apache Iceberg 외부 테이블, Delta Lake의 열에는 데이터 정책을 직접 할당할 수 없습니다.
• 세부적인 액세스 권한은 데이터 정책 수준에서만 부여할 수 있습니다. 자세한 내용은 데이터 정책 업데이트를 참고하세요.