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 como conceder papéis, consulte Gerenciar acesso.

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 papéis personalizados 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 aplicar controles de acesso quando o conjunto de dados for criado, chame datasets.insert com um dataset resource definido. Para atualizar os controles de acesso, chame 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.

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 desta 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 gravar a tabela ou as informações de visualização atuais (incluindo controles de acesso) em um arquivo JSON, use o comando bq get-iam-policy:

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

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados que contém a tabela ou visualização que você quer atualizar.
   • TABLE_OR_VIEW: 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. (em inglês). 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 vincula um ou mais members, ou principais, a um único role. Os diretores podem ser contas de usuário, contas de serviço, Grupos do Google e domínios. Por exemplo, a seção bindings de um arquivo JSON de uma tabela ou visualização teria a seguinte aparência:

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

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

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

   bq set-iam-policy PROJECT_ID:DATASET.TABLE_OR_VIEW 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.TABLE_OR_VIEW
   

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 e/ou vinculações. 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.

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 gravar a tabela ou as informações de visualização atuais (incluindo controles de acesso) em um arquivo JSON, use o comando bq get-iam-policy:

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

   Substitua:

   • PROJECT_ID: ID do projeto
   • DATASET: o nome do conjunto de dados que contém a tabela ou visualização que você quer atualizar.
   • TABLE_OR_VIEW: 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 itens a seguir: userByEmail, groupByEmail e domain. Por exemplo, a seção access de um arquivo JSON de uma tabela ou visualização teria a seguinte 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"
     }
    ],
    ...
   }
   

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

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

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

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

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

API

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

2. Edite a política para adicionar membros e/ou vinculações. 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.