Esta página foi traduzida pela API Cloud Translation.

Ocultar dados da coluna

Neste documento, mostramos como implementar o mascaramento de dados para ocultar dados sensíveis e confidenciais seletivamente. Ao implementar o mascaramento de dados, você pode oferecer diferentes níveis de visibilidade para diferentes grupos de usuários. Para informações gerais, consulte Introdução ao mascaramento de dados.

Para implementar o mascaramento de dados, adicione uma política de dados a uma coluna. Para adicionar uma política de mascaramento de dados a uma coluna, siga estas etapas:

Crie uma taxonomia com pelo menos uma tag de política.
Opcional: conceda o papel Leitor de controle refinado do Data Catalog a um ou mais principais em uma ou mais tags de política criadas.
Crie até três políticas de dados para a tag de política mapear regras de mascaramento e principais (que representam usuários ou grupos) para essa tag.
Defina a tag de política em uma coluna. Isso mapeia as políticas de dados associadas à tag de política para a coluna selecionada.
Atribua usuários que precisam ter acesso a dados mascarados ao papel Leitor mascarado do BigQuery. Como prática recomendada, atribua o papel de leitor mascarado do BigQuery no nível da política de dados. Atribuir o papel no nível do projeto ou em níveis superiores concede aos usuários permissões para todas as políticas de dados no projeto, o que pode levar a problemas causados por permissões em excesso.

É possível usar o console Google Cloud ou a API BigQuery Data Policy para trabalhar com políticas de dados.

Quando você conclui essas etapas, os usuários que executam consultas na coluna recebem dados não mascarados, dados mascarados ou um erro de acesso negado, dependendo dos grupos a que eles pertencem e dos papéis que receberam. Para mais informações, consulte Como os papéis de leitor mascarado e leitor de controle refinado interagem.

Como alternativa, é possível aplicar políticas de dados diretamente em uma coluna (Prévia). Para mais informações, consulte Mascarar dados com políticas de dados diretamente em uma coluna.

Mascarar dados com tags de política

Use tags de política para mascarar seletivamente dados sensíveis.

Antes de começar

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

O BigQuery é ativado de forma automática nos novos projetos, mas talvez seja necessário ativá-lo em um projeto preexistente.
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
Se você estiver criando uma política de dados que se refira a uma rotina de mascaramento personalizada, crie a UDF de mascaramento associada para que ela esteja disponível nas etapas a seguir.

Criar taxonomias

A conta de usuário ou de serviço que cria uma taxonomia precisa receber o papel de administrador de tags de política do Data Catalog.

Console

Abra a página Taxonomia de tag de política no console doGoogle Cloud .
Abrir a página de taxonomias de tags de política
Clique em Criar taxonomia.
Na página Nova taxonomia:
1. Em Nome da taxonomia, insira o nome da taxonomia que você quer criar.
2. Em Descrição, insira uma descrição.
3. Se necessário, altere o projeto listado em Projeto.
4. Se necessário, altere o local listado em Local.
5. Em Tags de política, insira o nome e a descrição da tag de política.
6. Para adicionar uma tag de política filha a uma tag de política, clique em Adicionar subtag.
7. Para adicionar uma nova tag de política no mesmo nível de outra tag de política, clique em + Adicionar tag de política.
8. Continue adicionando tags de política e tags de política filha conforme necessário para sua taxonomia.
9. Quando terminar de criar tags de política para sua hierarquia, clique em Criar.

API

Para usar as taxonomias atuais, chame taxonomies.import no lugar das duas primeiras etapas do procedimento a seguir.

Chame taxonomies.create para criar uma taxonomia.
Chame taxonomies.policytag.create para criar uma tag de política.

Trabalhar com tags de política

Para conferir mais informações sobre como trabalhar com tags de política, como vê-las ou atualizá-las, consulte Trabalhar com tags de política. Para práticas recomendadas, consulte Práticas recomendadas para uso de tags de política no BigQuery.

Criar políticas de dados

A conta de usuário ou de serviço que cria uma política de dados precisa ter as permissões bigquery.dataPolicies.create, bigquery.dataPolicies.setIamPolicy e datacatalog.taxonomies.get.

As permissões bigquery.dataPolicies.create e bigquery.dataPolicies.setIamPolicy estão incluídas nos papéis de administrador de políticas de dados, administrador e proprietário de dados do BigQuery. A permissão datacatalog.taxonomies.get está incluída nos papéis de Administrador do Data Catalog e Leitor do Data Catalog.

Se você estiver criando uma política de dados que se refira a uma rotina de mascaramento personalizada, também será preciso ter permissões de rotina.

No caso de mascaramento personalizado, conceda aos usuários os papéis de administrador do BigQuery ou proprietário de dados do BigQuery para garantir que eles tenham as permissões necessárias para rotinas e políticas de dados.

Você pode criar até nove políticas de dados para uma tag de política. Uma dessas políticas é reservada para configurações de controle de acesso no nível da coluna.

Console

Abra a página Taxonomia de tag de política no console doGoogle Cloud .
Abrir a página de taxonomias de tags de política
Clique no nome da taxonomia para abrir.
Selecione uma tag de política.
Clique em Gerenciar políticas de dados.
Em Nome da política de dados, digite um nome para a política de dados. O nome da política de dados precisa ser exclusivo no projeto em que a política de dados reside.
Em Regra de mascaramento, escolha uma regra de mascaramento predefinida ou uma rotina personalizada. Se você estiver selecionando uma rotina de mascaramento personalizada, verifique se tem as permissões bigquery.routines.get e bigquery.routines.list no nível do projeto.
Em Principal, digite o nome de um ou mais usuários ou grupos a que você quer conceder acesso mascarado à coluna. Todos os usuários e grupos inseridos aqui recebem o papel Leitor mascarado do BigQuery.
Clique em Enviar.

API

Chame o método create. Transmita um recurso DataPolicy que atenda aos seguintes requisitos:
- O campo dataPolicyType está definido como DATA_MASKING_POLICY.
- O campo dataMaskingPolicy identifica a regra ou rotina de mascaramento de dados a ser usada.
- O campo dataPolicyId fornece um nome para a política de dados que é exclusiva no projeto em que a política de dados reside.
Chame o método setIamPolicy e transmita um Policy. Policy precisa identificar os principais que receberam acesso aos dados mascarados e especificar roles/bigquerydatapolicy.maskedReader para o campo role.

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Definir tags de política nas colunas

Defina uma política de dados em uma coluna anexando a tag de política associada à política de dados à coluna.

A conta de usuário ou serviço que define uma tag de política precisa das permissões datacatalog.taxonomies.get e bigquery.tables.setCategory. datacatalog.taxonomies.get está incluído nos papéis de administrador de tags de política do Data Catalog e de visualizador do projeto. bigquery.tables.setCategory está incluído nos papéis Administrador do BigQuery (roles/bigquery.admin) e de Proprietário de dados do BigQuery (roles/bigquery.dataOwner).

Para visualizar taxonomias e tags de política em todos os projetos de uma organização no console doGoogle Cloud , os usuários precisam da permissão resourcemanager.organizations.get, incluída no papel Leitor da organização.

Console

Defina a tag de política modificando um esquema usando o consoleGoogle Cloud .

Abra a página do BigQuery no console do Google Cloud .

Acessar a página do BigQuery
No BigQuery Explorer, localize e selecione a tabela que você quer atualizar. O esquema da tabela será aberto.
Clique em Editar esquema.
Na tela Esquema atual, selecione a coluna de destino e clique em Adicionar tag de política.
Na tela Adicionar tag de política, localize e selecione a tag de política que você quer aplicar à coluna.
Clique em Selecionar. A tela deve ser semelhante a esta:
Clique em Salvar.

bq

Salve o esquema para um arquivo local.
```
bq show --schema --format=prettyjson \
   project-id:dataset.table > schema.json
```
em que:
- project-id é o ID do projeto;
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.

Modifique o schema.json para definir uma tag de política em uma coluna. Para o valor do campo names de policyTags, use o nome do recurso da tag de política.

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

Atualize o esquema.

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

API

Para tabelas existentes, chame tables.patch. Para novas tabelas, chame tables.insert. Use a propriedade schema do objeto Table que você transmite para definir uma tag de política na definição do esquema. Consulte o esquema de exemplo de linha de comando para conferir como definir uma tag de política.

Ao trabalhar com uma tabela atual, o método tables.patch é preferível, porque o método tables.update substitui todo o recurso da tabela.

Aplicar controle de acesso

Ao criar uma política de dados para uma tag de política, o controle de acesso é aplicado automaticamente. Todas as colunas com essa tag de política aplicada retornam dados mascarados em resposta a consultas de usuários que têm o papel Leitor mascarado.

Para interromper a aplicação do controle de acesso, primeiro é necessário excluir todas as políticas de dados associadas às tags de política na taxonomia. Para mais informações, consulte Aplicar controle de acesso.

Receber uma política de dados

Siga estas etapas para acessar informações sobre uma política de dados:

Node.js

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Verificar as permissões do IAM em uma política de dados

Siga estas etapas para acessar a política do IAM de uma política de dados:

API

Chame o método testIamPermissions.

Node.js

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Listar políticas de dados

Siga estas etapas para listar as políticas de dados:

Node.js

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Atualizar políticas de dados

A conta de usuário ou de serviço que atualiza uma política de dados precisa ter a permissão bigquery.dataPolicies.update. Se você estiver atualizando a tag de política a que a política de dados está associada, também precisará da permissão datacatalog.taxonomies.get.

Se você estiver atualizando os principais associados à política de dados, precisará da permissão bigquery.dataPolicies.setIamPolicy.

As permissões bigquery.dataPolicies.update e bigquery.dataPolicies.setIamPolicy estão incluídas nos papéis de administrador de políticas de dados, administrador e proprietário de dados do BigQuery. A permissão datacatalog.taxonomies.get está incluída nos papéis de Administrador do Data Catalog e Leitor do Data Catalog.

Console

Abra a página Taxonomia de tag de política no console doGoogle Cloud .
Abrir a página de taxonomias de tags de política
Clique no nome da taxonomia para abrir.
Selecione uma tag de política.
Clique em Gerenciar políticas de dados.
Também é possível alterar a regra de mascaramento.
Opcional: adicionar ou remover principais.
Clique em Enviar.

API

Para alterar a regra de mascaramento de dados, chame o método patch e transmita um recurso DataPolicy com um campo dataMaskingPolicy atualizado.

Para alterar os principais associados a uma política de dados, chame o método setIamPolicy e transmita um Policy que atualize os principais que recebem acesso aos dados mascarados.

Node.js

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Excluir políticas de dados

A conta de usuário ou de serviço que cria uma política de dados precisa ter a permissão bigquery.dataPolicies.delete. Essa permissão está incluída nos papéis de administrador de políticas de dados do BigQuery, administrador do BigQuery e proprietário de dados do BigQuery.

Console

Abra a página Taxonomia de tag de política no console doGoogle Cloud .
Abrir a página de taxonomias de tags de política
Clique no nome da taxonomia para abrir.
Selecione uma tag de política.
Clique em Gerenciar políticas de dados.
Clique em ao lado da política de dados a ser excluída.
Clique em Enviar.
Clique em Confirmar.

API

Para excluir uma política de dados, chame o método delete.

Node.js

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Mascarar dados aplicando políticas de dados a uma coluna

Como alternativa à criação de tags de política, você pode criar políticas de dados e aplicá-las diretamente em uma coluna.

Trabalhar com políticas de dados

É possível criar, atualizar e excluir políticas de dados usando a API BigQuery Data Policy. Para aplicar uma política de dados diretamente em uma coluna, não é possível usar a página Taxonomias de tag de política no console do Google Cloud .

Para trabalhar com políticas de dados, use o recurso v2.projects.locations.datapolicies.

Criar políticas de dados

A conta de usuário ou de serviço que cria uma política de dados precisa ter a permissão bigquery.dataPolicies.create.

A permissão bigquery.dataPolicies.create está incluída nos papéis de administrador de políticas de dados, administrador e proprietário de dados do BigQuery. A permissão datacatalog.taxonomies.get está incluída nos papéis de Administrador do Data Catalog e Leitor do Data Catalog.

Se você estiver criando uma política de dados que se refira a uma rotina de mascaramento personalizada, também será preciso ter permissões de rotina.

Se você usar mascaramento personalizado, conceda aos usuários a função de proprietário de dados do BigQuery para garantir que eles tenham as permissões necessárias para rotinas e políticas de dados.

API

Para criar uma política de dados, chame o método create. Transmita um recurso DataPolicy que atenda aos seguintes requisitos:

O campo dataPolicyType está definido como DATA_MASKING_POLICY ou RAW_DATA_ACCESS_POLICY.
O campo dataMaskingPolicy identifica a regra ou rotina de mascaramento de dados a ser usada.
O campo dataPolicyId fornece um nome para a política de dados que é exclusiva no projeto em que a política de dados reside.

SQL

Para criar uma política de dados com acesso mascarado, use a instrução CREATE DATA_POLICY e defina o valor de data_policy_type como 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"
    );

Para criar uma política de dados com acesso bruto, use a instrução CREATE DATA_POLICY e defina o valor de data_policy_type como 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");

Se o valor de data_policy_type não for especificado, o valor padrão será RAW_DATA_ACCESS_POLICY.

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

O campo data_policy_type está definido como DATA_MASKING_POLICY ou RAW_DATA_ACCESS_POLICY. Não é possível atualizar esse campo depois que a política de dados é criada.
O campo masking_expression identifica a regra ou rotina de mascaramento de dados a ser usada.

Atualizar políticas de dados

A conta de usuário ou de serviço que atualiza uma política de dados precisa ter a permissão bigquery.dataPolicies.update.

A permissão bigquery.dataPolicies.update está incluída nos papéis de administrador de políticas de dados do BigQuery, administrador do BigQuery e proprietário de dados do BigQuery.

API

Para alterar a regra de mascaramento de dados, chame o método patch e transmita um recurso DataPolicy com um campo dataMaskingPolicy atualizado.

SQL

Use a instrução ALTER DATA_POLICY para atualizar as regras de mascaramento de dados. Exemplo:

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

Também é possível conceder acesso refinado às políticas de dados.

As permissões para conceder controle de acesso detalhado às políticas de dados e gerenciar essas políticas são diferentes. Para controlar as permissões de controle de acesso refinado, atualize o campo grantees da política de dados. Para controlar o acesso às políticas de dados, defina os papéis do IAM usando o método setIamPolicy.

Para definir beneficiários em uma política de dados, use o método v2 patch . Para gerenciar as permissões da política de dados, use o método v1 setIamPolicy.

API

Para conceder acesso granular de controle de acesso às políticas de dados, chame o método patch e transmita um recurso DataPolicy com um campo grantees atualizado.

SQL

Para conceder controle de acesso detalhado às políticas de dados, use a instrução GRANT FINE_GRAINED_READ para adicionar grantees. Exemplo:

    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"

Para revogar o acesso de controle de acesso detalhado das políticas de dados, use a instrução REVOKE FINE_GRAINED_READ para remover grantees. Exemplo:

    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"

Excluir políticas de dados

API

Para excluir uma política de dados, chame o método delete.

SQL

Use a instrução DROP DATA_POLICY para excluir uma política de dados:

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

Atribuir uma política de dados diretamente a uma coluna

É possível atribuir uma política de dados diretamente a uma coluna sem usar tags de política.

Antes de começar

Para receber as permissões necessárias para atribuir uma política de dados diretamente a uma coluna, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de dados do BigQuery (roles/bigquerydatapolicy.admin) na sua tabela. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para atribuir uma política de dados diretamente a uma coluna. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para atribuir uma política de dados diretamente a uma coluna:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Atribuir uma política de dados

Para atribuir uma política de dados diretamente a uma coluna, faça o seguinte:

SQL

Para anexar uma política de dados a uma coluna, use as instruções DDL CREATE TABLE, ALTER TABLE ADD COLUMN ou ALTER COLUMN SET OPTIONS.

O exemplo a seguir usa a instrução CREATE TABLE e define políticas de dados em uma coluna:

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

O exemplo a seguir usa o ALTER COLUMN SET OPTIONS para adicionar uma política de dados a uma coluna existente em uma tabela:

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

Para atribuir uma política de dados a uma coluna, chame o método patch na tabela e atualize o esquema da tabela com as políticas de dados aplicáveis.

Remover a atribuição de uma política de dados

Para remover a atribuição de uma política de dados diretamente em uma coluna, faça o seguinte:

SQL

Para desvincular uma política de dados de uma coluna, use a instrução DDL ALTER COLUMN SET OPTIONS.

O exemplo a seguir usa o ALTER COLUMN SET OPTIONS para remover todas as políticas de dados de uma coluna em uma tabela:

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

O exemplo a seguir usa o ALTER COLUMN SET OPTIONS para substituir políticas de dados de uma coluna existente em uma tabela:

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

API

Para remover a atribuição de uma política de dados a uma coluna, chame o método patch na tabela e atualize o esquema da tabela com políticas de dados vazias ou atualizadas.

Limitações

A atribuição de uma política de dados diretamente a uma coluna está sujeita às seguintes limitações:

Use o recurso v2.projects.locations.datapolicies.
Não é possível aplicar tags de política e políticas de dados à mesma coluna.
É possível anexar no máximo oito políticas de dados a uma coluna.
Uma tabela pode referenciar no máximo 1.000 políticas de dados exclusivas pelas colunas.
Uma consulta pode referenciar no máximo 2.000 políticas de dados.
Só é possível excluir uma política de dados se nenhuma coluna de tabela a referenciar.
Se um usuário tiver apenas a função maskedAccess, a chamada de API tabledata.list vai falhar.
As operações de cópia de tabela falham em tabelas protegidas por políticas de dados de coluna se o usuário não tiver acesso aos dados brutos.
As operações de cópia de tabelas entre regiões não são compatíveis com tabelas protegidas por políticas de dados de coluna.
As políticas de dados de coluna não estão disponíveis nas regiões do BigQuery Omni.
O SQL legado falha se a tabela de destino tiver políticas de dados de coluna.
Os jobs de carregamento não são compatíveis com esquemas especificados pelo usuário com políticas de dados de coluna.
Se você substituir uma tabela de destino, o sistema vai remover todas as tags de política atuais da tabela, a menos que use a flag --destination_schema para especificar um esquema com políticas de dados de coluna.
Por padrão, o mascaramento de dados não é compatível com colunas particionadas ou em cluster. Essa é uma limitação geral do mascaramento de dados, não específica das políticas de dados de coluna. O mascaramento de dados em colunas particionadas ou em cluster pode aumentar significativamente os custos de consulta.
Não é possível atribuir uma política de dados diretamente a uma coluna em tabelas do BigLake para Apache Iceberg no BigQuery, tabelas de objetos, tabelas externas que não são do BigLake, tabelas externas do Apache Iceberg e Delta Lake.
O acesso refinado só pode ser concedido no nível da política de dados. Para mais informações, consulte Atualizar políticas de dados.