Limitare l'accesso con controllo dell'accesso a livello di colonna

Questa pagina spiega come utilizzare controllo dell'accesso a livello di colonna BigQuery per limitare l'accesso ai dati BigQuery a livello di colonna. Per informazioni generali sulcontrollo dell'accessoo a livello di colonna, consulta Introduzione al controllo dell'accesso a livello di colonna di BigQuery.

Le istruzioni in questa pagina utilizzano sia BigQuery sia Data Catalog.

Devi aggiornare lo schema della tabella per impostare un tag di criteri su una colonna. Puoi utilizzare la console Google Cloud , lo strumento a riga di comando bq e l'API BigQuery per impostare untag di criteriy su una colonna. Inoltre, puoi creare una tabella, specificare lo schema e specificare i tag di policy in un'unica operazione utilizzando le seguenti tecniche:

• I comandi bq mk e bq load dello strumento a riga di comando bq.
• Il metodo API tables.insert.
• La pagina Crea tabella nella console Google Cloud . Se utilizzi la console Google Cloud , devi selezionare Modifica come testo quando aggiungi o modifichi lo schema.

Nota: non puoi utilizzare l'istruzione DDL CREATE TABLE per specificare i tag di policy.

Per migliorare controllo dell'accesso a livello di colonna, puoi utilizzare facoltativamente il mascheramento dinamico dei dati. Il mascheramento dei dati consente di mascherare i dati sensibili sostituendo i contenuti nulli, predefiniti o con hash al posto del valore effettivo della colonna.

Prima di iniziare

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

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

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Data Catalog and BigQuery Data Policy APIs.

Roles required to enable APIs

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

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

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Data Catalog and BigQuery Data Policy APIs.

Roles required to enable APIs

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

Enable the APIs

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

   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

Ruoli e autorizzazioni

Esistono diversi ruoli correlati ai tag dei criteri per utenti e service account.

• Gli utenti o i service account che amministrano i tag dei criteri devono disporre del ruolo Amministratore tag dei criteri Data Catalog. Il ruolo Amministratore tag di policy può gestire le tassonomie e i tag di policy e può concedere o rimuovere i ruoli IAM associati ai tag di policy.
• Gli utenti o i service account che applicano il controllo dell'accesso per il controllo dell'accesso a livello di colonna devono disporre del ruolo BigQuery Admin o BigQuery Data Owner. I ruoli BigQuery possono gestire i criteri per i dati, che vengono utilizzati per applicare controllo dell'accesso a una tassonomia.
• Per visualizzare le taxonomies e i tag di policy per tutti i progetti di un'organizzazione nella consoleGoogle Cloud , gli utenti devono disporre del ruolo Visualizzatore organizzazione. In caso contrario, la console mostra solo le classificazioni e i tag di policy associati al progetto selezionato.
• Gli utenti o gli account di servizio che eseguono query sui dati protetti dal controllo dell'accesso a livello di colonna devono disporre del ruolo Lettore granulare di Data Catalog per accedere a questi dati.

Per saperne di più su tutti i ruoli correlati ai tag di criteri, consulta Ruoli utilizzati con il controllo dell'accesso a livello di colonna.

Ruolo Amministratore tag di policy Data Catalog

Il ruolo Amministratore tag di criteri di Data Catalog può creare e gestire i tag di criteri per i dati.

Per concedere il ruolo Amministratore tag policy, devi disporre dell'autorizzazione resourcemanager.projects.setIamPolicy nel progetto per il quale vuoi concedere il ruolo. Se non disponi dell'autorizzazione resourcemanager.projects.setIamPolicy, chiedi a un Proprietario progetto di concederti l'autorizzazione o di eseguire i seguenti passaggi per tuo conto.

1. Nella console Google Cloud , vai alla pagina IAM.

   Apri la pagina IAM

2. Se l'indirizzo email dell'utente a cui concedere il ruolo è presente nell'elenco, selezionalo e fai clic su Modifica. Viene visualizzato il riquadro Modifica accesso. Fai clic su Aggiungi un altro ruolo.

   Se l'indirizzo email dell'utente non è presente nell'elenco, fai clic su Aggiungi, quindi inserisci l'indirizzo email nella casella Nuovi principali.

3. Fai clic sull'elenco a discesa Seleziona un ruolo.

4. In Per prodotto o servizio, fai clic su Data Catalog. In Ruoli, fai clic su Amministratore tag di norme.

5. Fai clic su Salva.

Ruoli Amministratore policy dei dati BigQuery, Amministratore BigQuery e Proprietario dati BigQuery

I ruoli BigQuery Data Policy Admin, BigQuery Admin e BigQuery Data Owner possono gestire le policy dei dati.

Per concedere uno di questi ruoli, devi disporre dell'autorizzazione resourcemanager.projects.setIamPolicy sul progetto per cui vuoi concedere il ruolo. Se non disponi dell'autorizzazione resourcemanager.projects.setIamPolicy, chiedi a un Proprietario progetto di concederti l'autorizzazione o di eseguire i seguenti passaggi per tuo conto.

1. Nella console Google Cloud , vai alla pagina IAM.

   Apri la pagina IAM

2. Se l'indirizzo email dell'utente a cui concedere il ruolo è presente nell'elenco, selezionalo e fai clic su Modifica. Poi, fai clic su Aggiungi un altro ruolo.

   Se l'indirizzo email dell'utente non è presente nell'elenco, fai clic su Aggiungi, quindi inserisci l'indirizzo email nella casella Nuovi principali.

3. Fai clic sull'elenco a discesa Seleziona un ruolo.

4. Fai clic su BigQuery, poi su BigQuery Data Policy Admin, BigQuery Admin o BigQuery Data Owner.

5. Fai clic su Salva.

Il ruolo Visualizzatore organizzazione

Il ruolo Visualizzatore organizzazione consente agli utenti di visualizzare i dettagli della risorsa dell'organizzazione. Per concedere questo ruolo, devi disporre dell'autorizzazione resourcemanager.organizations.setIamPolicy nell'organizzazione.

Ruolo Lettore granulare Data Catalog

Gli utenti che devono accedere ai dati protetti con il controllo dell'accesso a livello di colonna devono disporre del ruolo Lettore granulare Data Catalog o di qualsiasi altro ruolo a cui è stata concessa l'autorizzazionedatacatalog.categories.fineGrainedGet. Questo ruolo viene assegnato alle entità nell'ambito della configurazione di un tag di criteri.

Per concedere a un utente il ruolo Lettore granulare per un tag di criteri, devi disporre dell'autorizzazione datacatalog.taxonomies.setIamPolicy per il progetto che contiene la tassonomia di quetag di criteriio. Se non disponi dell'autorizzazione datacatalog.taxonomies.setIamPolicy, chiedi a un Proprietario progetto di concederti l'autorizzazione o di eseguire l'azione per te.

Per le istruzioni, vedi Impostare le autorizzazioni per i tag delle policy.

Configurare controllo dell'accesso a livello di colonna

Configura controllo dell'accesso a livello di colonna completando queste attività:

• Crea una tassonomia di tag di criteri.
• Associa le entità ai tag di criteri e concedi alle entità il ruolo Lettore granulare Data Catalog.
• Associa i tag di criteri alle colonne della tabella BigQuery.
• Applica controllo dell'accesso alla tassonomia contenente i tag criterio.

Creazione tassonomie

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

Console

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

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 elencata in Posizione.
   5. In Tag delle norme, inserisci un nome e una descrizione per tag di criteri.
   6. Per aggiungere un tag di criteri figlio a un tag di criteri, fai clic su Aggiungi tag secondario.
   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 policy e tag policy figlio in base alle esigenze della tua tassonomia.
   9. Al termine della creazione dei tag criterio per la gerarchia, fai clic su Crea.

API

Per utilizzare le classificazioni esistenti, chiama taxonomies.import al posto dei primi due passaggi della seguente procedura.

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

Imposta le autorizzazioni per i tag delle policy

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

Console

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sul nome della tassonomia che contiene i tag criterio pertinenti.

3. Seleziona uno o più tag di criterio.

4. Se il riquadro Informazioni è nascosto, fai clic su Mostra riquadro informazioni.

5. Nel riquadro Informazioni, puoi visualizzare i ruoli e le entità per i tag di policy selezionati. Aggiungi il ruolo Amministratore tag policy agli account che creano e gestiscono i tag policy. Aggiungi il ruolo Lettore granulare agli account che devono avere accesso ai dati protetti dal controllo dell'accesso a livello di colonna. Utilizzi questo pannello anche per rimuovere i ruoli dagli account o modificare altre autorizzazioni.

6. Fai clic su Salva.

API

Chiama taxonomies.policytag.setIamPolicy per concedere l'accesso a un tag di criteri assegnando le entità ai ruoli appropriati.

Imposta i tag di policy sulle colonne

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 BigQuery Admin (roles/bigquery.admin) e BigQuery Data Owner (roles/bigquery.dataOwner).

Per visualizzare le classificazioni 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.

Nota: puoi assegnare un solo tag di criteri per colonna.

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 BigQuery Explorer, individua e seleziona la tabella da aggiornare. Si apre 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 a questa:

   

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 contenente 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 risorsa del tag 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 il numero tables.patch o, per le nuove tabelle, chiama il numero tables.insert. Utilizza la proprietà schema dell'oggetto Table che trasmetti per impostare un tag di criteri nella definizione dello schema. Consulta lo schema dell'esempio di riga di comando per scoprire come impostare untag di criteriy.

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

Altri modi per impostare i tag dei criteri sulle colonne

Puoi anche impostare i tag dei criteri quando:

• Utilizza bq mk per creare una tabella. Trasmetti uno schema da utilizzare per la creazione della tabella.
• Utilizza bq load per caricare i dati in una tabella. Passa uno schema da utilizzare quando carichi la tabella.

Per informazioni generali sullo schema, vedi Specifica di uno schema.

Applica controllo di accesso

Segui queste istruzioni per attivare o disattivare l'applicazione del controllo dell'accesso'accesso.

L'applicazione del controllo dell'accesso richiede la creazione di una policy dei dati. Questa operazione viene eseguita automaticamente se applichi ilcontrollo dell'accessoo utilizzando la consoleGoogle Cloud . Se vuoi applicare il controllo dell'accesso dell'accesso utilizzando l'API BigQuery Data Policy, devi creare esplicitamente i criteri dei dati.

L'entità che applica controllo dell'accesso'accesso deve disporre del ruolo Amministratore BigQuery o del ruolo Proprietario dati BigQuery. L'entità deve disporre anche del ruolo Amministratore Data Catalog o Visualizzatore Data Catalog.

Per interrompere l'applicazione del controllo dell'accesso, se è attivo, fai clic su Applica controllo dell'accesso per attivare/disattivare il controllo.

Se hai policy sui dati associate a uno dei tag criterio nella tassonomia, devi eliminare tutte le policy sui dati nella tassonomia prima di interrompere l'applicazione del controllo dell'accesso#39;accesso. Se elimini le norme sui dati utilizzando l'API BigQuery Data Policy, devi eliminare tutte le norme sui dati con un dataPolicyType di DATA_MASKING_POLICY. Per saperne di più, consulta Eliminare le norme relative ai dati.

Creare una norma sui dati

Per creare una norma sui dati:

Console

Per applicare controllo dell'accesso#39;accesso:

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sulla tassonomia di cui vuoi applicare controllo dell'accesso a livello di colonna.

3. Se l'opzione Applica controllo di accesso non è già attiva, fai clic su Applica controllo di accesso per attivarla.

API

Utilizza il metodo create e trasmetti una risorsa DataPolicy in cui il campo dataPolicyType è impostato su COLUMN_LEVEL_SECURITY_POLICY.

Ottenere una norma sui dati

Per ottenere informazioni su una norma relativa ai dati:

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

Recupera il criterio IAM (Identity and Access Management) per un criterio di dati

Segui questi passaggi per ottenere il criterio IAM per una norma sui dati:

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

Elenca le norme sui dati

Per elencare le norme relative ai dati:

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

Eliminare un criterio relativo ai dati

Per eliminare una norma sui dati:

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

Utilizzare i tag di policy

Utilizza questa sezione per scoprire come visualizzare, modificare ed eliminare i tag delle policy.

Visualizzare i tag di policy

Per visualizzare i tag criterio che hai creato per una tassonomia:

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sulla tassonomia di cui vuoi visualizzare i tag policy. La pagina Tassonomie mostra i tag di policy nella tassonomia.

Visualizzare i tag di criteri nello schema

Puoi visualizzare i tag di policy applicati a una tabella quando esamini lo schema della tabella. Puoi visualizzare lo schema utilizzando la console Google Cloud , lo strumento a riga di comando bq, l'API BigQuery e le librerie client. Per informazioni dettagliate su come visualizzare lo schema, vedi Recupero delle informazioni sulla tabella.

Visualizzare le autorizzazioni sui tag di criteri

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sul nome della tassonomia che contiene i tag criterio pertinenti.

3. Seleziona uno o più tag di criterio.

4. Se il riquadro Informazioni è nascosto, fai clic su Mostra riquadro informazioni.

5. Nel riquadro Informazioni, puoi visualizzare i ruoli e le entità per i tag di policy selezionati.

Aggiornare le autorizzazioni sui tag di policy

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

Console

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sul nome della tassonomia che contiene i tag criterio pertinenti.

3. Seleziona uno o più tag di criterio.

4. Se il riquadro Informazioni è nascosto, fai clic su Mostra riquadro informazioni.

5. Nel riquadro Informazioni, puoi visualizzare i ruoli e le entità per i tag di policy selezionati. Aggiungi il ruolo Amministratore tag policy agli account che creano e gestiscono i tag policy. Aggiungi il ruolo Lettore granulare agli account che devono avere accesso ai dati protetti dal controllo dell'accesso a livello di colonna. Utilizzi questo pannello anche per rimuovere i ruoli dagli account o modificare altre autorizzazioni.

6. Fai clic su Salva.

API

Chiama taxonomies.policytag.setIamPolicy per concedere l'accesso a un tag di criteri assegnando le entità ai ruoli appropriati.

Recupera i nomi delle risorse tag di criteri

Il nome risorsa del tag di criteri è necessario quando applichi il tag di criteri a una colonna.

Per recuperare il nome risorsa del tag di criteri:

1. Visualizza i tag di policy per la tassonomia che contiene il tag di criteri.

2. Trova il tag di criteri di cui vuoi copiare il nome risorsa.

3. Fai clic sull'icona Copia nome risorsa tag policy.

   

Cancella tag di criteri

Aggiorna lo schema della tabella per rimuovere un tag di criteri da una colonna. Puoi utilizzare la consoleGoogle Cloud , lo strumento a riga di comando bq e il metodo API BigQuery per cancellare un tag di criteri da una colonna.

Console

Nella pagina Schema attuale, fai clic su X in Tag di criteri.



bq

Nota: per cancellare un tag di criteri, devi impostare esplicitamente il campo names di policyTags su un elenco vuoto, []. Se elimini il campo policyTags, non ha alcun effetto sui tag criterio esistenti. Questo comportamento è intenzionale, per impedire la rimozione accidentale di tag criterio che potrebbero esporre dati sensibili.

1. Recupera lo schema e salvalo 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 contenente la tabella che stai aggiornando.
   • table è il nome della tabella che stai aggiornando.

2. Modifica schema.json per cancellare un tag di criteri da una colonna.

   [
    ...
    {
      "name": "ssn",
      "type": "STRING",
      "mode": "REQUIRED",
      "policyTags": {
        "names": []
      }
    },
    ...
   ]

3. Aggiorna lo schema.

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

API

Nota: per cancellare un tag di criteri, devi impostare esplicitamente il campo names di policyTags su un elenco vuoto, []. Se elimini il campo policyTags, non ha alcun effetto sui tag criterio esistenti. Questo comportamento è intenzionale, per impedire la rimozione accidentale di tag di policy che potrebbero esporre dati sensibili.

Chiama tables.patch e utilizza la proprietà schema per cancellare un tag di criteri nella definizione dello schema. Consulta lo schema dell'esempio di riga di comando per scoprire come cancellare un tag di criteri.

Poiché il metodo tables.update sostituisce l'intera risorsa della tabella, è preferibile il metodo tables.patch.

Elimina tag di policy

Puoi eliminare uno o più tag policy in una tassonomia oppure puoi eliminare la tassonomia e tutti i tag policy che contiene. L'eliminazione di un tag di criteri rimuove automaticamente l'associazione tra iltag di criterio e le colonne a cui è stato applicato.

Quando elimini un tag di criteri a cui è associato un criterio relativo ai dati, potrebbero essere necessari fino a 30 minuti prima che anche il criterio relativo ai dati venga eliminato. Puoi eliminare direttamente il criterio relativo ai dati se vuoi che venga eliminato immediatamente.

Per eliminare uno o più tag policy in una tassonomia:

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sul nome della tassonomia contenente i tag da eliminare.
3. Fai clic su Modifica.
4. Fai clic su accanto ai tag di policy da eliminare.
5. Fai clic su Salva.
6. Fai clic su Conferma.

Per eliminare un'intera tassonomia:

1. Apri la pagina Tassonomie di tag di criteri nella consoleGoogle Cloud .

   Apri la pagina Tassonomie di tag di criteri

2. Fai clic sul nome della tassonomia contenente i tag da eliminare.
3. Fai clic su Elimina tassonomia dei tag di policy.
4. Digita il nome della tassonomia e fai clic su Elimina.

Eseguire query sui dati con controllo dell'accesso a livello di colonna

Se un utente ha accesso al set di dati e dispone del ruolo Lettore granulare di Data Catalog, i dati delle colonne sono disponibili per l'utente. L'utente esegue una query come di consueto.

Se un utente ha accesso al set di dati, ma non ha il ruolo Lettore granulare di Data Catalog, i dati delle colonne non sono disponibili per l'utente. Se un utente di questo tipo esegue SELECT *, riceve un errore che elenca le colonne a cui non può accedere. Per risolvere l'errore, puoi:

• Modifica la query per escludere le colonne a cui l'utente non può accedere. Ad esempio, se l'utente non ha accesso alla colonna ssn, ma ha accesso alle colonne rimanenti, può eseguire la seguente query:

  SELECT * EXCEPT (ssn) FROM ...

  Nell'esempio precedente, la clausola EXCEPT esclude la colonna ssn.

• Chiedi a un amministratore Data Catalog di aggiungere l'utente come lettore granulare Data Catalog alla classe di dati pertinente. Il messaggio di errore fornisce il nome completo deltag di criteriy per cui l'utente avrebbe bisogno dell'accesso.

Domande frequenti

La sicurezza a livello di colonna di BigQuery funziona per le viste?

Sì. Le viste derivano da una tabella sottostante. Lo stesso controllo dell'accesso a livello di colonna nella tabella viene applicato quando si accede alle colonne protette tramite una vista.

In BigQuery esistono due tipi di viste: viste logiche e viste autorizzate. Entrambi i tipi di viste derivano da una tabella di origine ed entrambi sono coerenti con il controllo dell'accesso a livello di colonna della tabella.

Per ulteriori informazioni, consulta la sezione Visualizzazioni autorizzate.

Controllo dell'accesso a livello di colonna funziona sulle colonne STRUCT o RECORD?

Sì. Puoi applicare i tag di policy solo ai campi foglia e solo questi campi sono protetti.

Posso utilizzare sia l'SQL precedente sia GoogleSQL?

Puoi utilizzare GoogleSQL per eseguire query sulle tabelle protette dal controllo dell'accesso a livello di colonna.

Tutte le query SQL precedente vengono rifiutate se sono presenti tag criterio nelle tabelle di destinazione.

Le query vengono registrate in Cloud Logging?

Il controllo dei tag di criteri viene registrato in Logging. Per saperne di più, consulta Audit logging per controllo dell'accesso a livello di colonna.

La copia di una tabella è interessata dal controllo dell'accesso a livello di colonna?

Sì. Non puoi copiare le colonne se non hai accesso.

Le seguenti operazioni verificano le autorizzazioni a livello di colonna.

• Query SELECT con tabelle di destinazione
• Job di copia delle tabelle
• Job di estrazione dei dati (ad esempio, in Cloud Storage)

Quando copio i dati in una nuova tabella, i tag delle norme vengono propagati automaticamente?

Nella maggior parte dei casi, no. Se copi i risultati di una query in una nuova tabella, a quest'ultima non vengono assegnati automaticamente tag di policy. Pertanto, la nuova tabella non dispone del controllo dell'accesso a livello di colonna. Lo stesso vale se esporti i dati in Cloud Storage.

L'eccezione è se utilizzi un job di copia della tabella. Poiché i job di copia delle tabelle non applicano alcuna trasformazione dei dati, i tag dei criteri vengono propagati automaticamente alle tabelle di destinazione. Questa eccezione non si applica ai job di copia delle tabelle tra regioni, perché questi job non supportano la copia dei tag di policy.

Controllo dell'accesso a livello di colonna è compatibile con Virtual Private Cloud?

Sì, controllo dell'accesso a livello di colonna e VPC sono compatibili e complementari.

VPC utilizza IAM per controllare l'accesso ai servizi, come BigQuery e Cloud Storage. Il controllo dell'accesso a livello di colonna fornisce una sicurezza granulare delle singole colonne all'interno di BigQuery.

Per applicare VPC per i tag di policy e le policy dei dati per il controllo dell'accesso a livello di colonna e il mascheramento dinamico dei dati, devi limitare le seguenti API nel perimetro:

• API Data Catalog
• API BigQuery
• API BigQuery Data Policy

Risoluzione dei problemi

Non riesco a visualizzare i ruoli Data Catalog

Se non riesci a visualizzare ruoli come Lettore granulare di Data Catalog, è possibile che tu non abbia abilitato l'API Data Catalog nel tuo progetto. Per scoprire come abilitare l'API Data Catalog, consulta la sezione Prima di iniziare. I ruoli Data Catalog dovrebbero essere visualizzati diversi minuti dopo l'abilitazione dell'API Data Catalog.

Non riesco a visualizzare la pagina Tassonomie

Per visualizzare la pagina Tassonomie, devi disporre di autorizzazioni aggiuntive. Ad esempio, il ruolo Amministratore tag di criteri di Data Catalog ha accesso alla pagina Tassonomie.

Ho applicato i tag delle norme, ma non sembra funzionare

Se continui a ricevere risultati di query per un account che non dovrebbe avere accesso, è possibile che l'account riceva risultati memorizzati nella cache. Nello specifico, se in precedenza hai eseguito la query correttamente e poi hai applicato i tag delle norme, potresti ricevere risultati dalla cache dei risultati delle query. Per impostazione predefinita, i risultati delle query vengono memorizzati nella cache per 24 ore. La query dovrebbe non riuscire immediatamente se disattivi la cache dei risultati. Per maggiori dettagli sulla memorizzazione nella cache, consulta Impatto del controllo dell'accesso a livello di colonna.

In generale, l'applicazione degli aggiornamenti IAM richiede circa 30 secondi. La propagazione delle modifiche alla gerarchia dei tag di criteri può richiedere fino a 30 minuti.

Non ho l'autorizzazione per leggere da una tabella con sicurezza a livello di colonna

Devi avere il ruolo Lettore granulare o il ruolo Lettore mascherato a diversi livelli, ad esempio organizzazione, cartella, progetto e tag di criteri. Il ruolo Lettore granulare concede l'accesso ai dati non elaborati, mentre il ruolo Lettore mascherato concede l'accesso ai dati mascherati. Puoi utilizzare lo strumento per la risoluzione dei problemi IAM per controllare questa autorizzazione a livello di progetto.

Ho impostato controllo dell'accesso granulare nella tassonomia dei tag di criteri, ma gli utenti vedono i dati protetti

Per risolvere il problema, verifica i seguenti dettagli:

• Nella pagina Tassonomia di tag di criteri, verifica che il pulsante di attivazione/disattivazione Applica controllo dell'accesso sia impostato su On.

• Assicurati che le query non utilizzino i risultati delle query memorizzati nella cache. Se utilizzi lo strumento con interfaccia a riga di comando bq per testare le query, devi utilizzare --nouse_cache flag per disattivare la cache delle query. Ad esempio:

  bq query --nouse_cache --use_legacy_sql=false "SELECT * EXCEPT (customer_pii) FROM my_table;"