Como controlar o acesso a conjuntos de dados

Neste documento, descreveremos como controlar o acesso a conjuntos de dados no BigQuery.

Além disso, você também pode conferir os tópicos a seguir:

Controlar o acesso nos níveis da tabela e da visualização.
Controlar o acesso em um nível superior na hierarquia de recursos do IAM.

Visão geral

As permissões no nível do conjunto de dados determinam os usuários, grupos e contas de serviço que têm permissão para acessar as tabelas, visualizações e dados da tabela em um conjunto de dados específico. Por exemplo, se você conceder o papel de IAM bigquery.dataOwner a um usuário em um conjunto de dados específico, ele poderá criar, atualizar e excluir tabelas e visualizações no conjunto de dados.

É possível aplicar controles de acesso durante a criação do conjunto de dados chamando o método da API datasets.insert.

Não é possível aplicar controles de acesso durante a criação do conjunto de dados no Console do Cloud, na ferramenta de linha de comando bq ou nas instruções da linguagem de definição de dados (DDL).

É possível aplicar controles de acesso a um conjunto de dados depois que ele é criado das seguintes maneiras:

usando o Console do Cloud.
usando as instruções DCL GRANT e REVOKE.
use o comando bq update na ferramenta de linha de comando bq.
Chamada do método de API datasets.patch
usando bibliotecas de cliente.

Permissões e papéis obrigatórios

Esta seção descreve as Permissões de gerenciamento de identidade e acesso (IAM, na sigla em inglês) necessárias para controlar o acesso ao conjunto de dados e os papéis predefinidos do IAM que concedem essas permissões.

Permissões

Para controlar o acesso de um conjunto de dados, você precisa de todas estas permissões:

Permissão	Recurso
`bigquery.datasets.update`	O conjunto de dados cujo acesso você quer controlar.
`bigquery.datasets.get`	O conjunto de dados cujo acesso você quer controlar.

Para controlar o acesso de um conjunto de dados usando o Console do Google Cloud, você também precisa destas permissões:

Permissão	Recurso
`bigquery.datasets.getIamPolicy`	O conjunto de dados cujo acesso você quer controlar.
`bigquery.datasets.setIamPolicy`	O conjunto de dados cujo acesso você quer controlar.

Papéis

Para controlar o acesso de um conjunto de dados, é preciso ter no mínimo o seguinte papel:

Papel	Recurso
`roles/bigquery.dataOwner`	O conjunto de dados cujo acesso você quer controlar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como conceder acesso a um conjunto de dados

Para conceder acesso a um conjunto de dados, faça o seguinte:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Compartilhar conjunto de dados.
No painel Compartilhar conjunto de dados da guia Permissões do conjunto de dados, digite a entidade que você quer incluir no campo Adicionar membros. É possível adicionar qualquer uma das entidades a seguir:
- E-mail da Conta do Google: concede acesso ao conjunto de dados a uma conta individual do Google.
- Grupo do Google: concede acesso ao conjunto de dados a todos os membros de um grupo do Google.
- Domínio do Google Apps: concede acesso ao conjunto de dados a todos os usuários e grupos em um domínio do Google.
- Conta de serviço: concede acesso ao conjunto de dados a uma conta de serviço.
- Qualquer pessoa: insira allUsers para conceder acesso ao público em geral.
- Todas as Contas do Google: insira allAuthenticatedUsers para conceder acesso a qualquer usuário conectado a uma Conta do Google.
Em Selecionar um papel, clique em BigQuery e escolha um papel de IAM predefinido apropriado para os novos membros. Para mais informações sobre as permissões atribuídas a cada papel predefinido do BigQuery, consulte a seção Papéis da página de controle de acesso.
Clique em Concluído.

SQL

Use a seguinte instrução GRANT para conceder o papel Visualizador de dados (roles/bigquery.dataViewer) ao usuário joe@example.com no seu conjunto de dados.

     GRANT `roles/bigquery.dataViewer`
     ON SCHEMA DATASET
     TO "user:joe@example.com"

Substitua DATASET pelo nome do conjunto de dados em que o recurso está.

Saiba mais sobre a instrução DCL GRANT em Instruções da linguagem de controle de dados em SQL padrão.

bq

Use o comando show para gravar as informações atuais do conjunto de dados, incluindo controles de acesso, em um arquivo JSON. 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.
```
bq show \
--format=prettyjson \
project_id:dataset > path_to_file
```
Substitua:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados;
- path_to_file é o caminho do arquivo JSON na sua máquina local.
Exemplos:

Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está no projeto padrão.
```
  bq show --format=prettyjson mydataset > /tmp/mydataset.json
```
Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está em myotherproject.
```
  bq show --format=prettyjson \
  myotherproject:mydataset > /tmp/mydataset.json
```

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. É possível também adicionar ou modificar 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"
  }
 ],
 ...
}

Quando as edições estiverem concluídas, use o comando 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
```
Substitua:
- path_to_file é o caminho do arquivo JSON na sua máquina local.
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados;
Exemplos:

Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está no projeto padrão.
```
    bq update --source /tmp/mydataset.json mydataset
```
Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está em myotherproject.
```
    bq update --source /tmp/mydataset.json myotherproject:mydataset
```
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 dataset
```
ou
```
bq show --format=prettyjson project_id:dataset
```

API

Ligue para datasets.insertcom um recurso de conjunto de dados definido para aplicar controles de acesso quando o conjunto de dados for criado. 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.

Ver no GitHub Feedback

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:     "sample.bigquery.dev@gmail.com"},
		),
	}

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

Ver no GitHub Feedback

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 "sample.bigquery.dev@gmail.com"
    // 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("sample.bigquery.dev@gmail.com"), 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.

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.

Ver no GitHub Feedback

from google.cloud import bigquery

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

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

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

entry = bigquery.AccessEntry(
    role="READER",
    entity_type="userByEmail",
    entity_id="sample.bigquery.dev@gmail.com",
)

entries = list(dataset.access_entries)
entries.append(entry)
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)
)

Como revogar o acesso a um conjunto de dados

Para revogar o acesso a um conjunto de dados, faça o seguinte:

Console

No painel Explorer, expanda o projeto e selecione um conjunto de dados.
No painel de detalhes, clique em Compartilhar conjunto de dados.
No painel Compartilhar conjunto de dados da guia Permissões do conjunto de dados, expanda o papel cuja associação você quer alterar.
Clique em Excluir na conta de usuário que você quer remover.
Na caixa de diálogo Remover membro?, clique em Remover.
Clique em Concluído.

SQL

Use a seguinte instrução REVOKE para remover o papel Visualizador de dados (roles/bigquery.dataViewer) do usuário joe@example.com no seu conjunto de dados.

  REVOKE `roles/bigquery.dataViewer`
  ON SCHEMA DATASET
  FROM "user:joe@example.com"

Substitua DATASET pelo nome do conjunto de dados em que o recurso está.

Saiba mais sobre a instrução DCL REVOKE em Instruções da linguagem de controle de dados em SQL padrão.

bq

Use o comando show para gravar as informações atuais do conjunto de dados, incluindo controles de acesso, em um arquivo JSON. 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.
```
bq show \
--format=prettyjson \
project_id:dataset > path_to_file
```
Substitua:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados;
- path_to_file é o caminho do arquivo JSON na sua máquina local.
Exemplos:

Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está no projeto padrão.
```
  bq show --format=prettyjson mydataset > /tmp/mydataset.json
```
Digite o comando a seguir para gravar os controles de acesso para mydataset em um arquivo JSON. mydataset está em myotherproject.
```
  bq show --format=prettyjson \
  myotherproject:mydataset > /tmp/mydataset.json
```

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"
  }
 ],
 ...
}

Quando as edições estiverem concluídas, use o comando 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
```
Substitua:
- path_to_file é o caminho do arquivo JSON na sua máquina local.
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados;
Exemplos:

Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está no projeto padrão.
```
    bq update --source /tmp/mydataset.json mydataset
```
Digite o comando a seguir para atualizar os controles de acesso para mydataset. mydataset está em myotherproject.
```
    bq update --source /tmp/mydataset.json myotherproject:mydataset
```
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 dataset
```
ou
```
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

Ver no GitHub Feedback

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 := "user@mydomain.com"
	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
}

Próximas etapas

Para mais informações sobre como criar conjuntos de dados, consulte Como criar conjuntos de dados.
Para mais informações sobre como listar conjuntos de dados em um projeto, consulte Como listar conjuntos de dados.
Para mais informações sobre metadados do conjunto de dados, consulte Como receber informações sobre conjuntos de dados.
Para mais informações sobre como alterar propriedades do conjunto de dados, consulte Como atualizar conjuntos de dados.
Para mais informações sobre como criar e gerenciar rótulos, consulte esta página.