Maschera i dati delle colonne

Questo documento mostra come implementare il mascheramento dei dati per oscurare in modo selettivo i dati sensibili. Implementando il mascheramento dei dati, puoi fornire diversi livelli di visibilità a diversi gruppi di utenti. Per informazioni generali, consulta Introduzione al mascheramento dei dati.

Puoi implementare il mascheramento dei dati aggiungendo una policy dei dati a una colonna. Per aggiungere una policy di mascheramento dei dati a una colonna, devi completare i seguenti passaggi :

  1. Crea una tassonomia con almeno un tag di criteri.
  2. (Facoltativo) Concedi il ruolo Lettore granulare di Data Catalog a una o più entità su uno o più tag di policy che hai creato.
  3. Crea fino a tre policy dei dati per il tag di criteri, per mappare le regole di mascheramento e le entità (che rappresentano utenti o gruppi) a quel tag.
  4. Imposta il tag di criteri su una colonna. In questo modo, le policy dei dati associate al tag di criteri vengono mappate alla colonna selezionata.
  5. Assegna agli utenti che devono avere accesso ai dati mascherati il ruolo Lettore mascherato BigQuery. Come best practice, assegna il ruolo BigQuery Masked Reader a livello di policy dei dati. L'assegnazione del ruolo a livello di progetto o superiore concede agli utenti le autorizzazioni per tutte le policy relative ai dati del progetto, il che può causare problemi dovuti a un numero eccessivo di autorizzazioni.

Puoi utilizzare la console Google Cloud o l'API BigQuery Data Policy per lavorare con le policy dei dati.

Una volta completati questi passaggi, gli utenti che eseguono query sulla colonna ricevono dati in chiaro, dati mascherati o un errore di accesso negato, a seconda dei gruppi a cui appartengono e dei ruoli che sono stati loro concessi. Per saperne di più, consulta Come interagiscono i ruoli Masked Reader e Fine-Grained Reader.

In alternativa, puoi applicare le policy dei dati direttamente a una colonna. Per saperne di più, consulta Maschera i dati con le policy dei dati direttamente su una colonna.

Maschera i dati con i tag di policy

Utilizza i tag di policy per oscurare in modo selettivo i dati sensibili.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Data Catalog and BigQuery Data Policy APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Data Catalog and BigQuery Data Policy APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.
  8. BigQuery viene abilitato automaticamente nei nuovi progetti, ma potresti doverlo attivare in un progetto preesistente.

    Abilita l'API BigQuery, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  9. Se stai creando una policy dei dati che fa riferimento a una routine di mascheramento personalizzata, crea la funzione definita dall'utente di mascheramento associata in modo che sia disponibile nei passaggi seguenti.

Creazione tassonomie

All'account utente o al service account che crea una tassonomia deve essere concesso il ruolo Amministratore tag di policy di Data Catalog.

Console

  1. Nella console Google Cloud , vai alla pagina Tassonomie dei tag di policy.

    Vai a Tassonomie tag di policy

  2. Fai clic su Crea tassonomia.

  3. Nella pagina Nuova tassonomia:

    1. In Nome tassonomia, inserisci il nome della tassonomia che vuoi creare.
    2. In Descrizione, inserisci una descrizione.
    3. Se necessario, modifica il progetto elencato in Progetto.
    4. Se necessario, modifica la posizione indicata in Posizione.
    5. In Tag di policy, inserisci un nome e una descrizione per tag di criteri.
    6. Per aggiungere un tag di criteri secondario per un tag di criteri, fai clic su Aggiungi sottotag.
    7. Per aggiungere un nuovo tag di criteri allo stesso livello di un altro tag di criteri, fai clic su + Aggiungi tag di policy.
    8. Continua ad aggiungere tag di policy e tag di policy secondari in base alle esigenze della tua tassonomia.
    9. Al termine della creazione dei tag di policy per la gerarchia, fai clic su Crea.

API

Per utilizzare le tassonomie esistenti, chiama taxonomies.import anziché i primi due passaggi della procedura seguente.

  1. Chiama taxonomies.create per creare una tassonomia.
  2. Chiama taxonomies.policyTags.create per creare un tag di criteri.

Utilizza i tag di policy

Per saperne di più su come utilizzare i tag di policy, ad esempio come visualizzarli o aggiornarli, consulta Utilizza i tag di policy. Per le best practice, consulta Best practice per l'utilizzo dei tag di policy in BigQuery.

Crea policy dei dati

L'utente o il account di servizio che crea una policy dati deve disporre delle autorizzazioni bigquery.dataPolicies.create, bigquery.dataPolicies.setIamPolicy e datacatalog.taxonomies.get.

Le autorizzazioni bigquery.dataPolicies.create e bigquery.dataPolicies.setIamPolicy sono incluse nei ruoli Amministratore policy dei dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery. L'autorizzazione datacatalog.taxonomies.get è inclusa nei ruoli Amministratore Data Catalog e Visualizzatore Data Catalog.

Se stai creando una policy dei dati che fa riferimento a una routine di mascheramento personalizzata, devi disporre anche delle autorizzazioni per la routine.

In caso di mascheramento personalizzato, concedi agli utenti i ruoli Amministratore BigQuery o Proprietario dati BigQuery per assicurarti che dispongano delle autorizzazioni necessarie sia per le routine che per le policy dei dati.

Puoi creare fino a nove policy dei dati per un tag di criteri. Una di queste policy è riservata alle impostazioni di controllo dell'accesso a livello di colonna.

Console

  1. Nella console Google Cloud , vai alla pagina Tassonomie dei tag di policy.

    Vai a Tassonomie tag di policy

  2. Fai clic sul nome della tassonomia da aprire.
  3. Seleziona un tag di criteri.
  4. Fai clic su Gestisci i criteri relativi ai dati.
  5. In Nome policy dati, digita un nome per la policy dati. Il nome della policy dei dati deve essere univoco all'interno del progetto in cui si trova la policy dei dati.
  6. In Regola di mascheramento, scegli una regola di mascheramento predefinita o una routine di mascheramento personalizzata. Se selezioni una routine di mascheramento personalizzata, assicurati di disporre delle autorizzazioni bigquery.routines.get e bigquery.routines.list a livello di progetto.
  7. In Entità, digita il nome di uno o più utenti o gruppi a cui vuoi concedere l'accesso mascherato alla colonna. Tieni presente che a tutti gli utenti e i gruppi inseriti qui viene concesso il ruolo BigQuery Masked Reader.
  8. Fai clic su Invia.

API

  1. Chiama il metodo create. Passa una risorsa DataPolicy che soddisfi i seguenti requisiti:

    • Il campo dataPolicyType è impostato su DATA_MASKING_POLICY.
    • Il campo dataMaskingPolicy identifica la regola o la routine di mascheramento dei dati da utilizzare.
    • Il campo dataPolicyId fornisce un nome per la policy dei dati che è univoco all'interno del progetto in cui si trova la policy dei dati.

  2. Chiama il metodo setIamPolicy e trasmetti un Policy. La Policy deve identificare le entità a cui è concesso l'accesso ai dati mascherati e specificare roles/bigquerydatapolicy.maskedReader per il campo role.

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.CreateDataPolicyRequest;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy.PredefinedExpression;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicy.DataPolicyType;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import com.google.cloud.bigquery.datapolicies.v2.LocationName;
import java.io.IOException;

public class CreateDataPolicy {

  /**
   * Creates a data policy to apply a data masking rule to a specific BigQuery table column.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policy (for example, "us-central1").
   * @param dataPolicyId The user-assigned ID for the new data policy (for example,
   *     "example_data_policy").
   */
  public static void createDataPolicy(String projectId, String location, String dataPolicyId) {
    LocationName parent = LocationName.of(projectId, location);

    DataMaskingPolicy dataMaskingPolicy =
        DataMaskingPolicy.newBuilder()
            .setPredefinedExpression(PredefinedExpression.SHA256)
            .build();

    DataPolicy dataPolicy =
        DataPolicy.newBuilder()
            .setDataPolicyType(DataPolicyType.DATA_MASKING_POLICY)
            .setDataMaskingPolicy(dataMaskingPolicy)
            .build();

    CreateDataPolicyRequest request =
        CreateDataPolicyRequest.newBuilder()
            .setParent(parent.toString())
            .setDataPolicyId(dataPolicyId)
            .setDataPolicy(dataPolicy)
            .build();

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      DataPolicy response = client.createDataPolicy(request);

      System.out.printf("Successfully created data policy: %s%n", response.getName());
      System.out.printf("Data Policy ID: %s%n", response.getDataPolicyId());
      System.out.printf("Data Policy Type: %s%n", response.getDataPolicyType());
      if (response.hasDataMaskingPolicy()) {
        System.out.printf(
            "Data Masking Predefined Expression: %s%n",
            response.getDataMaskingPolicy().getPredefinedExpression());
      }
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: data policy '%s' already exists in location '%s' for project '%s': %s%n",
          dataPolicyId, location, projectId, err.getMessage());
    } catch (NotFoundException err) {
      System.err.printf(
          "error: project '%s' or location '%s' was not found: %s%n",
          projectId, location, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create data policy '%s' in location '%s' for project '%s': %s%n",
          dataPolicyId, location, projectId, err.getMessage());
    }
  }

Imposta i tag di policy sulle colonne

Imposta una policy dei dati su una colonna collegando alla colonna il tag di criteri associato alla policy dei dati.

L'utente o il account di servizio che imposta un tag di criteri deve disporre delle autorizzazioni datacatalog.taxonomies.get e bigquery.tables.setCategory. datacatalog.taxonomies.get è incluso nei ruoli Amministratore tag di policy di Data Catalog e Visualizzatore progetto. bigquery.tables.setCategory è incluso nei ruoli Amministratore BigQuery (roles/bigquery.admin) e Proprietario dati BigQuery (roles/bigquery.dataOwner).

Per visualizzare le tassonomie e i tag di policy in tutti i progetti di un'organizzazione nella consoleGoogle Cloud , gli utenti devono disporre dell'autorizzazione resourcemanager.organizations.get, inclusa nel ruolo Visualizzatore organizzazione. Questa autorizzazione non è richiesta quando utilizzi l'API o lo strumento a riga di comando bq.

Console

Imposta il tag di criteri modificando uno schema utilizzando la consoleGoogle Cloud .

  1. Apri la pagina BigQuery nella console Google Cloud .

    Vai alla pagina BigQuery

  2. In Explorer di BigQuery, individua e seleziona la tabella che vuoi aggiornare. Viene visualizzato lo schema della tabella.

  3. Fai clic su Modifica schema.

  4. Nella schermata Schema attuale, seleziona la colonna di destinazione e fai clic su Aggiungi tag di policy.

  5. Nella schermata Aggiungi un tag di policy, individua e seleziona il tag di criteri che vuoi applicare alla colonna.

  6. Fai clic su Seleziona. La schermata dovrebbe essere simile alla seguente:

    Modifica schema.

  7. Fai clic su Salva.

bq

  1. Scrivi lo schema in un file locale.

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

    dove:

    • project-id è l'ID progetto.
    • dataset è il nome del set di dati che contiene la tabella che stai aggiornando.
    • table è il nome della tabella che stai aggiornando.

  2. Modifica schema.json per impostare un tag di criteri su una colonna. Per il valore del campo names di policyTags, utilizza il nome della risorsa del tag di policy.

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

  3. Aggiorna lo schema.

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

API

Per le tabelle esistenti, chiama tables.patch, mentre per le nuove tabelle chiama tables.insert. Utilizza la proprietà schema dell'oggetto Table che passi per impostare un tag di criteri nella definizione dello schema. Consulta lo schema di esempio della riga di comando per scoprire come impostare un tag di criteri.

Quando si lavora con una tabella esistente, è preferibile il metodo tables.patch, perché il metodo tables.update sostituisce l'intera risorsa della tabella.

Applica controllo di accesso

Quando crei una policy dei dati per un tag di criteri, controllo dell'accesso viene applicato automaticamente. Tutte le colonne a cui è applicato il tag di criteri restituiscono dati mascherati in risposta alle query degli utenti con il ruolo Lettore mascherato.

Per interrompere l'applicazione del controllo degli accessi, devi prima eliminare tutte le policy relative ai dati associate ai tag di policy nella tassonomia. Per saperne di più, consulta Applica il controllo degli accessi.

Recupera una policy dei dati

Per ottenere informazioni su una policy dei dati, segui questi passaggi:

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy.PredefinedExpression;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyName;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import java.io.IOException;

public class GetDataPolicy {

  /**
   * Gets a specific data policy from the BigQuery Data Policy API by its name.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policy (for example, "us-central1").
   * @param dataPolicyId The user-assigned ID of the data policy (for example,
   *     "example_data_policy").
   */
  public static void getDataPolicy(String projectId, String location, String dataPolicyId) {
    DataPolicyName dataPolicyName = DataPolicyName.of(projectId, location, dataPolicyId);

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      DataPolicy response = client.getDataPolicy(dataPolicyName);

      System.out.printf("Successfully retrieved data policy: %s%n", response.getName());
      System.out.printf("  Data Policy ID: %s%n", response.getDataPolicyId());
      System.out.printf("  Data Policy Type: %s%n", response.getDataPolicyType());
      if (!response.getPolicyTag().isEmpty()) {
        System.out.printf("  Policy Tag: %s%n", response.getPolicyTag());
      }
      if (!response.getGranteesList().isEmpty()) {
        System.out.printf("  Grantees: %s%n", String.join(", ", response.getGranteesList()));
      }
      if (response.hasDataMaskingPolicy()) {
        DataMaskingPolicy maskingPolicy = response.getDataMaskingPolicy();
        if (maskingPolicy.getPredefinedExpression()
            != PredefinedExpression.PREDEFINED_EXPRESSION_UNSPECIFIED) {
          System.out.printf(
              "  Data Masking Predefined Expression: %s%n",
              maskingPolicy.getPredefinedExpression());
        } else if (!maskingPolicy.getRoutine().isEmpty()) {
          System.out.printf("  Data Masking Routine: %s%n", maskingPolicy.getRoutine());
        }
      }
    } catch (NotFoundException err) {
      System.err.printf(
          "error: data policy '%s' not found: %s%n", dataPolicyName, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to get data policy '%s': %s%n", dataPolicyName, err.getMessage());
    }
  }

Controlla le autorizzazioni IAM su una policy dei dati

Per ottenere la policy IAM per una policy dei dati, segui questi passaggi:

API

Chiama il metodo testIamPermissions.

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyName;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class GetIamPolicy {

  /**
   * Gets the IAM policy for a specified data policy resource from the BigQuery Data Policy API.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policy (for example, "us-central1").
   * @param dataPolicyId The ID of the data policy (for example, "example_data_policy").
   */
  public static void getIamPolicy(String projectId, String location, String dataPolicyId) {
    DataPolicyName resourceName = DataPolicyName.of(projectId, location, dataPolicyId);

    GetIamPolicyRequest request =
        GetIamPolicyRequest.newBuilder().setResource(resourceName.toString()).build();

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      Policy policy = client.getIamPolicy(request);

      System.out.printf("Successfully retrieved IAM policy for data policy: %s%n", resourceName);
      System.out.printf("Policy Version: %d%n", policy.getVersion());
      if (policy.getBindingsCount() > 0) {
        System.out.println("Policy Bindings:");
        for (Binding binding : policy.getBindingsList()) {
          System.out.printf("  Role: %s%n", binding.getRole());
          System.out.printf("  Members: %s%n", String.join(", ", binding.getMembersList()));
          if (binding.hasCondition() && !binding.getCondition().getExpression().isEmpty()) {
            System.out.printf("  Condition: %s%n", binding.getCondition().getExpression());
          }
        }
      } else {
        System.out.println("No bindings found in the policy.");
      }
    } catch (NotFoundException err) {
      System.err.printf("error: data policy '%s' not found: %s%n", resourceName, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to get IAM policy for data policy '%s': %s%n",
          resourceName, err.getMessage());
    }
  }

Elenca le policy sui dati

Per elencare le policy di dati, segui questi passaggi:

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient.ListDataPoliciesPagedResponse;
import com.google.cloud.bigquery.datapolicies.v2.ListDataPoliciesRequest;
import com.google.cloud.bigquery.datapolicies.v2.LocationName;
import java.io.IOException;

public class ListDataPolicies {

  /**
   * Lists all data policies in a specified project and location.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policies (for example, "us-central1").
   */
  public static void listDataPolicies(String projectId, String location) {
    LocationName parent = LocationName.of(projectId, location);

    ListDataPoliciesRequest request =
        ListDataPoliciesRequest.newBuilder().setParent(parent.toString()).build();

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      System.out.printf(
          "Listing data policies for project '%s' in location '%s':%n", projectId, location);
      ListDataPoliciesPagedResponse pageResult = client.listDataPolicies(request);

      boolean foundPolicies = false;
      for (DataPolicy dataPolicy : pageResult.iterateAll()) {
        foundPolicies = true;
        System.out.printf("  Data Policy Name: %s%n", dataPolicy.getName());
        System.out.printf("  Data Policy ID: %s%n", dataPolicy.getDataPolicyId());
        System.out.printf("  Data Policy Type: %s%n", dataPolicy.getDataPolicyType());
        if (!dataPolicy.getPolicyTag().isEmpty()) {
          System.out.printf("  Policy Tag: %s%n", dataPolicy.getPolicyTag());
        }
        if (!dataPolicy.getGranteesList().isEmpty()) {
          System.out.printf("  Grantees: %s%n", String.join(", ", dataPolicy.getGranteesList()));
        }
        System.out.println("--------------------");
      }

      if (!foundPolicies) {
        System.out.println("No data policies found.");
      }
    } catch (NotFoundException err) {
      System.err.printf(
          "error: project '%s' or location '%s' was not found: %s%n",
          projectId, location, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to list data policies in location '%s' for project '%s': %s%n",
          location, projectId, err.getMessage());
    }
  }

Aggiorna le policy sui dati

L'utente o il account di servizio che aggiorna una policy dati deve disporre dell'autorizzazione bigquery.dataPolicies.update. Se stai aggiornando il tag di criteri a cui è associata la policy di dati, devi disporre anche dell'autorizzazione datacatalog.taxonomies.get.

Se stai aggiornando le entità associate alla policy dei dati, devi disporre dell'autorizzazione bigquery.dataPolicies.setIamPolicy.

Le autorizzazioni bigquery.dataPolicies.update e bigquery.dataPolicies.setIamPolicy sono incluse nei ruoli Amministratore policy dei dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery. L'autorizzazione datacatalog.taxonomies.get è inclusa nei ruoli Amministratore Data Catalog e Visualizzatore Data Catalog.

Console

  1. Nella console Google Cloud , vai alla pagina Tassonomie dei tag di policy.

    Vai a Tassonomie tag di policy

  2. Fai clic sul nome della tassonomia per aprirla.
  3. Seleziona un tag di criteri.
  4. Fai clic su Gestisci i criteri relativi ai dati.
  5. Facoltativamente, modifica la regola di mascheramento.
  6. (Facoltativo) Aggiungi o rimuovi entità.
  7. Fai clic su Invia.

API

Per modificare la regola di mascheramento dei dati, chiama il metodo patch e passa una risorsa DataPolicy con un campo dataMaskingPolicy aggiornato.

Per modificare le entità associate a una policy dei dati, chiama il metodo setIamPolicy e trasmetti un Policy che aggiorna le entità a cui è concesso l'accesso ai dati mascherati.

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataMaskingPolicy.PredefinedExpression;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicy;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyName;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import com.google.cloud.bigquery.datapolicies.v2.UpdateDataPolicyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class UpdateDataPolicy {

  /**
   * Updates the data masking configuration of an existing data policy.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policy (for example, "us-central1").
   * @param dataPolicyId The ID of the data policy to update (for example, "example_data_policy").
   */
  public static void updateDataPolicy(String projectId, String location, String dataPolicyId) {
    DataPolicyName dataPolicyName = DataPolicyName.of(projectId, location, dataPolicyId);

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      // Retrieve the existing policy so its etag can be used to prevent race conditions.
      DataPolicy existingPolicy = client.getDataPolicy(dataPolicyName);

      DataPolicy updatedDataPolicy =
          DataPolicy.newBuilder()
              .setName(dataPolicyName.toString())
              .setDataMaskingPolicy(
                  DataMaskingPolicy.newBuilder()
                      .setPredefinedExpression(PredefinedExpression.SHA256)
                      .build())
              .setEtag(existingPolicy.getEtag())
              .build();

      FieldMask updateMask = FieldMask.newBuilder().addPaths("data_masking_policy").build();

      UpdateDataPolicyRequest request =
          UpdateDataPolicyRequest.newBuilder()
              .setDataPolicy(updatedDataPolicy)
              .setUpdateMask(updateMask)
              .build();

      DataPolicy response = client.updateDataPolicy(request);

      System.out.printf("Successfully updated data policy: %s%n", response.getName());
      System.out.printf("New data policy type: %s%n", response.getDataPolicyType());
      if (response.hasDataMaskingPolicy()) {
        System.out.printf(
            "New masking expression: %s%n",
            response.getDataMaskingPolicy().getPredefinedExpression());
      }
    } catch (NotFoundException err) {
      System.err.printf(
          "error: data policy '%s' not found: %s%n", dataPolicyName, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to update data policy '%s': %s%n", dataPolicyName, err.getMessage());
    }
  }

Elimina le policy dei dati

L'utente o il account di servizio che crea una policy dati deve disporre dell'autorizzazione bigquery.dataPolicies.delete. Questa autorizzazione è inclusa nei ruoli Amministratore policy dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery.

Console

  1. Nella console Google Cloud , vai alla pagina Tassonomie dei tag di policy.

    Vai a Tassonomie tag di policy

  2. Fai clic sul nome della tassonomia da aprire.
  3. Seleziona un tag di criteri.
  4. Fai clic su Gestisci i criteri relativi ai dati.
  5. Fai clic su accanto al criterio relativo ai dati da eliminare.
  6. Fai clic su Invia.
  7. Fai clic su Conferma.

API

Per eliminare una policy dei dati, chiama il metodo delete.

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyName;
import com.google.cloud.bigquery.datapolicies.v2.DataPolicyServiceClient;
import java.io.IOException;

public class DeleteDataPolicy {

  /**
   * Deletes a data policy from the BigQuery Data Policy API.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the data policy (for example, "us-central1").
   * @param dataPolicyId The ID of the data policy to delete (for example, "example_data_policy").
   */
  public static void deleteDataPolicy(String projectId, String location, String dataPolicyId) {
    DataPolicyName name = DataPolicyName.of(projectId, location, dataPolicyId);

    try (DataPolicyServiceClient client = DataPolicyServiceClient.create()) {
      client.deleteDataPolicy(name);
      System.out.printf("Successfully deleted data policy: %s%n", name);
    } catch (NotFoundException err) {
      System.err.printf(
          "error: data policy '%s' not found: %s%n", name, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to delete data policy '%s': %s%n", name, err.getMessage());
    }
  }

Maschera i dati applicando policy dei dati a una colonna

In alternativa alla creazione di tag di policy, puoi creare policy dei dati e applicarle direttamente a una colonna.

Puoi anche implementare il mascheramento dei dati tramite i tag di governance dei dati. Per saperne di più, consulta Controlla l'accesso con i tag di governance dei dati.

Utilizza le policy dei dati

Puoi creare, aggiornare ed eliminare le policy dei dati utilizzando l'API BigQuery Data Policy. Per applicare una policy dei dati direttamente a una colonna, non puoi utilizzare la pagina Tassonomie dei tag di policy nella console Google Cloud .

Per utilizzare le policy dei dati, utilizza la risorsa v2.projects.locations.datapolicies.

Crea policy dei dati

L'utente o il account di servizio che crea una policy dati deve disporre dell'autorizzazione bigquery.dataPolicies.create.

L'autorizzazione bigquery.dataPolicies.create è inclusa nei ruoli Amministratore policy dei dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery. L'autorizzazione datacatalog.taxonomies.get è inclusa nei ruoli Amministratore Data Catalog e Visualizzatore Data Catalog.

Se stai creando una policy dei dati che fa riferimento a una routine di mascheramento personalizzata, devi disporre anche delle autorizzazioni per la routine.

Se utilizzi il mascheramento personalizzato, concedi agli utenti il ruolo BigQuery Data Owner per assicurarti che dispongano delle autorizzazioni necessarie sia per le routine sia per le policy dei dati.

API

Per creare una policy dei dati, chiama il metodo create. Passa una risorsa DataPolicy che soddisfi i seguenti requisiti:

  • Il campo dataPolicyType è impostato su DATA_MASKING_POLICY o RAW_DATA_ACCESS_POLICY.
  • Il campo dataMaskingPolicy identifica la regola o la routine di mascheramento dei dati da utilizzare.
  • Il campo dataPolicyId fornisce un nome per la policy dei dati che è univoco all'interno del progetto in cui si trova la policy dei dati.

SQL

Per creare una policy dei dati con accesso mascherato, utilizza l'istruzione CREATE DATA_POLICY e imposta il valore di data_policy_type su 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"
    );

Per creare una policy dei dati con accesso non elaborato, utilizza l'istruzione CREATE DATA_POLICY e imposta il valore di data_policy_type su 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 il valore di data_policy_type non è specificato, il valore predefinito è RAW_DATA_ACCESS_POLICY. 

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

  • Il campo data_policy_type è impostato su DATA_MASKING_POLICY o RAW_DATA_ACCESS_POLICY. Non puoi aggiornare questo campo dopo aver creato la policy dei dati.
  • Il campo masking_expression identifica la regola o la routine di mascheramento dei dati da utilizzare.

Aggiorna le policy sui dati

L'utente o il account di servizio che aggiorna una policy dati deve disporre dell'autorizzazione bigquery.dataPolicies.update.

L'autorizzazione bigquery.dataPolicies.update è inclusa nei ruoli Amministratore policy dei dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery.

API

Per modificare la regola di mascheramento dei dati, chiama il metodo patch e passa una risorsa DataPolicy con un campo dataMaskingPolicy aggiornato.

SQL

Utilizza l'istruzione ALTER DATA_POLICY per aggiornare le regole di mascheramento dei dati. Ad esempio:

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

Puoi anche concedere l'controllo dell'accesso granulare dell'accesso alle policy dei dati.

Le autorizzazioni per concedere l'controllo dell'accesso granulare dell'accesso alle policy relative ai dati e per gestire le policy relative ai dati sono diverse. Per controllare le autorizzazioni di controllo dell'accesso granulare dell'accesso, devi aggiornare il campo grantees della policy dei dati. Per controllare l'accesso alle policy dei dati, imposta i ruoli IAM utilizzando il metodo setIamPolicy.

Per impostare i beneficiari su una policy dei dati, utilizza il metodo v2 patch . Per gestire le autorizzazioni delle policy dei dati, utilizza il metodo v1 setIamPolicy.

API

Per concedere l'controllo dell'accesso granulare dell'accesso alle policy dei dati, chiama il metodo patch e passa una risorsa DataPolicy con un campo grantees aggiornato.

SQL

Per concedere controllo dell'accesso granulare dell'accesso alle policy dei dati, utilizza l'istruzione GRANT FINE_GRAINED_READ per aggiungere grantees. Ad esempio:

    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"

Per revocare l'accesso controllo dell'accesso granulare dell'accesso dalle policy dei dati, utilizza l'istruzione REVOKE FINE_GRAINED_READ per rimuovere grantees. Ad esempio:

    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"

Elimina le policy dei dati

L'utente o il account di servizio che crea una policy dati deve disporre dell'autorizzazione bigquery.dataPolicies.delete. Questa autorizzazione è inclusa nei ruoli Amministratore policy dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery.

API

Per eliminare una policy dei dati, chiama il metodo delete.

SQL

Utilizza l'istruzione DROP DATA_POLICY per eliminare una policy dei dati:

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

Assegna una policy dei dati direttamente a una colonna

Puoi assegnare una policy dei dati direttamente a una colonna senza utilizzare i tag di policy.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per assegnare una policy dei dati direttamente a una colonna, chiedi all'amministratore di concederti il ruolo IAM BigQuery Data Policy Admin (roles/bigquerydatapolicy.admin) sulla tabella. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per assegnare una policy dei dati direttamente a una colonna. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per assegnare una policy dati direttamente a una colonna sono necessarie le seguenti autorizzazioni:

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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Assegna una policy dei dati

Per assegnare una policy dei dati direttamente a una colonna, esegui una delle seguenti operazioni:

SQL

Per collegare una policy dei dati a una colonna, utilizza le istruzioni DDL CREATE TABLE, ALTER TABLE ADD COLUMN o ALTER COLUMN SET OPTIONS.

L'esempio seguente utilizza l'istruzione CREATE TABLE e imposta le policy dei dati su una colonna:

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

L'esempio seguente utilizza ALTER COLUMN SET OPTIONS per aggiungere una policy dei dati a una colonna esistente di una tabella:

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

Per assegnare una policy dati a una colonna, chiama il metodo patch sulla tabella e aggiorna lo schema della tabella con le policy dati applicabili.

Annulla l'assegnazione di una policy dei dati

Per annullare l'assegnazione di una policy dati direttamente su una colonna, esegui una delle seguenti operazioni:

SQL

Per scollegare una policy dati da una colonna, utilizza l'istruzione DDL ALTER COLUMN SET OPTIONS.

L'esempio seguente utilizza ALTER COLUMN SET OPTIONS per rimuovere tutte le policy di dati da una colonna esistente di una tabella:

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

L'esempio seguente utilizza ALTER COLUMN SET OPTIONS per sostituire le policy dei dati di una colonna esistente in una tabella:

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

API

Per annullare l'assegnazione di una policy dei dati a una colonna, chiama il metodo patch sulla tabella e aggiorna lo schema della tabella con policy dei dati vuote o aggiornate.

Limitazioni

L'assegnazione di una policy dei dati direttamente a una colonna è soggetta alle seguenti limitazioni:

  • Devi utilizzare la risorsa v2.projects.locations.datapolicies.
  • Non puoi applicare sia i tag di policy sia le policy dei dati alla stessa colonna.
  • Puoi collegare un massimo di otto policy dati a una colonna.
  • Una tabella può fare riferimento a un massimo di 1000 policy dei dati univoche tramite le sue colonne.
  • Una query può fare riferimento a un massimo di 2000 policy dei dati.
  • Puoi eliminare una policy dei dati solo se non è presente alcun riferimento a questa policy in una colonna della tabella.
  • Se un utente ha solo il ruolo maskedAccess, la chiamata API tabledata.list non va a buon fine.
  • Le operazioni di copia delle tabelle non riescono sulle tabelle protette da policy dei dati delle colonne se l'utente non dispone dell'accesso ai dati non elaborati.
  • Le operazioni di copia delle tabelle tra regioni non supportano le tabelle protette da policy dei dati delle colonne.
  • Le policy dei dati delle colonne non sono disponibili nelle regioni BigQuery Omni.
  • L'esecuzione di SQL precedente non va a buon fine se la tabella di destinazione ha policy dei dati delle colonne.
  • I job di caricamento non supportano gli schemi specificati dall'utente con policy dei dati delle colonne.
  • Se sovrascrivi una tabella di destinazione, il sistema rimuove tutti i tag di policy esistenti dalla tabella, a meno che non utilizzi il flag --destination_schema per specificare uno schema con policy dei dati delle colonne.
  • Per impostazione predefinita, l'oscuramento dei dati non supporta le colonne partizionate o raggruppate. Si tratta di una limitazione generale del mascheramento dei dati, non specifica delle policy dei dati delle colonne. Il mascheramento dei dati su colonne partizionate o raggruppate in cluster può aumentare notevolmente i costi delle query.
  • Non puoi assegnare una policy dei dati direttamente a una colonna nelle tabelle degli oggetti, nelle tabelle esterne non BigLake, nelle tabelle esterne Apache Iceberg e in Delta Lake.
  • L'accesso granulare può essere concesso solo a livello di policy dei dati. Per saperne di più, consulta Aggiorna le policy relative ai dati.
  • Non puoi annullare l'assegnazione dell'ultima policy dei dati rimanente su una colonna utilizzando l'API BigQuery Data Policy. Puoi annullare l'assegnazione dell'ultima policy dei dati rimanente su una colonna utilizzando l'istruzione DDL ALTER COLUMN SET OPTIONS.