Usar o IAM para controlar o acesso a recursos

Neste documento, descrevemos como ver a política de acesso atual de um recurso, como conceder acesso a um recurso e como para revogar o acesso a um recurso.

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

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 console do Google 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 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.

Ver a política de acesso de um recurso

As seções a seguir descrevem como visualizar as políticas de acesso de diferentes recursos.

Ver a política de acesso de 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. Clique em Compartilhamento > Permissões.

   As políticas de acesso ao 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 em sua máquina local.

API

Para conferir a política de acesso de um conjunto de dados, chame o método datasets.get com um recurso dataset definido.

A política está disponível na propriedade access do recurso dataset retornado.

Ver a política de acesso de uma tabela ou visualização

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

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

3. Clique em Compartilhar.

   As políticas 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 em sua máquina local.

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.

Permitir acesso a um recurso

As seções a seguir descrevem como conceder acesso a diferentes recursos.

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

Conceder 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 seu 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.

   Ir para 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 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 visualizador de dados no conjunto de dados 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 existente (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 sinalização --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 no seguinte 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. Recomendamos que você leia a documentação google_bigquery_dataset_iam com atenção antes de fazer alterações 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 do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud 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 projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU 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 projeto do Google Cloud.

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.

import (
	"context"
	"fmt"

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

// updateDatasetAccessControl demonstrates how the access control policy of a dataset
// can be amended by adding an additional entry corresponding to a specific user identity.
func updateDatasetAccessControl(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       bigquery.ReaderRole,
			EntityType: bigquery.UserEmailEntity,
			Entity:     "[e-mail]"},
		),
	}

	// Leverage the ETag for the update to assert there's been no modifications to the
	// dataset since the metadata was originally read.
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	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.Role;
import com.google.cloud.bigquery.Acl.User;
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 java.util.ArrayList;

public class UpdateDatasetAccess {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    // Create a new ACL granting the READER role to "[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(new User("[e-mail]"), Role.READER);

    updateDatasetAccess(datasetName, newEntry);
  }

  public static void updateDatasetAccess(String datasetName, Acl newEntry) {
    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();

      Dataset dataset = bigquery.getDataset(datasetName);

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

      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("Dataset Access Control updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset Access control was not updated \n" + e.toString());
    }
  }
}

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.

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom
# you are adding access. Alternatively, to the JSON REST API representation
# of the entity, such as a view's table reference.
entity_id = "[e-mail]"

from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Set entity_type to the type of entity you are granting access to.
# Common types include:
#
# * "userByEmail" -- A single user or service account. For example "[e-mail]"
# * "groupByEmail" -- A group of users. For example "[e-mail]"
# * "view" -- An authorized view. For example
#       {"projectId": "p", "datasetId": "d", "tableId": "v"}
#
# For a complete reference, see the REST API reference documentation:
# https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#Dataset.FIELDS.access
entity_type = EntityTypes.GROUP_BY_EMAIL

# TODO(developer): Set role to a one of the "Basic roles for datasets"
# described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
role = "READER"

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ["access_entries"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

Permitir acesso a uma tabela ou visualização

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para 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.

   Ir para 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 visualizador de dados na tabela 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 do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud 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 projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU 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 projeto do Google Cloud.

API

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

2. Edite a política para adicionar 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. Cuidado: vinculações vazias sem membros não são permitidas e resultam em erro.

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;

// Sample to create iam policy for table
public class CreateIamPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createIamPolicy(datasetName, tableName);
  }

  public static void createIamPolicy(String datasetName, String tableName) {
    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();

      TableId tableId = TableId.of(datasetName, tableName);

      Policy policy = bigquery.getIamPolicy(tableId);
      policy
          .toBuilder()
          .addIdentity(Role.of("roles/bigquery.dataViewer"), Identity.allUsers())
          .build();
      bigquery.setIamPolicy(tableId, policy);
      System.out.println("Iam policy created successfully");
    } catch (BigQueryException e) {
      System.out.println("Iam policy was not created. \n" + e.toString());
    }
  }
}

Python

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

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

from google.cloud import bigquery

bqclient = bigquery.Client()

policy = bqclient.get_iam_policy(
    your_table_id,  # e.g. "project.dataset.table"
)

analyst_email = "[e-mail]"
binding = {
    "role": "roles/bigquery.dataViewer",
    "members": {f"group:{analyst_email}"},
}
policy.bindings.append(binding)

updated_policy = bqclient.set_iam_policy(
    your_table_id,  # e.g. "project.dataset.table"
    policy,
)

for binding in updated_policy.bindings:
    print(repr(binding))

Revogar acesso a um recurso

As seções a seguir descrevem como revogar o acesso a recursos diferentes.

Revogar 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 dessa maneira, o principal poderá herdar o acesso de um nível superior na hierarquia de recursos (em inglês). Para instruções sobre como editar o acesso principal, consulte Conceder ou revogar um único papel.

SQL

Para remover o acesso de principais dos conjuntos de dados, use a instrução DCL REVOKE:

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

   Ir para 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 administrador no conjunto de dados myDataset:

REVOKE `roles/bigquery.admin`
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 existente (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 sinalização --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 no seguinte 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 show novamente sem gravar as informações em um arquivo.

   bq show --format=prettyjson PROJECT_ID:DATASET

API

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

import (
	"context"
	"fmt"

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

// revokeDatasetAccess updates the access control on a dataset to remove all
// access entries that reference a specific entity.
func revokeDatasetAccess(projectID, datasetID, entity string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// entity := "[e-mail]"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	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,
		}
		if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
			return err
		}
	}
	return nil
}

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.

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom you are revoking access.
entity_id = "[e-mail]"

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
dataset.access_entries = [
    entry for entry in entries if entry.entity_id != entity_id
]

dataset = client.update_dataset(
    dataset,
    # Update just the `access_entries` property of the dataset.
    ["access_entries"],
)  # Make an API request.

full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
print(f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'")

Revogar acesso a uma tabela ou visualização

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda seu projeto 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 dessa maneira, o principal poderá herdar o acesso de um nível superior na hierarquia de recursos (em inglês). Para instruções sobre como editar o acesso principal, consulte Conceder ou revogar um único papel.

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.

   Ir para 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 administrador na tabela myTable:

REVOKE `roles/bigquery.admin`
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. Cuidado: vinculações vazias sem membros não são permitidas e resultam em erro.

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.Map;
import java.util.Set;

// Sample to update iam policy in table
public class UpdateIamPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    updateIamPolicy(datasetName, tableName);
  }

  public static void updateIamPolicy(String datasetName, String tableName) {
    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();

      TableId tableId = TableId.of(datasetName, tableName);

      Policy policy = bigquery.getIamPolicy(tableId);
      Map<Role, Set<Identity>> binding = new HashMap<>(policy.getBindings());
      binding.remove(Role.of("roles/bigquery.dataViewer"));

      policy.toBuilder().setBindings(binding).build();
      bigquery.setIamPolicy(tableId, policy);

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

Negar acesso a um recurso

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" 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. Para mais informações, consulte as descrições da fase 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 que você crie, exclua ou manipula uma tabela, além de ler e modificar os dados da tabela, mesmo que você não tenha permissão direta para realizar essas operações. Ele também pode receber dados ou metadados do modelo e invocar outros procedimentos armazenados na tabela. Esse recurso implica 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 esses principais no campo exceptionPrincipals da sua política de negação. 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 podem ser acessados 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 armazenados em cache, crie uma política de recusa 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 analise e revogue todas as assinaturas no conjunto de dados.

• Para criar uma política de negação do IAM para visualizar os controles de acesso a conjuntos 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 ao conjunto de dados, negue as seguintes permissões:

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