Usar o IAM para controlar o acesso a recursos

Neste documento, descrevemos como ver, conceder e revogar controles de acesso para conjuntos de dados do BigQuery e para os recursos dentro deles: tabelas, visualizações e rotinas. Embora os modelos também sejam recursos no nível do conjunto de dados, não é possível conceder acesso a modelos individuais usando papéis do IAM.

É possível conceder acesso a recursos do Google Cloud com políticas de permissão, também conhecidas como políticas do Identity and Access Management (IAM), que são anexadas aos recursos. É possível anexar apenas uma política a cada recurso. A política de permissão controla o acesso ao próprio recurso e todos os descendentes desse recurso que herdam a política.

Para mais informações sobre políticas de permissão, consulte Estrutura da política na documentação do IAM.

Para este documento, é preciso conhecer o Identity and Access Management (IAM) no Google Cloud.

Limitações

• As listas de controle de acesso (ACLs) de rotina não estão incluídas nas rotinas replicadas.
• As rotinas em conjuntos de dados externos ou vinculados não são compatíveis com controles de acesso.
• As tabelas em conjuntos de dados externos ou vinculados não são compatíveis com controles de acesso.
• Não é possível definir controles de acesso de rotina com o Terraform.
• Não é possível definir controles de acesso de rotina com o SDK Google Cloud.
• Não é possível definir controles de acesso de rotina usando a linguagem de controle de dados (DCL) do BigQuery.
• O Data Catalog não é compatível com controles de acesso de rotina. Se um usuário tiver concedido acesso condicional no nível da rotina, ele não vai ver as rotinas no painel lateral do BigQuery. Como solução alternativa, conceda acesso no nível do conjunto de dados.
• A visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES não mostra controles de acesso para rotinas.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Funções exigidas

Para conseguir as permissões necessárias para modificar as políticas do IAM para recursos, peça ao administrador para conceder a você o papel do IAM de Proprietário de dados do BigQuery (roles/bigquery.dataOwner) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para modificar as políticas do IAM para recursos. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para modificar as políticas do IAM para recursos:

• Para ver a política de acesso a um conjunto de dados: bigquery.datasets.get
• Para definir a política de acesso de um conjunto de dados: bigquery.datasets.update
• Para ver a política de acesso a um conjunto de dados (somente no consoleGoogle Cloud ): bigquery.datasets.getIamPolicy
• Para definir a política de acesso a um conjunto de dados (somente console): bigquery.datasets.setIamPolicy
• Para ver a política de uma tabela ou visualização: bigquery.tables.getIamPolicy
• Para definir a política de uma tabela ou visualização: bigquery.tables.setIamPolicy
• Para acessar a política de acesso de uma rotina: bigquery.routines.getIamPolicy
• Para definir a política de acesso de uma rotina: bigquery.routines.setIamPolicy
• Para criar a ferramenta bq ou jobs do SQL do BigQuery (opcional): bigquery.jobs.create

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

Trabalhar com controles de acesso a conjuntos de dados

É possível conceder acesso a um conjunto de dados atribuindo a um principal do IAM um papel predefinido ou personalizado que determina o que o principal pode fazer com o conjunto de dados. Isso também é conhecido como anexar uma política de permissão a um recurso. Depois de conceder acesso, é possível conferir os controles de acesso do conjunto de dados e revogar o acesso a ele.

Conceder acesso a um conjunto de dados

Não é possível conceder acesso a um conjunto de dados ao criá-lo usando a UI da Web do BigQuery ou a ferramenta de linha de comando bq. É preciso primeiro criar o conjunto de dados e depois conceder acesso a ele. Com a API, é possível conceder acesso durante a criação do conjunto de dados chamando o método datasets.insert com um recurso de conjunto de dados definido.

Um projeto é o recurso principal de um conjunto de dados, e um conjunto de dados é o recurso principal de tabelas e visualizações, rotinas e modelos. Quando você concede um papel no nível do projeto, o papel e as permissões dele são herdados pelo conjunto de dados e pelos recursos dele. Da mesma forma, quando você concede um papel no nível do conjunto de dados, o papel e as permissões dele são herdados pelos recursos dentro do conjunto.

É possível conceder acesso a um conjunto de dados atribuindo uma permissão de função do IAM para acessar o conjunto de dados ou concedendo acesso condicionalmente usando uma condição do IAM. Para mais informações sobre como conceder acesso condicional, consulte Controlar o acesso com as condições do IAM.

Observação: a concessão de acesso a um conjunto de dados não o lista automaticamente no painel Explorer. Para visualizar um projeto no painel Explorer, consulte Marcar um projeto com estrela.

Para conceder a um papel do IAM acesso a um conjunto de dados sem usar condições, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados para compartilhar.

3. Clique em Compartilhamento > Permissões.

4. Clique em adicionar conta principal.

5. No campo Novos principais, digite um principal..

6. Na lista Selecionar papel, escolha uma função predefinida ou personalizada..

7. Clique em Save.

8. Para retornar às informações do conjunto de dados, clique em Fechar.

SQL

Para conceder aos principais acesso aos conjuntos de dados, use a instrução DCL GRANT:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   GRANT `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   TO "USER_LIST"

   Substitua:

   • ROLE_LIST: um papel ou uma lista de papéis separados por vírgulas que você queira conceder.
   • RESOURCE_NAME: o nome do conjunto de dados a que você está concedendo acesso.

   • USER_LIST: uma lista separada por vírgulas de usuários a que o papel é concedido.

     Para ver uma lista de formatos válidos, consulte user_list.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

O exemplo a seguir concede o papel de Leitor de dados do BigQuery a myDataset:

GRANT `roles/bigquery.dataViewer`
ON SCHEMA `myProject`.myDataset
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para gravar as informações do conjunto de dados atual (incluindo controles de acesso) em um arquivo JSON, use o comando bq show:

   bq show \
       --format=prettyjson \
       PROJECT_ID:DATASET > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados
   • PATH_TO_FILE: o caminho para o arquivo JSON em sua máquina local.

3. Faça suas alterações na seção access do arquivo JSON. É possível adicionar qualquer uma das entradas specialGroup: projectOwners, projectWriters, projectReaders e allAuthenticatedUsers. Também é possível adicionar qualquer uma das seguintes opções: userByEmail, groupByEmail e domain.

   Por exemplo, a seção access do arquivo JSON de um conjunto de dados tem esta aparência:

   {
    "access": [
     {
      "role": "READER",
      "specialGroup": "projectReaders"
     },
     {
      "role": "WRITER",
      "specialGroup": "projectWriters"
     },
     {
      "role": "OWNER",
      "specialGroup": "projectOwners"
     },
     {
      "role": "READER",
      "specialGroup": "allAuthenticatedUsers"
     },
     {
      "role": "READER",
      "domain": "domain_name"
     },
     {
      "role": "WRITER",
      "userByEmail": "user_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }

4. Quando as edições estiverem concluídas, use o comando bq update e inclua o arquivo JSON usando a flag --source. Se o conjunto de dados estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato: PROJECT_ID:DATASET.

   Cuidado: quando você aplica o arquivo JSON que contém os controles de acesso, os controles de acesso atuais são substituídos.

     bq update 
   
     --source PATH_TO_FILE 
   
     PROJECT_ID:DATASET
     

5. Para verificar as alterações no controle de acesso, insira o comando bq show novamente sem gravar as informações em um arquivo.

   bq show --format=prettyjson PROJECT_ID:DATASET

Terraform

Use os recursos google_bigquery_dataset_iam para atualizar o acesso a um conjunto de dados.

Importante: os diferentes recursos fornecidos por google_bigquery_dataset_iam podem entrar em conflito entre si e com o recurso google_bigquery_dataset_access. Leia a documentação google_bigquery_dataset_iam com atenção antes de fazer mudanças no controle de acesso usando o Terraform.

Definir a política de acesso para um conjunto de dados

O exemplo a seguir mostra como usar o recurso google_bigquery_dataset_iam_policy para definir a política do IAM para o conjunto de dados mydataset. Isso substitui qualquer política existente já anexada ao conjunto de dados:

# This file sets the IAM policy for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.admin"
    members = [
      "user:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "group:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataEditor"
    members = [
      "serviceAccount:[e-mail]",
    ]
  }
}

resource "google_bigquery_dataset_iam_policy" "dataset_iam_policy" {
  dataset_id  = google_bigquery_dataset.default.dataset_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

Definir associação de papel para um conjunto de dados

O exemplo a seguir mostra como usar o recurso google_bigquery_dataset_iam_binding para definir a associação em um determinado papel para o conjunto de dados mydataset. Isso substitui qualquer associação existente nesse papel. Outros papéis na política do IAM para o conjunto de dados são preservados:

# This file sets membership in an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_binding" "dataset_iam_binding" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.jobUser"

  members = [
    "user:[e-mail]",
    "group:[e-mail]"
  ]
}

Definir associação de papel para um único principal

O exemplo a seguir mostra como usar o recurso google_bigquery_dataset_iam_member para atualizar a política do IAM para o conjunto de dados mydataset a fim de conceder um papel a um só principal. A atualização dessa política do IAM não afeta o acesso de outros principais que receberam esse papel no conjunto de dados.

# This file adds a member to an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_member" "dataset_iam_member" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.user"
  member     = "user:[e-mail]"
}

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu Google Cloud projeto para conferir os resultados. No console Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu Google Cloud projeto.

API

Para aplicar controles de acesso quando o conjunto de dados for criado, chame o método datasets.insert com um recurso de conjunto de dados definido. Para atualizar os controles de acesso, chame o método datasets.patch e use a propriedade access no recurso Dataset.

Como datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch para atualizar os controles de acesso.

Go

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

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

Defina a nova lista de acesso anexando a nova entrada à lista atual com o tipo DatasetMetadataToUpdate . Em seguida, chame a função dataset.Update() para atualizar a propriedade.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// grantAccessToDataset creates a new ACL conceding the READER role to the group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func grantAccessToDataset(w io.Writer, projectID, datasetID string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"

	ctx := context.Background()

	// Create BigQuery handler.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Create dataset handler
	dataset := client.Dataset(datasetID)

	// Get metadata
	meta, err := dataset.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Metadata: %w", err)
	}

	// Find more details about BigQuery Entity Types here:
	// https://pkg.go.dev/cloud.google.com/go/bigquery#EntityType
	//
	// Find more details about BigQuery Access Roles here:
	// https://pkg.go.dev/cloud.google.com/go/bigquery#AccessRole

	entityType := bigquery.GroupEmailEntity
	entityID := "[e-mail]"
	roleType := bigquery.ReaderRole

	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       roleType,
			EntityType: entityType,
			Entity:     entityID,
		}),
	}

	// Leverage the ETag for the update to assert there's been no modifications to the
	// dataset since the metadata was originally read.
	meta, err = dataset.Update(ctx, update, meta.ETag)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)
	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entities: %v\n", access.Entity)
	}

	return nil
}

Java

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

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

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Entity;
import com.google.cloud.bigquery.Acl.Group;
import com.google.cloud.bigquery.Acl.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.ArrayList;
import java.util.List;

public class GrantAccessToDataset {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Group to add to the ACL
    String entityEmail = "[e-mail]";

    grantAccessToDataset(projectId, datasetName, entityEmail);
  }

  public static void grantAccessToDataset(
      String projectId, String datasetName, String entityEmail) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Create a new Entity with the corresponding type and email
      // "[e-mail]"
      // For more information on the types of Entities available see:
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity
      // and
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity.Type
      Entity entity = new Group(entityEmail);

      // Create a new ACL granting the READER role to the group with the entity email
      // "[e-mail]"
      // For more information on the types of ACLs available see:
      // https://cloud.google.com/storage/docs/access-control/lists
      Acl newEntry = Acl.of(entity, Role.READER);

      // Get a copy of the ACLs list from the dataset and append the new entry.
      List<Acl> acls = new ArrayList<>(dataset.getAcl());
      acls.add(newEntry);

      // Update the ACLs by setting the new list.
      Dataset updatedDataset = bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println(
          "ACLs of dataset \""
              + updatedDataset.getDatasetId().getDataset()
              + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("ACLs were not updated \n" + e.toString());
    }
  }
}

Node.js

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

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

Defina a nova lista de acesso anexando a nova entrada à lista atual usando o método Dataset#metadata. Em seguida, chame a função Dataset#setMetadata() para atualizar a propriedade.

/**
 * TODO(developer): Update and un-comment below lines.
 */

// const datasetId = "my_project_id.my_dataset_name";

// ID of the user or group from whom you are adding access.
// const entityId = "[e-mail]";

// One of the "Basic roles for datasets" described here:
// https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
// const role = "READER";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

// Type of entity you are granting access to.
// Find allowed allowed entity type names here:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#resource:-dataset
const entityType = 'groupByEmail';

async function grantAccessToDataset() {
  const [dataset] = await client.dataset(datasetId).get();

  // The 'access entries' array is immutable. Create a copy for modifications.
  const entries = [...dataset.metadata.access];

  // Append an AccessEntry to grant the role to a dataset.
  // Find more details about the AccessEntry object in the BigQuery documentation:
  // https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
  entries.push({
    role,
    [entityType]: entityId,
  });

  // Assign the array of AccessEntries back to the dataset.
  const metadata = {
    access: entries,
  };

  // Update will only succeed if the dataset
  // has not been modified externally since retrieval.
  //
  // See the BigQuery client library documentation for more details on metadata updates:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest

  // Update just the 'access entries' property of the dataset.
  await client.dataset(datasetId).setMetadata(metadata);

  console.log(
    `Role '${role}' granted for entity '${entityId}' in '${datasetId}'.`
  );
}

Python

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

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

Defina a propriedade dataset.access_entries com os controles de acesso de um conjunto de dados. Em seguida, chame a função client.update_dataset() para atualizar a propriedade.

from google.api_core.exceptions import PreconditionFailed
from google.cloud import bigquery
from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Update and uncomment the lines below.

# ID of the dataset to grant access to.
# dataset_id = "my_project_id.my_dataset"

# ID of the user or group receiving access to the dataset.
# Alternatively, the JSON REST API representation of the entity,
# such as the view's table reference.
# entity_id = "[e-mail]"

# One of the "Basic roles for datasets" described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
# role = "READER"

# Type of entity you are granting access to.
# Find allowed allowed entity type names here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/enums#class-googlecloudbigqueryenumsentitytypesvalue
entity_type = EntityTypes.GROUP_BY_EMAIL

# Instantiate a client.
client = bigquery.Client()

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# The `access_entries` list is immutable. Create a copy for modifications.
entries = list(dataset.access_entries)

# Append an AccessEntry to grant the role to a dataset.
# Find more details about the AccessEntry object here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)

# Assign the list of AccessEntries back to the dataset.
dataset.access_entries = entries

# Update will only succeed if the dataset
# has not been modified externally since retrieval.
#
# See the BigQuery client library documentation for more details on `update_dataset`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client#google_cloud_bigquery_client_Client_update_dataset
try:
    # Update just the `access_entries` property of the dataset.
    dataset = client.update_dataset(
        dataset,
        ["access_entries"],
    )

    # Show a success message.
    full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
    print(
        f"Role '{role}' granted for entity '{entity_id}'"
        f" in dataset '{full_dataset_id}'."
    )
except PreconditionFailed:  # A read-modify-write error
    print(
        f"Dataset '{dataset.dataset_id}' was modified remotely before this update. "
        "Fetch the latest version and retry."
    )

Papéis predefinidos que concedem acesso a conjuntos de dados

Você pode conceder acesso a um conjunto de dados com os seguintes papéis predefinidos do IAM.

Atenção: embora seja possível conceder permissões de administrador do BigQuery ou do BigQuery Studio em um conjunto de dados, não conceda esses papéis no nível do conjunto de dados. O proprietário de dados do BigQuery também concede todas as permissões para o conjunto de dados e é um papel com menos privilégios. Normalmente, os administradores do BigQuery e do BigQuery Studio recebem permissão no nível do projeto.

Papel	Descrição
Proprietário de dados do BigQuery (roles/bigquery.dataOwner)	Quando concedido em um conjunto de dados, esse papel concede as seguintes permissões: Todas as permissões para o conjunto de dados e para todos os recursos dele: tabelas e visualizações, modelos e rotinas. Observação:quando concedido no nível do projeto, os proprietários de dados também podem criar novos conjuntos de dados e listar aqueles a que têm acesso no projeto.
Editor de dados do BigQuery (roles/bigquery.dataEditor)	Quando concedido em um conjunto de dados, esse papel concede as seguintes permissões: Recebe metadados e permissões para o conjunto de dados. Para tabelas e visualizações: criar, atualizar, receber, listar e excluir as tabelas e visualizações do conjunto de dados. Ler (consultar), exportar, replicar e atualizar dados da tabela. Criar, atualizar e excluir índices. Criar e restaurar snapshots. Todas as permissões para as rotinas e modelos do conjunto de dados. Observação:quando concedida no nível do projeto, a função de editor de dados também pode criar e listar conjuntos de dados no projeto a que tem acesso.
Leitor de dados do BigQuery (roles/bigquery.dataViewer)	Quando concedido em um conjunto de dados, esse papel concede as seguintes permissões: Recebe metadados e permissões para o conjunto de dados. Listar tabelas, visualizações e modelos de um conjunto de dados. Receber metadados e controles de acesso para as tabelas e visualizações do conjunto de dados. Ler (consultar), replicar e exportar dados de tabelas e criar snapshots. Listar e invocar as rotinas do conjunto de dados.
Leitor de metadados do BigQuery (roles/bigquery.metadataViewer)	Quando concedido em um conjunto de dados, esse papel concede as seguintes permissões: Receba metadados e controles de acesso para o conjunto de dados. Receba metadados e controles de acesso para tabelas e visualizações. Receber metadados dos modelos e rotinas do conjunto de dados. listar tabelas, visualizações, modelos e rotinas no conjunto de dados;

Permissões do conjunto de dados

A maioria das permissões que começam com bigquery.datasets se aplicam no nível do conjunto de dados. bigquery.datasets.create não. Para criar conjuntos de dados, a permissão bigquery.datasets.create precisa ser concedida a uma função no contêiner principal, ou seja, o projeto.

A tabela a seguir lista todas as permissões para conjuntos de dados e o recurso de menor nível a que elas podem ser aplicadas.

Permissão	Recurso	Ação
bigquery.datasets.create	Projeto	Crie conjuntos de dados no projeto.
bigquery.datasets.get	Conjunto de dados	Receba metadados e controles de acesso para o conjunto de dados. A visualização de permissões no console também requer a permissão bigquery.datasets.getIamPolicy.
bigquery.datasets.getIamPolicy	Conjunto de dados	Necessário no console para conceder ao usuário permissão para receber os controles de acesso de um conjunto de dados. Falha ao abrir. O console também exige a permissão bigquery.datasets.get para visualizar o conjunto de dados.
bigquery.datasets.update	Conjunto de dados	Atualize os metadados e os controles de acesso do conjunto de dados. A atualização dos controles de acesso no console também requer a permissão bigquery.datasets.setIamPolicy.
bigquery.datasets.setIamPolicy	Conjunto de dados	Necessário no console para conceder ao usuário permissão para definir os controles de acesso de um conjunto de dados. Falha ao abrir. O console também exige a permissão bigquery.datasets.update para atualizar o conjunto de dados.
bigquery.datasets.delete	Conjunto de dados	Excluir um conjunto de dados.
bigquery.datasets.createTagBinding	Conjunto de dados	Anexe tags ao conjunto de dados.
bigquery.datasets.deleteTagBinding	Conjunto de dados	Remova as tags do conjunto de dados.
bigquery.datasets.listTagBindings	Conjunto de dados	Lista as tags do conjunto de dados.
bigquery.datasets.listEffectiveTags	Conjunto de dados	Lista as tags efetivas (aplicadas e herdadas) do conjunto de dados.
bigquery.datasets.link	Conjunto de dados	Crie um conjunto de dados vinculado.
bigquery.datasets.listSharedDatasetUsage	Projeto	Liste as estatísticas de uso de conjuntos de dados compartilhados para aqueles a que você tem acesso no projeto. Essa permissão é necessária para consultar a visualização INFORMATION_SCHEMA.SHARED_DATASET_USAGE.

Ver controles de acesso para um conjunto de dados

Para conferir os controles de acesso definidos explicitamente em um conjunto de dados, escolha uma das seguintes opções. Para ver os papéis herdados de um conjunto de dados, use a UI da Web do BigQuery.

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. Clique em Compartilhamento > Permissões.

   Os controles de acesso do conjunto de dados aparecem no painel Permissões do conjunto de dados.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para receber uma política atual e enviá-la para um arquivo local em JSON, use o comando bq show no Cloud Shell:

   bq show \
      --format=prettyjson \
      PROJECT_ID:DATASET > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados
   • PATH_TO_FILE: o caminho para o arquivo JSON na sua máquina local.

SQL

Prévia

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Consulte a visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES. As consultas para recuperar controles de acesso de um conjunto de dados precisam especificar object_name.

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   SELECT
   COLUMN_LIST
   FROM
     PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
   WHERE
   object_name = "DATASET";

   Substitua:

   • COLUMN_LIST: uma lista separada por vírgulas de colunas da visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES.
   • PROJECT_ID: ID do projeto;
   • REGION: um qualificador de região
   • DATASET: o nome de um conjunto de dados no projeto.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplo:

Essa consulta recebe controles de acesso para mydataset.

SELECT
object_name, privilege_type, grantee
FROM
my_project.`region-us`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
WHERE
object_name = "mydataset";

A saída será semelhante a esta:

+------------------+-----------------------------+-------------------------+
|   object_name    |  privilege_type             | grantee                 |
+------------------+-----------------------------+-------------------------+
| mydataset        | roles/bigquery.dataOwner    | projectOwner:myproject  |
| mydataset        | roles/bigquery.dataViwer    | user:[e-mail]   |
+------------------+-----------------------------+-------------------------+

API

Para conferir os controles de acesso de um conjunto de dados, chame o método datasets.get com um recurso dataset definido.

Os controles de acesso aparecem na propriedade access do recurso dataset.

Go

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

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

Chame a função client.Dataset().Metadata(). A política de acesso está disponível na propriedade Access.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// viewDatasetAccessPolicies retrieves the ACL for the given dataset
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func viewDatasetAccessPolicies(w io.Writer, projectID, datasetID string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"

	ctx := context.Background()

	// Create new client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get dataset's metadata.
	meta, err := client.Dataset(datasetID).Metadata(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Client.Dataset.Metadata: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)

	// Iterate over access permissions.
	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entity: %v\n", access.Entity)
	}

	return nil
}

Java

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

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

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.List;

public class GetDatasetAccessPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    getDatasetAccessPolicy(projectId, datasetName);
  }

  public static void getDatasetAccessPolicy(String projectId, String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Show ACL details.
      // Find more information about ACL and the Acl Class here:
      // https://cloud.google.com/storage/docs/access-control/lists
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl
      List<Acl> acls = dataset.getAcl();
      System.out.println("ACLs in dataset \"" + dataset.getDatasetId().getDataset() + "\":");
      System.out.println(acls.toString());
      for (Acl acl : acls) {
        System.out.println();
        System.out.println("Role: " + acl.getRole());
        System.out.println("Entity: " + acl.getEntity());
      }
    } catch (BigQueryException e) {
      System.out.println("ACLs info not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

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

Recupere os metadados do conjunto de dados usando a função Dataset#getMetadata(). A política de acesso está disponível na propriedade de acesso do objeto de metadados resultante.

/**
 * TODO(developer): Update and un-comment below lines
 */
// const datasetId = "my_project_id.my_dataset";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const bigquery = new BigQuery();

async function viewDatasetAccessPolicy() {
  const dataset = bigquery.dataset(datasetId);

  const [metadata] = await dataset.getMetadata();
  const accessEntries = metadata.access || [];

  // Show the list of AccessEntry objects.
  // More details about the AccessEntry object in the BigQuery documentation:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest
  console.log(
    `${accessEntries.length} Access entries in dataset '${datasetId}':`
  );
  for (const accessEntry of accessEntries) {
    console.log(`Role: ${accessEntry.role || 'null'}`);
    console.log(`Special group: ${accessEntry.specialGroup || 'null'}`);
    console.log(`User by Email: ${accessEntry.userByEmail || 'null'}`);
  }
}

Python

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

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

Chame a função client.get_dataset(). A política de acesso está disponível na propriedade dataset.access_entries.

from google.cloud import bigquery

# Instantiate a client.
client = bigquery.Client()

# TODO(developer): Update and uncomment the lines below.

# Dataset from which to get the access policy.
# dataset_id = "my_dataset"

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# Show the list of AccessEntry objects.
# More details about the AccessEntry object here:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.AccessEntry
print(
    f"{len(dataset.access_entries)} Access entries found "
    f"in dataset '{dataset_id}':"
)

for access_entry in dataset.access_entries:
    print()
    print(f"Role: {access_entry.role}")
    print(f"Special group: {access_entry.special_group}")
    print(f"User by Email: {access_entry.user_by_email}")

Revogar acesso a um conjunto de dados

Para revogar o acesso a um conjunto de dados, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. No painel de detalhes, clique em Compartilhamento>Permissões.

4. Na caixa de diálogo Permissões do conjunto de dados, expanda o principal cujo acesso você quer revogar.

5. Clique em Remover principal.

6. Na caixa de diálogo Remover papel do principal?, clique em Remover.

7. Para retornar aos detalhes do conjunto de dados, clique em Fechar.

Observação: se não for possível revogar o acesso ao conjunto de dados, o principal poderá ter herdados o acesso de um nível superior na hierarquia de recursos.

SQL

Para remover o acesso de um principal a um conjunto de dados, use a instrução DCL REVOKE:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   REVOKE `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   FROM "USER_LIST"

   Substitua:

   • ROLE_LIST: um papel ou uma lista de papéis separados por vírgulas que você queira revogar
   • RESOURCE_NAME: o nome do recurso em que você quer revogar a permissão.

   • USER_LIST: uma lista separada por vírgulas de usuários que terão os papéis revogados.

     Para ver uma lista de formatos válidos, consulte user_list.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

O exemplo a seguir revoga o papel de proprietário de dados do BigQuery de myDataset:

REVOKE `roles/bigquery.dataOwner`
ON SCHEMA `myProject`.myDataset
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para gravar as informações do conjunto de dados atual (incluindo controles de acesso) em um arquivo JSON, use o comando bq show:

   bq show \
       --format=prettyjson \
       PROJECT_ID:DATASET > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados
   • PATH_TO_FILE: o caminho para o arquivo JSON em sua máquina local.

3. Faça suas alterações na seção access do arquivo JSON. É possível remover qualquer uma das entradas specialGroup: projectOwners, projectWriters, projectReaders e allAuthenticatedUsers. Também é possível remover qualquer um dos itens a seguir: userByEmail, groupByEmail e domain.

   Por exemplo, a seção access do arquivo JSON de um conjunto de dados tem esta aparência:

   {
    "access": [
     {
      "role": "READER",
      "specialGroup": "projectReaders"
     },
     {
      "role": "WRITER",
      "specialGroup": "projectWriters"
     },
     {
      "role": "OWNER",
      "specialGroup": "projectOwners"
     },
     {
      "role": "READER",
      "specialGroup": "allAuthenticatedUsers"
     },
     {
      "role": "READER",
      "domain": "domain_name"
     },
     {
      "role": "WRITER",
      "userByEmail": "user_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }

4. Quando as edições estiverem concluídas, use o comando bq update e inclua o arquivo JSON usando a flag --source. Se o conjunto de dados estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato: PROJECT_ID:DATASET.

   Cuidado: quando você aplica o arquivo JSON que contém os controles de acesso, os controles de acesso atuais são substituídos.

     bq update 
   
         --source PATH_TO_FILE 
   
         PROJECT_ID:DATASET
     

5. Para verificar as alterações no controle de acesso, use o comando show sem gravar as informações em um arquivo:

   bq show --format=prettyjson PROJECT_ID:DATASET

API

Chame o método datasets.patch e use a propriedade access no recurso Dataset para atualizar os controles de acesso.

Como datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch para atualizar os controles de acesso.

Go

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

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

Defina a nova lista de acesso removendo a entrada da lista atual com o tipo DatasetMetadataToUpdate . Em seguida, chame a função dataset.Update() para atualizar a propriedade.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// revokeAccessToDataset creates a new ACL removing the dataset access to "[e-mail]" entity
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func revokeAccessToDataset(w io.Writer, projectID, datasetID, entity string) error {
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// entity := "[e-mail]"

	ctx := context.Background()

	// Create BigQuery client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get dataset handler
	dataset := client.Dataset(datasetID)

	// Get dataset metadata
	meta, err := dataset.Metadata(ctx)
	if err != nil {
		return err
	}

	// Create new access entry list by copying the existing and omiting the access entry entity value
	var newAccessList []*bigquery.AccessEntry
	for _, entry := range meta.Access {
		if entry.Entity != entity {
			newAccessList = append(newAccessList, entry)
		}
	}

	// Only proceed with update if something in the access list was removed.
	// Additionally, we use the ETag from the initial metadata to ensure no
	// other changes were made to the access list in the interim.
	if len(newAccessList) < len(meta.Access) {
		update := bigquery.DatasetMetadataToUpdate{
			Access: newAccessList,
		}
		meta, err = dataset.Update(ctx, update, meta.ETag)
		if err != nil {
			return err
		}
	} else {
		return fmt.Errorf("any access entry was revoked")
	}

	fmt.Fprintf(w, "Details for Access entries in dataset %v.\n", datasetID)

	for _, access := range meta.Access {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", access.Role)
		fmt.Fprintf(w, "Entity: %v\n", access.Entity)
	}

	return nil
}

Java

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

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

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Entity;
import com.google.cloud.bigquery.Acl.Group;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import java.util.List;

public class RevokeDatasetAccess {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project and dataset from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Group to remove from the ACL
    String entityEmail = "[e-mail]";

    revokeDatasetAccess(projectId, datasetName, entityEmail);
  }

  public static void revokeDatasetAccess(String projectId, String datasetName, String entityEmail) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create datasetId with the projectId and the datasetName.
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // Create a new Entity with the corresponding type and email
      // "[e-mail]"
      // For more information on the types of Entities available see:
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity
      // and
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl.Entity.Type
      Entity entity = new Group(entityEmail);

      // To revoke access to a dataset, remove elements from the Acl list.
      // Find more information about ACL and the Acl Class here:
      // https://cloud.google.com/storage/docs/access-control/lists
      // https://cloud.google.com/java/docs/reference/google-cloud-bigquery/latest/com.google.cloud.bigquery.Acl
      // Remove the entity from the ACLs list.
      List<Acl> acls =
          dataset.getAcl().stream().filter(acl -> !acl.getEntity().equals(entity)).toList();

      // Update the ACLs by setting the new list.
      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("ACLs of \"" + datasetName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("ACLs were not updated \n" + e.toString());
    }
  }
}

Node.js

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

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

Atualize a lista de acesso ao conjunto de dados removendo a entrada especificada da lista atual usando o método Dataset#get() para recuperar os metadados atuais. Modifique a propriedade de acesso para excluir a entidade desejada e chame a função Dataset#setMetadata() para aplicar a lista de acesso atualizada.

/**
 * TODO(developer): Update and un-comment below lines
 */

// const datasetId = "my_project_id.my_dataset"

// ID of the user or group from whom you are revoking access.
// const entityId = "[e-mail]"

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const bigquery = new BigQuery();

async function revokeDatasetAccess() {
  const [dataset] = await bigquery.dataset(datasetId).get();

  // To revoke access to a dataset, remove elements from the access list.
  //
  // See the BigQuery client library documentation for more details on access entries:
  // https://cloud.google.com/nodejs/docs/reference/bigquery/latest

  // Filter access entries to exclude entries matching the specified entity_id
  // and assign a new list back to the access list.
  dataset.metadata.access = dataset.metadata.access.filter(entry => {
    return !(
      entry.entity_id === entityId ||
      entry.userByEmail === entityId ||
      entry.groupByEmail === entityId
    );
  });

  // Update will only succeed if the dataset
  // has not been modified externally since retrieval.
  //
  // See the BigQuery client library documentation for more details on metadata updates:
  // https://cloud.google.com/bigquery/docs/updating-datasets

  // Update just the 'access entries' property of the dataset.
  await dataset.setMetadata(dataset.metadata);

  console.log(`Revoked access to '${entityId}' from '${datasetId}'.`);
}

Python

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

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

Defina a propriedade dataset.access_entries com os controles de acesso de um conjunto de dados. Em seguida, chame a função client.update_dataset() para atualizar a propriedade.

from google.cloud import bigquery
from google.api_core.exceptions import PreconditionFailed

# TODO(developer): Update and uncomment the lines below.

# ID of the dataset to revoke access to.
# dataset_id = "my-project.my_dataset"

# ID of the user or group from whom you are revoking access.
# Alternatively, the JSON REST API representation of the entity,
# such as a view's table reference.
# entity_id = "[e-mail]"

# Instantiate a client.
client = bigquery.Client()

# Get a reference to the dataset.
dataset = client.get_dataset(dataset_id)

# To revoke access to a dataset, remove elements from the AccessEntry list.
#
# See the BigQuery client library documentation for more details on `access_entries`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.dataset.Dataset#google_cloud_bigquery_dataset_Dataset_access_entries

# Filter `access_entries` to exclude entries matching the specified entity_id
# and assign a new list back to the AccessEntry list.
dataset.access_entries = [
    entry for entry in dataset.access_entries
    if entry.entity_id != entity_id
]

# Update will only succeed if the dataset
# has not been modified externally since retrieval.
#
# See the BigQuery client library documentation for more details on `update_dataset`:
# https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client#google_cloud_bigquery_client_Client_update_dataset
try:
    # Update just the `access_entries` property of the dataset.
    dataset = client.update_dataset(
        dataset,
        ["access_entries"],
    )

    # Notify user that the API call was successful.
    full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
    print(f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'")
except PreconditionFailed:  # A read-modify-write error.
    print(
        f"Dataset '{dataset.dataset_id}' was modified remotely before this update. "
        "Fetch the latest version and retry."
    )

Trabalhar com controles de acesso a tabelas e visualizações

As visualizações são tratadas como recursos de tabela no BigQuery. É possível conceder acesso a uma tabela ou visualização atribuindo a um principal do IAM um papel predefinido ou personalizado que determina o que o principal pode fazer com a tabela ou visualização. Isso também é conhecido como anexar uma política de permissão a um recurso. Depois de conceder acesso, é possível conferir os controles de acesso da tabela ou visualização e revogar o acesso a elas.

Permitir acesso a uma tabela ou visualização

Para um controle de acesso detalhado, é possível conceder um papel predefinido ou personalizado do IAM em uma tabela ou visualização específica. A tabela ou visualização também herda os controles de acesso especificados no nível do conjunto de dados e acima. Por exemplo, se você conceder a um principal o papel de proprietário de dados do BigQuery em um conjunto de dados, esse principal também terá permissões de proprietário de dados do BigQuery nas tabelas e visualizações do conjunto de dados.

Para conceder acesso a uma tabela ou visualização, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione uma tabela ou visualização para compartilhar.

3. Clique em Compartilhar.

4. Clique em adicionar conta principal.

5. No campo Novos principais, digite um principal..

6. Na lista Selecionar papel, escolha uma função predefinida ou personalizada..

7. Clique em Save.

8. Para retornar à tabela ou aos detalhes da visualização, clique em Fechar.

SQL

Para conceder aos principais acesso a tabelas ou visualizações, use a instrução DCL GRANT:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   GRANT `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   TO "USER_LIST"

   Substitua:

   • ROLE_LIST: um papel ou uma lista de papéis separados por vírgulas que você queira conceder.

   • RESOURCE_TYPE: o tipo de recurso ao qual o papel é aplicado.

     Os valores aceitos incluem TABLE, VIEW, MATERIALIZED VIEW e EXTERNAL TABLE.

   • RESOURCE_NAME: o nome do recurso em que você quer conceder a permissão.

   • USER_LIST: uma lista separada por vírgulas de usuários a que o papel é concedido.

     Para ver uma lista de formatos válidos, consulte user_list.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

O exemplo a seguir concede o papel de Leitor de dados do BigQuery em myTable:

GRANT `roles/bigquery.dataViewer`
ON TABLE `myProject`.myDataset.myTable
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para conceder acesso a uma tabela ou visualização, use o comando bq add-iam-policy-binding:

   bq add-iam-policy-binding --member=MEMBER_TYPE:MEMBER --role=ROLE
     --table=true RESOURCE

   Substitua:

   • MEMBER_TYPE: o tipo de membro, como user, group, serviceAccount ou domain.
   • MEMBER: o endereço de e-mail ou o nome de domínio do membro.
   • ROLE: o papel que você quer conceder ao membro.
   • RESOURCE: o nome da tabela ou visualização com a política que você quer atualizar.

Terraform

Use os recursos google_bigquery_table_iam para atualizar o acesso a uma tabela.

Importante: os diferentes recursos fornecidos por google_bigquery_table_iam podem entrar em conflito. Recomendamos que você leia a documentação google_bigquery_table_iam com atenção antes de fazer alterações no controle de acesso usando o Terraform.

Definir a política de acesso para uma tabela

O exemplo a seguir mostra como usar o recurso google_bigquery_table_iam_policy para definir a política do IAM para a tabela mytable. Isso substitui qualquer política existente já anexada à tabela:

# This file sets the IAM policy for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:[e-mail]",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "table_iam_policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

Definir a assinatura de uma função para uma tabela

O exemplo a seguir mostra como usar o recurso google_bigquery_table_iam_binding para definir a associação em um determinado papel para a tabela mytable. Isso substitui qualquer associação existente nesse papel. Outros papéis na política do IAM para a tabela são preservados.

# This file sets membership in an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_binding" "table_iam_binding" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataOwner"

  members = [
    "group:[e-mail]",
  ]
}

Definir associação de papel para um único principal

O exemplo a seguir mostra como usar o recurso google_bigquery_table_iam_member para atualizar a política do IAM para a tabela mytable a fim de conceder um papel a um só principal. A atualização dessa política do IAM não afeta o acesso de outros principais que receberam esse papel no conjunto de dados.

# This file adds a member to an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_member" "table_iam_member" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataEditor"
  member     = "serviceAccount:[e-mail]"
}

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu Google Cloud projeto para conferir os resultados. No console Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu Google Cloud projeto.

API

1. Para recuperar a política atual, chame o método tables.getIamPolicy.

2. Edite a política para adicionar membros ou controles de acesso, ou ambos. Quanto ao formato necessário à política, consulte o tópico de referência Políticas.

   Cuidado: antes de definir a política, sempre recupere a política atual para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.
   
   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor etag é o número da versão da política.

3. Chame tables.setIamPolicy para gravar a política atualizada.

   Observação: vinculações vazias sem membros não são permitidas e resultarão em erro.

Go

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

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

Chame a função IAM().SetPolicy() do recurso para salvar as mudanças na política de acesso de uma tabela ou visualização.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"cloud.google.com/go/iam"
)

// grantAccessToResource creates a new ACL conceding the VIEWER role to the group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func grantAccessToResource(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// resourceID := "myresource"

	ctx := context.Background()

	// Create new client
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource policy.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Find more details about IAM Roles here:
	// https://pkg.go.dev/cloud.google.com/go/iam#RoleName
	entityID := "[e-mail]"
	roleType := iam.Viewer

	// Add new policy.
	policy.Add(fmt.Sprintf("group:%s", entityID), roleType)

	// Update resource's policy.
	err = client.Dataset(datasetID).Table(resourceID).IAM().SetPolicy(ctx, policy)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Get resource policy again expecting the update.
	policy, err = client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

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

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;

public class GrantAccessToTableOrView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_TABLE_NAME";
    // Role to add to the policy access
    Role role = Role.of("roles/bigquery.dataViewer");
    // Identity to add to the policy access
    Identity identity = Identity.user("[e-mail]");
    grantAccessToTableOrView(projectId, datasetName, resourceName, role, identity);
  }

  public static void grantAccessToTableOrView(
      String projectId, String datasetName, String resourceName, Role role, Identity identity) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Add new user identity to current IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);
      policy = policy.toBuilder().addIdentity(role, identity).build();

      // Update the IAM policy by setting the new one.
      bigquery.setIamPolicy(tableId, policy);

      System.out.println("IAM policy of resource \"" + resourceName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("IAM policy was not updated. \n" + e.toString());
    }
  }
}

Node.js

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

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

Chame a função Table#getIamPolicy() para recuperar a política atual do IAM de uma tabela ou visualização, modifique a política adicionando novas vinculações e use a função Table#setIamPolicy() para salvar as mudanças na política de acesso.

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID";
// const datasetId = "YOUR_DATASET_ID";
// const tableId = "YOUR_TABLE_ID";
// const principalId = "YOUR_PRINCIPAL_ID";
// const role = "YOUR_ROLE";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function grantAccessToTableOrView() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(tableId);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings array.
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // To grant access to a table or view
  // add bindings to the Table or View policy.
  //
  // Find more details about Policy and Binding objects here:
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Binding
  const binding = {
    role,
    members: [principalId],
  };
  policy.bindings.push(binding);

  // Set the IAM access policy with updated bindings.
  await table.setIamPolicy(policy);

  // Show a success message.
  console.log(
    `Role '${role}' granted for principal '${principalId}' on resource '${datasetId}.${tableId}'.`
  );
}

await grantAccessToTableOrView();

Python

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

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

Chame a função client.set_iam_policy() para salvar as mudanças na política de acesso de uma tabela ou visualização.

from google.cloud import bigquery

# TODO(developer): Update and uncomment the lines below.

# Google Cloud Platform project.
# project_id = "my_project_id"

# Dataset where the table or view is.
# dataset_id = "my_dataset"

# Table or view name to get the access policy.
# resource_name = "my_table"

# Principal to grant access to a table or view.
# For more information about principal identifiers see:
# https://cloud.google.com/iam/docs/principal-identifiers
# principal_id = "user:[e-mail]"

# Role to grant to the principal.
# For more information about BigQuery roles see:
# https://cloud.google.com/bigquery/docs/access-control
# role = "roles/bigquery.dataViewer"

# Instantiate a client.
client = bigquery.Client()

# Get the full table or view name.
full_resource_name = f"{project_id}.{dataset_id}.{resource_name}"

# Get the IAM access policy for the table or view.
policy = client.get_iam_policy(full_resource_name)

# To grant access to a table or view, add bindings to the IAM policy.
#
# Find more details about Policy and Binding objects here:
# https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy
# https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Binding
binding = {
    "role": role,
    "members": [principal_id, ],
}
policy.bindings.append(binding)

# Set the IAM access policy with updated bindings.
updated_policy = client.set_iam_policy(full_resource_name, policy)

# Show a success message.
print(
    f"Role '{role}' granted for principal '{principal_id}'"
    f" on resource '{full_resource_name}'."
)

Papéis predefinidos que concedem acesso a tabelas e visualizações

As visualizações são tratadas como recursos de tabela no BigQuery. Para controle de acesso refinado, é possível conceder um papel predefinido ou personalizado do IAM em uma tabela ou visualização específica. A tabela ou visualização também herda os controles de acesso especificados no nível do conjunto de dados e acima. Por exemplo, se você conceder a um principal o papel de proprietário de dados do BigQuery em um conjunto de dados, esse principal também terá permissões de proprietário de dados nas tabelas e visualizações do conjunto de dados.

Os seguintes papéis predefinidos do IAM têm permissões em tabelas ou visualizações.

Atenção: embora seja possível conceder permissões de administrador do BigQuery ou do BigQuery Studio a uma tabela ou visualização, não conceda esses papéis no nível da tabela ou da visualização. O proprietário de dados do BigQuery também concede todas as permissões para tabelas e visualizações e é um papel menos privilegiado. Normalmente, os administradores do BigQuery e do BigQuery Studio recebem permissão no nível do projeto.

Papel	Descrição
Proprietário de dados do BigQuery (roles/bigquery.dataOwner)	Quando concedido em uma tabela ou visualização, esse papel concede as seguintes permissões: Todas as permissões para a tabela ou visualização. Todas as permissões para políticas de acesso a linhas, exceto a permissão para substituir restrições de viagem no tempo. Definir categorias e políticas de dados no nível da coluna. Observação:quando concedida no nível do conjunto de dados, os proprietários de dados também podem criar e listar tabelas no conjunto de dados.
Editor de dados do BigQuery (roles/bigquery.dataEditor)	Quando concedido em uma tabela ou visualização, esse papel concede as seguintes permissões: Acessar e atualizar metadados, acessar controles de acesso e excluir a tabela ou visualização. Receber (consultar), exportar, replicar e atualizar dados de tabelas. Criar, atualizar e excluir índices. Criar e restaurar snapshots. Observação:quando concedido no nível do conjunto de dados, os editores de dados também podem criar e listar tabelas no conjunto de dados.
Leitor de dados do BigQuery (roles/bigquery.dataViewer)	Quando concedido em uma tabela ou visualização, esse papel concede as seguintes permissões: Receba metadados e controles de acesso para a tabela ou visualização. Receber (consultar), exportar e replicar dados de tabelas. Criar snapshots. Observação:quando concedida no nível do conjunto de dados, a função "Leitor de dados" também pode listar tabelas no conjunto de dados.
Leitor de metadados do BigQuery (roles/bigquery.metadataViewer)	Quando concedido em uma tabela ou visualização, esse papel concede as seguintes permissões: Receba metadados e controles de acesso para a tabela ou visualização. Observação:quando concedida no nível do conjunto de dados, a função "Leitor de metadados" também pode listar tabelas no conjunto de dados.

Permissões para tabelas e visualizações

As visualizações são tratadas como recursos de tabela no BigQuery. Todas as permissões no nível da tabela se aplicam às visualizações.

A maioria das permissões que começam com bigquery.tables se aplicam no nível da tabela. bigquery.tables.create e bigquery.tables.list não funcionam. Para criar e listar tabelas ou visualizações, as permissões bigquery.tables.create e bigquery.tables.list precisam ser concedidas a uma função em um contêiner principal: o conjunto de dados ou o projeto.

A tabela a seguir lista todas as permissões para tabelas e visualizações e o recurso de nível mais baixo a que elas podem ser concedidas.

Permissão	Recurso	Ação
bigquery.tables.create	Conjunto de dados	Crie novas tabelas no conjunto de dados.
bigquery.tables.createIndex	Tabela	Crie um índice de pesquisa na tabela.
bigquery.tables.deleteIndex	Tabela	Exclua um índice de pesquisa na tabela.
bigquery.tables.createSnapshot	Tabela	Crie um snapshot da tabela. A criação de um snapshot exige várias permissões adicionais no nível da tabela e do conjunto de dados. Para mais detalhes, consulte Permissões e papéis para criar snapshots de tabelas.
bigquery.tables.deleteSnapshot	Tabela	Exclui um snapshot da tabela.
bigquery.tables.delete	Tabela	Excluir uma tabela.
bigquery.tables.createTagBinding	Tabela	Cria vinculações de tags de recursos em um tabela.
bigquery.tables.deleteTagBinding	Tabela	Exclui vinculações de tags de recursos em uma tabela.
bigquery.tables.listTagBindings	Tabela	Lista as vinculações de tags de recurso em uma tabela.
bigquery.tables.listEffectiveTags	Tabela	Lista as tags efetivas (aplicadas e herdadas) da tabela.
bigquery.tables.export	Tabela	Exporte os dados da tabela. Para executar um job de exportação, também são necessárias as permissões bigquery.jobs.create.
bigquery.tables.get	Tabela	Recebe metadados de uma tabela.
bigquery.tables.getData	Tabela	Consulte os dados da tabela. Para executar um job de consulta, também são necessárias permissões bigquery.jobs.create.
bigquery.tables.getIamPolicy	Tabela	Recebe os controles de acesso da tabela.
bigquery.tables.list	Conjunto de dados	Listar todas as tabelas e metadados de tabelas no conjunto de dados.
bigquery.tables.replicateData	Tabela	Replicar os dados da tabela. Essa permissão é necessária para criar visualizações materializadas de réplicas.
bigquery.tables.restoreSnapshot	Tabela	Restaure um snapshot da tabela.
bigquery.tables.setCategory	Tabela	Defina tags de política no esquema da tabela.
bigquery.tables.setColumnDataPolicy	Tabela	Defina políticas de acesso no nível da coluna em uma tabela.
bigquery.tables.setIamPolicy	Tabela	Defina controles de acesso em uma tabela.
bigquery.tables.update	Tabela	Atualizar tabela. metadata. bigquery.tables.get também é necessário para atualizar os metadados da tabela no console.
bigquery.tables.updateData	Tabela	Atualizar dados de tabela.
bigquery.tables.updateIndex	Tabela	Atualize um índice de pesquisa na tabela.

Ver controles de acesso para uma tabela ou visualização

Para conferir os controles de acesso de uma tabela ou visualização, escolha uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e um conjunto de dados e selecione uma tabela ou visualização.

3. Clique em Compartilhar.

   Os controles de acesso de tabela ou visualização aparecem no painel Compartilhar.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para receber uma política de acesso atual e enviá-la para um arquivo local em JSON, use o comando bq get-iam-policy no Cloud Shell:

   bq get-iam-policy \
       --table=true \
       PROJECT_ID:DATASET.RESOURCE > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados
   • RESOURCE: o nome da tabela ou visualização com a política que você quer ver
   • PATH_TO_FILE: o caminho para o arquivo JSON na sua máquina local.

SQL

Prévia

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Consulte a visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES. As consultas para recuperar controles de acesso de uma tabela ou visualização precisam especificar object_schema e object_name.

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   SELECT
   COLUMN_LIST
   FROM
     PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
   WHERE
   object_schema = "DATASET" AND object_name = "TABLE";

   Substitua:

   • COLUMN_LIST: uma lista separada por vírgulas de colunas da visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES.
   • PROJECT_ID: ID do projeto;
   • REGION: um qualificador de região
   • DATASET: o nome de um conjunto de dados que contém a tabela ou a visualização.
   • TABLE: o nome da tabela ou visualização

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplo:

SELECT
object_name, privilege_type, grantee
FROM
my_project.`region-us`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES
WHERE
object_schema = "mydataset" AND object_name = "mytable";

+------------------+-----------------------------+--------------------------+
|   object_name    |  privilege_type             | grantee                  |
+------------------+-----------------------------+--------------------------+
| mytable          | roles/bigquery.dataEditor   | group:[e-mail]|
| mytable          | roles/bigquery.dataOwner    | user:[e-mail]|
+------------------+-----------------------------+--------------------------+

API

Para recuperar a política atual, chame o método tables.getIamPolicy.

Observação: para visualizações, use tables como o valor de resource nessa chamada de API.

Go

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

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

Chame a IAM().Policy() função do recurso. Em seguida, chame a função Roles() para receber a política de acesso de uma tabela ou visualização.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// viewTableOrViewAccessPolicies retrieves the ACL for the given resource
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func viewTableOrViewAccessPolicies(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "my-dataset-id"
	// resourceID := "my-resource-id"

	ctx := context.Background()

	// Create new client.
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource's policy access.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

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

import com.google.cloud.Policy;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;

public class GetTableOrViewAccessPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_RESOURCE_NAME";
    getTableOrViewAccessPolicy(projectId, datasetName, resourceName);
  }

  public static void getTableOrViewAccessPolicy(
      String projectId, String datasetName, String resourceName) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Get the table IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);

      // Show policy details.
      // Find more information about the Policy Class here:
      // https://cloud.google.com/java/docs/reference/google-cloud-core/latest/com.google.cloud.Policy
      System.out.println(
          "IAM policy info of resource \"" + resourceName + "\" retrieved succesfully");
      System.out.println();
      System.out.println("IAM policy info: " + policy.toString());
    } catch (BigQueryException e) {
      System.out.println("IAM policy info not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

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

Recupere a política do IAM para uma tabela ou visualização usando a função Table#getIamPolicy(). Os detalhes da política de acesso estão disponíveis no objeto de política retornado.

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID"
// const datasetId = "YOUR_DATASET_ID"
// const resourceName = "YOUR_RESOURCE_NAME";

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function viewTableOrViewAccessPolicy() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(resourceName);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings if they don't exist
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // Show policy details.
  // Find more details for the Policy object here:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Policy
  console.log(`Access Policy details for table or view '${resourceName}'.`);
  console.log(`Bindings: ${JSON.stringify(policy.bindings, null, 2)}`);
  console.log(`etag: ${policy.etag}`);
  console.log(`Version: ${policy.version}`);
}

Revogar acesso a uma tabela ou visualização

Para revogar o acesso a uma tabela ou visualização, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda o projeto e um conjunto de dados e selecione uma tabela ou visualização.

3. No painel de detalhes, clique em Compartilhar.

4. Na caixa de diálogo Compartilhar, expanda o principal cujo acesso você quer revogar.

5. Clique em Excluir.

6. Na caixa de diálogo Remover papel do principal?, clique em Remover.

7. Para retornar à tabela ou aos detalhes da visualização, clique em Fechar.

Observação: se não for possível revogar o acesso, o principal poderá ter herdado o acesso de um nível superior na hierarquia de recursos.

SQL

Para remover o acesso de tabelas ou visualizações dos principais, use a instrução DCL REVOKE:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   REVOKE `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   FROM "USER_LIST"

   Substitua:

   • ROLE_LIST: um papel ou uma lista de papéis separados por vírgulas que você queira revogar

   • RESOURCE_TYPE: o tipo de recurso do qual o papel é revogado.

     Os valores aceitos incluem TABLE, VIEW, MATERIALIZED VIEW e EXTERNAL TABLE.

   • RESOURCE_NAME: o nome do recurso em que você quer revogar a permissão.

   • USER_LIST: uma lista separada por vírgulas de usuários que terão os papéis revogados.

     Para ver uma lista de formatos válidos, consulte user_list.

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

O exemplo a seguir revoga o papel de proprietário de dados do BigQuery em myTable:

REVOKE `roles/bigquery.dataOwner`
ON TABLE `myProject`.myDataset.myTable
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para revogar o acesso a uma tabela ou visualização, use o comando bq remove-iam-policy-binding:

   bq remove-iam-policy-binding --member=MEMBER_TYPE:MEMBER --role=ROLE
   --table=true RESOURCE

   Substitua:

   • MEMBER_TYPE: o tipo de membro, como user, group, serviceAccount ou domain
   • MEMBER: o endereço de e-mail ou o nome de domínio do membro.
   • ROLE: o papel que você quer revogar do membro
   • RESOURCE: o nome da tabela ou visualização com a política que você quer atualizar

API

1. Para recuperar a política atual, chame o método tables.getIamPolicy.

2. Edite a política para remover membros ou vinculações, ou ambos. Quanto ao formato necessário à política, consulte o tópico de referência Políticas.

   Cuidado: ao definir a política, sempre recupere a política atual como primeira etapa para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.
   
   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor etag é o número da versão da política.

3. Chame tables.setIamPolicy para gravar a política atualizada.

Observação: vinculações vazias sem membros não são permitidas e resultam em um erro.

Go

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

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

Chame a função policy.Remove() para remover o acesso. Em seguida, chame a função IAM().SetPolicy() para salvar as mudanças na política de acesso de uma tabela ou visualização.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"cloud.google.com/go/iam"
)

// revokeTableOrViewAccessPolicies creates a new ACL removing the VIEWER role to group "[e-mail]"
// For more information on the types of ACLs available see:
// https://cloud.google.com/storage/docs/access-control/lists
func revokeTableOrViewAccessPolicies(w io.Writer, projectID, datasetID, resourceID string) error {
	// Resource can be a table or a view
	//
	// TODO(developer): uncomment and update the following lines:
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// resourceID := "myresource"

	ctx := context.Background()

	// Create new client
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Get resource policy.
	policy, err := client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Find more details about IAM Roles here:
	// https://pkg.go.dev/cloud.google.com/go/iam#RoleName
	entityID := "[e-mail]"
	roleType := iam.Viewer

	// Revoke policy access.
	policy.Remove(fmt.Sprintf("group:%s", entityID), roleType)

	// Update resource's policy.
	err = client.Dataset(datasetID).Table(resourceID).IAM().SetPolicy(ctx, policy)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	// Get resource policy again expecting the update.
	policy, err = client.Dataset(datasetID).Table(resourceID).IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("bigquery.Dataset.Table.IAM.Policy: %w", err)
	}

	fmt.Fprintf(w, "Details for Access entries in table or view %v.\n", resourceID)

	for _, role := range policy.Roles() {
		fmt.Fprintln(w)
		fmt.Fprintf(w, "Role: %s\n", role)
		fmt.Fprintf(w, "Entities: %v\n", policy.Members(role))
	}

	return nil
}

Java

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

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

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

public class RevokeAccessToTableOrView {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    // Project, dataset and resource (table or view) from which to get the access policy
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String resourceName = "MY_RESOURCE_NAME";
    // Role to remove from the access policy
    Role role = Role.of("roles/bigquery.dataViewer");
    // Identity to remove from the access policy
    Identity user = Identity.user("[e-mail]");
    revokeAccessToTableOrView(projectId, datasetName, resourceName, role, user);
  }

  public static void revokeAccessToTableOrView(
      String projectId, String datasetName, String resourceName, Role role, Identity identity) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create table identity given the projectId, the datasetName and the resourceName.
      TableId tableId = TableId.of(projectId, datasetName, resourceName);

      // Remove either identities or roles, or both from bindings and replace it in
      // the current IAM policy.
      Policy policy = bigquery.getIamPolicy(tableId);
      // Create a copy of an immutable map.
      Map<Role, Set<Identity>> bindings = new HashMap<>(policy.getBindings());

      // Remove all identities with a specific role.
      bindings.remove(role);
      // Update bindings.
      policy = policy.toBuilder().setBindings(bindings).build();

      // Remove one identity in all the existing roles.
      for (Role roleKey : bindings.keySet()) {
        if (bindings.get(roleKey).contains(identity)) {
          // Create a copy of an immutable set if the identity is present in the role.
          Set<Identity> identities = new HashSet<>(bindings.get(roleKey));
          // Remove identity.
          identities.remove(identity);
          bindings.put(roleKey, identities);
          if (bindings.get(roleKey).isEmpty()) {
            // Remove the role if it has no identities.
            bindings.remove(roleKey);
          }
        }
      }
      // Update bindings.
      policy = policy.toBuilder().setBindings(bindings).build();

      // Update the IAM policy by setting the new one.
      bigquery.setIamPolicy(tableId, policy);

      System.out.println("IAM policy of resource \"" + resourceName + "\" updated successfully");
    } catch (BigQueryException e) {
      System.out.println("IAM policy was not updated. \n" + e.toString());
    }
  }
}

Node.js

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

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

Recupere a política do IAM atual para uma tabela ou visualização usando o método Table#getIamPolicy(). Modifique a política para remover o papel ou principal desejado e aplique a política atualizada usando o método Table#setIamPolicy().

/**
 * TODO(developer): Update and un-comment below lines
 */
// const projectId = "YOUR_PROJECT_ID"
// const datasetId = "YOUR_DATASET_ID"
// const tableId = "YOUR_TABLE_ID"
// const roleToRemove = "YOUR_ROLE"
// const principalToRemove = "YOUR_PRINCIPAL_ID"

const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate a client.
const client = new BigQuery();

async function revokeAccessToTableOrView() {
  const dataset = client.dataset(datasetId);
  const table = dataset.table(tableId);

  // Get the IAM access policy for the table or view.
  const [policy] = await table.getIamPolicy();

  // Initialize bindings array.
  if (!policy.bindings) {
    policy.bindings = [];
  }

  // To revoke access to a table or view,
  // remove bindings from the Table or View policy.
  //
  // Find more details about Policy objects here:
  // https://cloud.google.com/security-command-center/docs/reference/rest/Shared.Types/Policy

  if (principalToRemove) {
    // Create a copy of bindings for modifications.
    const bindings = [...policy.bindings];

    // Filter out the principal from each binding.
    for (const binding of bindings) {
      if (binding.members) {
        binding.members = binding.members.filter(
          m => m !== principalToRemove
        );
      }
    }

    // Filter out bindings with empty members.
    policy.bindings = bindings.filter(
      binding => binding.members && binding.members.length > 0
    );
  }

  if (roleToRemove) {
    // Filter out all bindings with the roleToRemove
    // and assign a new list back to the policy bindings.
    policy.bindings = policy.bindings.filter(b => b.role !== roleToRemove);
  }

  // Set the IAM access policy with updated bindings.
  await table.setIamPolicy(policy);

  // Both role and principal are removed
  if (roleToRemove !== null && principalToRemove !== null) {
    console.log(
      `Role '${roleToRemove}' revoked for principal '${principalToRemove}' on resource '${datasetId}.${tableId}'.`
    );
  }

  // Only role is removed
  if (roleToRemove !== null && principalToRemove === null) {
    console.log(
      `Role '${roleToRemove}' revoked for all principals on resource '${datasetId}.${tableId}'.`
    );
  }

  // Only principal is removed
  if (roleToRemove === null && principalToRemove !== null) {
    console.log(
      `Access revoked for principal '${principalToRemove}' on resource '${datasetId}.${tableId}'.`
    );
  }

  // No changes were made
  if (roleToRemove === null && principalToRemove === null) {
    console.log(
      `No changes made to access policy for '${datasetId}.${tableId}'.`
    );
  }
}

Trabalhar com controles de acesso para rotinas

Prévia

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Para enviar feedback ou solicitar suporte para esse recurso, envie um e-mail para [e-mail].

É possível conceder acesso a uma rotina atribuindo a um principal do IAM](/iam/docs/principal-identifiers#allow) um papel predefinido ou personalizado que determina o que o principal pode fazer com a rotina. Isso também é conhecido como anexar uma política de permissão a um recurso. Depois de conceder acesso, você pode conferir os controles de acesso da rotina e revogar o acesso a ela.

Conceder acesso a uma rotina

Para um controle de acesso detalhado, conceda um papel predefinido ou personalizado do IAM em uma rotina específica. A rotina também herda controles de acesso especificados no nível do conjunto de dados e acima. Por exemplo, se você conceder a um principal o papel de proprietário de dados do BigQuery em um conjunto de dados, ele também terá permissões de proprietário de dados nas rotinas do conjunto.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda o projeto e o conjunto de dados, depois Rotinas e selecione uma rotina.

3. Clique em Compartilhar.

4. Clique em Adicionar participantes.

5. No campo Novos membros, insira um principal.

6. Na lista Selecionar papel, escolha uma função predefinida ou personalizada..

7. Clique em Salvar.

8. Para voltar às informações da rotina, clique em Concluído.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para gravar as informações da rotina atual (incluindo controles de acesso) em um arquivo JSON, use o comando bq get-iam-policy:

   bq get-iam-policy \
       PROJECT_ID:DATASET.ROUTINE \
       > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto;
   • DATASET: o nome do conjunto de dados que contém a rotina que você quer atualizar
   • ROUTINE: o nome do recurso a ser atualizado.
   • PATH_TO_FILE: o caminho para o arquivo JSON em sua máquina local.
   Cuidado: ao definir a política, sempre recupere a política atual como primeira etapa para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.
   
   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor etag é o número da versão da política.

3. Faça suas alterações na seção bindings do arquivo JSON. Uma vinculação associa um ou mais principais a um único role. Os principais podem ser contas de usuário, contas de serviço, Grupos do Google e domínios. Por exemplo, a seção bindings do arquivo JSON de uma rotina teria a seguinte aparência:

   {
     "bindings": [
       {
         "role": "roles/bigquery.dataViewer",
         "members": [
           "user:[e-mail]",
           "group:[e-mail]",
           "domain:example.com",
         ]
       },
     ],
     "etag": "BwWWja0YfJA=",
     "version": 1
   }

   Observação: vinculações vazias sem membros não são permitidas e resultam em erro.

4. Para atualizar sua política de acesso, use o comando bq set-iam-policy:

   bq set-iam-policy PROJECT_ID:DATASET.ROUTINE PATH_TO_FILE

5. Para verificar as alterações no controle de acesso, insira o comando bq get-iam-policy novamente sem gravar as informações em um arquivo:

   bq get-iam-policy --format=prettyjson \\
       PROJECT_ID:DATASET.ROUTINE

API

1. Para recuperar a política atual, chame o método routines.getIamPolicy.

2. Edite a política para adicionar principais, vinculações ou ambos. Quanto ao formato necessário à política, consulte o tópico de referência Políticas.

   Cuidado: antes de definir a política, sempre recupere a política atual para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.
   
   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor etag é o número da versão da política.

3. Chame routines.setIamPolicy para gravar a política atualizada.

Observação :vinculações vazias sem membros não são permitidas e resultarão em erro.

Papéis predefinidos que concedem acesso a rotinas

Para um controle de acesso detalhado, conceda um papel predefinido ou personalizado do IAM em uma rotina específica. A rotina também herda controles de acesso especificados no nível do conjunto de dados e acima. Por exemplo, se você conceder a um principal o papel de proprietário de dados em um conjunto de dados, ele também terá permissões de proprietário de dados nas rotinas do conjunto por herança.

Os seguintes papéis predefinidos do IAM têm permissões em rotinas.

Atenção: embora seja possível conceder permissões de administrador do BigQuery ou do BigQuery Studio em uma rotina, não conceda esses papéis no nível da rotina. O editor de dados do BigQuery também concede todas as permissões para a rotina e é uma função menos privilegiada. Normalmente, os administradores do BigQuery e do BigQuery Studio recebem permissão no nível do projeto.

Papel	Descrição
Proprietário de dados do BigQuery (roles/bigquery.dataOwner)	Quando concedido em uma rotina, esse papel concede as seguintes permissões: Todas as permissões para a rotina. Não conceda o papel de proprietário de dados no nível da rotina. O Editor de dados também concede todas as permissões para a rotina e é um papel com menos privilégios. Observação:quando concedida no nível do conjunto de dados, os proprietários de dados podem criar rotinas e listar rotinas no conjunto de dados.
Editor de dados do BigQuery (roles/bigquery.dataEditor)	Quando concedido em uma rotina, esse papel concede as seguintes permissões: Todas as permissões para a rotina. Observação:quando concedido no nível do conjunto de dados, os editores de dados podem criar rotinas e listar rotinas no conjunto de dados.
Leitor de dados do BigQuery (roles/bigquery.dataViewer)	Quando concedido em uma rotina, esse papel concede as seguintes permissões: Em uma consulta, faça referência a uma rotina criada por outra pessoa. Observação:quando concedido no nível do conjunto de dados, os leitores de dados também podem listar rotinas no conjunto de dados.
Leitor de metadados do BigQuery (roles/bigquery.metadataViewer)	Quando concedido em uma rotina, esse papel concede as seguintes permissões: Em uma consulta, faça referência a uma rotina criada por outra pessoa. Observação:quando concedido no nível do conjunto de dados, os leitores de metadados também podem listar rotinas no conjunto de dados.

Permissões para rotinas

A maioria das permissões que começam com bigquery.routines se aplicam no nível da rotina. bigquery.routines.create e bigquery.routines.list não funcionam. Para criar e listar rotinas, as permissões bigquery.routines.create e bigquery.routines.list precisam ser concedidas a um papel no contêiner pai, ou seja, o conjunto de dados.

A tabela a seguir lista todas as permissões para rotinas e o recurso de menor nível a que elas podem ser concedidas.

Permissão	Recurso	Descrição
bigquery.routines.create	Conjunto de dados	Crie uma rotina no conjunto de dados. Essa permissão também exige bigquery.jobs.create para executar um job de consulta que contenha uma instrução CREATE FUNCTION.
bigquery.routines.delete	Rotina	Excluir uma rotina.
bigquery.routines.get	Rotina	Referenciar uma rotina criada por outra pessoa. Essa permissão também exige bigquery.jobs.create para executar um job de consulta que referencia a rotina. Além disso, você precisa de permissão para acessar todos os recursos referenciados pela rotina, como tabelas ou visualizações.
bigquery.routines.list	Conjunto de dados	Listar rotinas no conjunto de dados e mostrar metadados para rotinas.
bigquery.routines.update	Rotina	Atualiza definições e metadados de rotina.
bigquery.routines.getIamPolicy	Rotina	Receba controles de acesso para a rotina.
bigquery.routines.setIamPolicy	Rotina	Defina controles de acesso para a rotina.

Ver os controles de acesso de uma rotina

Para conferir os controles de acesso de uma rotina, escolha uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda o projeto, o conjunto de dados e Rotinas. Em seguida, selecione uma rotina.

3. Clique em Compartilhar.

   Os controles de acesso da rotina aparecem no painel Compartilhar.

bq

O comando bq get-iam-policy não oferece suporte para visualização de controles de acesso em uma rotina.

SQL

A visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES não mostra controles de acesso para rotinas.

API

Para recuperar a política atual, chame o método routines.getIamPolicy.

Revogar o acesso a uma rotina

Para revogar o acesso a uma rotina, selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda o projeto, um conjunto de dados e Rotinas. Em seguida, selecione uma rotina.

3. No painel de detalhes, clique em Compartilhamento>Permissões.

4. Na caixa de diálogo Permissões de rotina, expanda o principal cujo acesso você quer revogar.

5. Clique em Remover principal.

6. Na caixa de diálogo Remover papel do principal?, clique em Remover.

7. Clique em Fechar.

Observação: se não for possível revogar o acesso, o principal poderá ter herdado o acesso de um nível superior na hierarquia de recursos. Para instruções sobre como editar o acesso principal, consulte Conceder ou revogar um único papel.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Para gravar as informações da rotina atual (incluindo controles de acesso) em um arquivo JSON, use o comando bq get-iam-policy:

   bq get-iam-policy --routine PROJECT_ID:DATASET.ROUTINE > PATH_TO_FILE

   Substitua:

   • PROJECT_ID: ID do projeto;
   • DATASET: o nome do conjunto de dados que contém a rotina que você quer atualizar
   • ROUTINE: o nome do recurso a ser atualizado.
   • PATH_TO_FILE: o caminho para o arquivo JSON em sua máquina local.
   Cuidado: ao definir a política, sempre recupere a política atual como primeira etapa para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.

   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor de etag é o número da versão da política.

3. Faça suas alterações na seção access do arquivo JSON. É possível remover qualquer uma das entradas specialGroup: projectOwners, projectWriters, projectReaders e allAuthenticatedUsers. Também é possível remover qualquer um dos seguintes itens: userByEmail, groupByEmail e domain.

   Por exemplo, a seção access do arquivo JSON de uma rotina teria a seguinte aparência:

   {
    "bindings": [
      {
        "role": "roles/bigquery.dataViewer",
        "members": [
          "user:[e-mail]",
          "group:[e-mail]",
          "domain:google.com",
        ]
      },
    ],
    "etag": "BwWWja0YfJA=",
    "version": 1
   }

   Observação: vinculações vazias sem membros não são permitidas e resultam em erro.

4. Para atualizar sua política de acesso, use o comando bq set-iam-policy:

   bq set-iam-policy --routine PROJECT_ID:DATASET.ROUTINE PATH_TO_FILE

5. Para verificar as mudanças no controle de acesso, use o comando get-iam-policy novamente sem gravar as informações em um arquivo:

   bq get-iam-policy --routine --format=prettyjson PROJECT_ID:DATASET.ROUTINE

API

1. Para recuperar a política atual, chame o método routines.getIamPolicy.

2. Edite a política para adicionar principais ou vinculações, ou ambos. Quanto ao formato necessário à política, consulte o tópico de referência Políticas.

   Cuidado: ao definir a política, sempre recupere a política atual como primeira etapa para receber o valor atual de etag. Seu arquivo de política atualizado precisa incluir o mesmo valor de etag que a política atual que você está substituindo, ou a atualização falhará. Esse recurso impede que atualizações simultâneas aconteçam.
   
   No arquivo de política, o valor de version continua sendo 1. Esse número se refere à versão do esquema da política do IAM, não à versão da política. O valor etag é o número da versão da política.

Ver controles de acesso herdados para um recurso

É possível examinar os papéis herdados do IAM para um recurso usando a UI da Web do BigQuery. Você precisa das permissões adequadas para ver a herança no console. Para examinar a herança de um conjunto de dados, tabela, visualização ou rotina:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, selecione o conjunto de dados ou expanda-o e selecione uma tabela, visualização ou rotina.

3. Para um conjunto de dados, clique em Compartilhamento. Para uma tabela, uma visualização ou uma rotina, clique em Compartilhar.

4. Verifique se a opção Mostrar funções herdadas na tabela está ativada.

   

5. Expanda uma função na tabela.

6. Na coluna Herança, o ícone hexagonal indica se o papel foi herdado de um recurso pai.

   

Negar acesso a um recurso

Prévia

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Observação: para enviar feedback ou fazer perguntas relacionadas a esta versão de pré-lançamento, entre em contato com [e-mail].

As políticas de negação do IAM permitem definir proteções no acesso aos recursos do BigQuery. É possível definir regras de negação para impedir que alguns principais usem determinadas permissões, seja qual for o papel que eles receberam.

Para informações sobre como criar, atualizar e excluir políticas de negação, consulte Negar acesso a recursos.

Casos especiais

Considere os seguintes cenários ao criar políticas de negação do IAM em algumas permissões do BigQuery:

• O acesso a recursos autorizados (visualizações, rotinas, conjuntos de dados ou procedimentos armazenados) permite criar, excluir ou manipular uma tabela, além de ler e modificar dados da tabela, mesmo que você não tenha permissão direta para realizar essas operações. Também é possível receber dados ou metadados do modelo e invocar outros procedimentos armazenados na tabela. Isso significa que os recursos autorizados têm as seguintes permissões:

  • bigquery.tables.get
  • bigquery.tables.list
  • bigquery.tables.getData
  • bigquery.tables.updateData
  • bigquery.tables.create
  • bigquery.tables.delete
  • bigquery.routines.get
  • bigquery.routines.list
  • bigquery.datasets.get
  • bigquery.models.getData
  • bigquery.models.getMetadata

  Para negar o acesso a esses recursos autorizados, adicione um dos seguintes valores ao campo deniedPrincipal ao criar a política de negação:

  Valor	Caso de uso
  principalSet://goog/public:all	Bloqueia todos os principais, incluindo recursos autorizados.
  principalSet://bigquery.googleapis.com/projects/PROJECT_NUMBER/*	Bloqueia todos os recursos autorizados do BigQuery no projeto especificado. PROJECT_NUMBER é um identificador exclusivo gerado automaticamente para seu projeto do tipo INT64.

• Para isentar determinados principais da política de negação, especifique-os no campo exceptionPrincipals da política. Por exemplo, exceptionPrincipals: "principalSet://bigquery.googleapis.com/projects/1234/*".

• O BigQuery armazena em cache os resultados da consulta de um proprietário de job por 24 horas, que pode acessar sem precisar da permissão bigquery.tables.getData na tabela que contém os dados. Portanto, adicionar uma política de negação do IAM à permissão bigquery.tables.getData não bloqueia o acesso aos resultados armazenados em cache para o proprietário do job até que o cache expire. Para bloquear o acesso do proprietário do job aos resultados em cache, crie uma política de negação separada na permissão bigquery.jobs.create.

• Para evitar o acesso não intencional a dados ao usar políticas de negação para bloquear operações de leitura de dados, recomendamos que você também revise e revogue todas as assinaturas atuais no conjunto de dados.

• Para criar uma política de negação do IAM para visualizar os controles de acesso ao conjunto de dados, negue as seguintes permissões:

  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy

• Para criar uma política de negação do IAM para atualizar os controles de acesso do conjunto de dados, negue as seguintes permissões:

  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy

A seguir

Saiba como usar o método projects.testIamPermissions para testar o acesso de usuários a um recurso.