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 gerenciamento de identidade e acesso (IAM, na sigla em inglês) 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 Google 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 Google 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.

Antes de começar

Conceda os papéis do IAM que dão aos usuários as permissões necessárias para executar cada tarefa neste documento.

Permissões necessárias

Para controlar o acesso a um conjunto de dados, você precisa das seguintes permissões do IAM:

• bigquery.datasets.update
• bigquery.datasets.get
• bigquery.datasets.getIamPolicy (permite controlar o acesso a um conjunto de dados usando o console do Google Cloud)
• bigquery.datasets.setIamPolicy (permite controlar o acesso a um conjunto de dados usando o console do Google Cloud)

O papel predefinido do IAM roles/bigquery.dataOwner inclui as permissões necessárias para controlar o acesso a um conjunto de dados.

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

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

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

3. Clique em Adicionar principal.

4. No campo Novos participantes, digite a entidade que você quer adicionar. É 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 todas as contas de serviço e a todos os usuários da Internet que se autenticaram com uma Conta do Google. Por exemplo, [e-mail].

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

6. Clique em Concluído.

SQL

O exemplo a seguir usa a instrução DCL GRANT para conceder o papel de visualizador de dados do BigQuery (roles/bigquery.dataViewer) ao usuário [e-mail] no conjunto de dados mydataset:

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 `roles/bigquery.dataViewer`
   ON SCHEMA mydataset
   TO 'user:[e-mail]';
   

3. Clique em Executar.

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

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

2. 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": "WRITER",
      "userByEmail": "service_account_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }
   

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

4. 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:     "[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.

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 "[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 para 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

# 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)
)

Observação: para que um usuário possa consultar as tabelas em um conjunto de dados, não basta que ele tenha acesso ao conjunto de dados. Um usuário também precisa ter permissão para executar um job de consulta em um projeto. Se você quiser conceder a um usuário permissão para executar uma consulta no projeto, conceda a ele a permissão bigquery.jobs.create para o projeto. Você pode fazer isso atribuindo ao usuário o papel roles/bigquery.jobUser para o projeto. Para mais informações, consulte Exemplos de controle de acesso.

Como revogar o acesso a um conjunto de dados

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

Console

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

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

3. Na caixa de diálogo Permissões do conjunto de dados, expanda o papel com a assinatura que você quer alterar.

4. Clique em Excluir na conta de usuário que você quer remover.

5. Na caixa de diálogo Remover membro?, clique em Remover.

6. Clique em Concluído.

SQL

O exemplo a seguir usa a instrução DCL REVOKE para remover o papel visualizador de dados do BigQuery (roles/bigquery.dataViewer) do usuário [e-mail] no no conjunto de dados mydataset:

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 `roles/bigquery.dataViewer`
   ON SCHEMA mydataset
   FROM 'user:[e-mail]';
   

3. Clique em Executar.

Para informações sobre como executar consultas, consulte Como executar consultas interativas.

bq

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

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

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

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

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

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

# 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}.'")

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.