Mudanças nos controles de acesso no nível do conjunto de dados

A partir de 17 de março de 2026, a permissão bigquery.datasets.getIamPolicy do Identity and Access Management (IAM) será necessária para visualizar os controles de acesso de um conjunto de dados e consultar a visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES. A permissão bigquery.datasets.setIamPolicy é necessária para atualizar os controles de acesso de um conjunto de dados ou para criar um conjunto de dados com controles de acesso usando a API.

Ativar a aplicação antecipada

Antes de 17 de março de 2026, você pode ativar a aplicação antecipada das mudanças de permissão. Ao ativar, a permissão bigquery.datasets.getIamPolicy é necessária para acessar os controles de acesso de um conjunto de dados, e a permissão bigquery.datasets.setIamPolicy é necessária para atualizar os controles de acesso de um conjunto de dados ou criar um conjunto com controles de acesso usando a API.

Para ativar a aplicação antecipada, defina a configuração enable_fine_grained_dataset_acls_option como TRUE no nível da organização ou do projeto. Para instruções sobre como ativar as configurações, consulte Gerenciar configurações de configuração.

Exemplos de configurações

Os exemplos a seguir mostram como definir e remover a configuração enable_fine_grained_dataset_acls_option.

Definir as configurações da organização

Para definir as configurações da organização, use a instrução DDL ALTER ORGANIZATION SET OPTIONS. O exemplo a seguir define enable_fine_grained_dataset_acls_option como TRUE no nível da organização:

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = TRUE);

Substitua REGION pela região associada à sua organização, por exemplo, us ou europe-west6.

O exemplo a seguir limpa a configuração enable_fine_grained_dataset_acls_option no nível da organização:

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = FALSE);

Definir configurações do projeto

Para definir as configurações do projeto, use a instrução DDL ALTER PROJECT SET OPTIONS. A instrução DDL ALTER PROJECT SET OPTIONS aceita opcionalmente a variável project_id. Quando o project_id não é especificado, o padrão é o projeto atual em que a consulta é executada.

O exemplo a seguir define enable_fine_grained_dataset_acls_option como TRUE:

ALTER PROJECT PROJECT_ID
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = TRUE);

Substitua PROJECT_ID pela ID do seu projeto.

O exemplo a seguir limpa a configuração enable_fine_grained_dataset_acls_option no nível do projeto:

ALTER PROJECT PROJECT_ID
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = FALSE);

Mudanças nos papéis personalizados

Essa mudança nas permissões necessárias afeta os papéis personalizados atuais que concedem as permissões bigquery.datasets.get, bigquery.datasets.create ou bigquery.datasets.update e não concedem as permissões bigquery.datasets.getIamPolicy ou bigquery.datasets.setIamPolicy.

Todos os papéis personalizados que incluem apenas a permissão bigquery.datasets.get, bigquery.datasets.update ou bigquery.datasets.create precisam ser atualizados para incluir a permissão bigquery.datasets.getIamPolicy ou bigquery.datasets.setIamPolicy até 17 de março de 2026, se você quiser manter a funcionalidade atual dos papéis personalizados. Se as funções personalizadas precisarem apenas visualizar ou atualizar os metadados de um conjunto de dados, use os novos parâmetros dataset_view e update_mode.

As funções predefinidas do BigQuery não são afetadas por essa mudança. Todos os papéis predefinidos que concedem a permissão bigquery.datasets.get também concedem a permissão bigquery.datasets.getIamPolicy. Todos os papéis predefinidos que concedem a permissão bigquery.datasets.update também concedem a permissão bigquery.datasets.setIamPolicy.

Mudanças nos comandos da ferramenta de linha de comando bq

Quando você ativa a aplicação antecipada, os seguintes comandos da ferramenta bq são afetados.

bq show

Use o comando bq show com a seguinte flag:

--dataset_view={METADATA|ACL|FULL}
Especifica como aplicar permissões ao visualizar os controles de acesso ou metadados de um conjunto de dados. Use um dos seguintes valores:
  • METADATA: veja apenas os metadados do conjunto de dados. Esse valor exige a permissão bigquery.datasets.get.
  • ACL: veja apenas os controles de acesso do conjunto de dados. Esse valor exige a permissão bigquery.datasets.getIamPolicy.
  • FULL: veja os metadados e os controles de acesso do conjunto de dados. Esse valor exige as permissões bigquery.datasets.get e bigquery.datasets.getIamPolicy.

bq update

Use o comando bq update com a seguinte flag:

--update_mode={UPDATE_METADATA|UPDATE_ACL|UPDATE_FULL}
Especifica como aplicar permissões ao atualizar os controles de acesso ou metadados de um conjunto de dados. Use um dos seguintes valores:
  • UPDATE_METADATA: atualiza apenas os metadados do conjunto de dados. Esse valor requer a permissão bigquery.datasets.update.
  • UPDATE_ACL: atualiza apenas os controles de acesso do conjunto de dados. Esse valor requer a permissão bigquery.datasets.setIamPolicy.
  • UPDATE_FULL: atualize os metadados e os controles de acesso do conjunto de dados. Esse valor exige as permissões bigquery.datasets.update e bigquery.datasets.setIamPolicy.

Mudanças nas instruções da linguagem de controle de dados (DCL)

Ao ativar a aplicação antecipada, as seguintes permissões são necessárias para executar instruções GRANT e REVOKE em conjuntos de dados usando a linguagem de controle de dados (DCL):

  • bigquery.datasets.setIamPolicy

Mudanças nas consultas de visualização do INFORMATION_SCHEMA

Ao ativar a aplicação antecipada, a permissão bigquery.datasets.getIamPolicy é necessária para consultar a visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES.

Mudanças nos métodos da API

Depois de ativar a aplicação antecipada, os seguintes métodos de conjunto de dados da API REST v2 serão afetados.

Método datasets.get

O método datasets.get tem um parâmetro de caminho adicional chamado dataset_view.

Esse parâmetro oferece mais controle sobre as informações retornadas pelo método datasets.get. Em vez de sempre retornar controles de acesso e metadados, o parâmetro dataset_view permite especificar se você quer retornar apenas metadados, apenas controles de acesso ou ambos.

O campo access no recurso do conjunto de dados contém os controles de acesso do conjunto de dados. Os outros campos, como friendlyName, description e labels, representam os metadados do conjunto de dados.

A tabela a seguir mostra a permissão obrigatória e a resposta da API para os diferentes valores aceitos pelo parâmetro dataset_view:

Valor de parâmetro Permissões necessárias Resposta da API
DATASET_VIEW_UNSPECIFIED (ou vazio)
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 O valor padrão. Retorna os metadados e controles de acesso do conjunto de dados.
METADATA
  • bigquery.datasets.get
 Retorna os metadados do conjunto de dados.
ACL
  • bigquery.datasets.getIamPolicy
 Retorna os controles de acesso, os campos obrigatórios e os campos do recurso do conjunto de dados que são somente de saída.
FULL
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 Retorna os metadados e controles de acesso do conjunto de dados.

Se você não ativar a aplicação antecipada ou se desativar depois de ativar, use o parâmetro dataset_view com os valores METADATA ou ACL. Os valores FULL e DATASET_VIEW_UNSPECIFIED (ou vazio) são definidos como o comportamento anterior por padrão. A permissão bigquery.datasets.get permite receber metadados e controles de acesso.

Exemplo

O exemplo a seguir envia uma solicitação GET com o parâmetro dataset_view definido como METADATA:

GET https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?datasetView=METADATA&key=YOUR_API_KEY HTTP/1.1

Substitua:

  • YOUR_PROJECT: o nome do projeto.
  • YOUR_DATASET: o nome do conjunto de dados
  • YOUR_API_KEY: sua chave de API

Método datasets.update

O método datasets.update tem um parâmetro de caminho adicional chamado update_mode.

Esse parâmetro oferece mais controle sobre os campos atualizados pelo método datasets.update. Em vez de sempre permitir atualizações nos controles de acesso e nos metadados, o parâmetro update_mode permite especificar se você quer atualizar apenas os metadados, apenas os controles de acesso ou ambos.

O campo access no recurso do conjunto de dados contém os controles de acesso do conjunto de dados. Os outros campos, como friendlyName, description e labels, representam os metadados do conjunto de dados.

A tabela a seguir mostra a permissão obrigatória e a resposta da API para os diferentes valores aceitos pelo parâmetro update_mode:

Valor de parâmetro Permissões necessárias Resposta da API
UPDATE_MODE_UNSPECIFIED (ou vazio)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 O valor padrão. Retorna os metadados atualizados e os controles de acesso do conjunto de dados.
UPDATE_METADATA
  • bigquery.datasets.update
 Retorna os metadados atualizados do conjunto de dados.
UPDATE_ACL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Retorna os controles de acesso atualizados, os campos obrigatórios e os campos somente de saída do recurso do conjunto de dados.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Retorna os metadados e controles de acesso atualizados do conjunto de dados.

Se você não ativar a aplicação antecipada ou se desativar depois de ativar, o BigQuery vai usar o comportamento anterior por padrão. A permissão bigquery.datasets.update permite atualizar os metadados e os controles de acesso.

Exemplo

O exemplo a seguir envia uma solicitação PUT com o parâmetro update_mode definido como METADATA:

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

Substitua:

  • YOUR_PROJECT: o nome do projeto.
  • YOUR_DATASET: o nome do conjunto de dados
  • YOUR_API_KEY: o nome da sua chave de API

Método datasets.patch

O método datasets.patch tem um parâmetro de caminho adicional chamado update_mode.

Esse parâmetro oferece mais controle sobre os campos atualizados pelo método datasets.patch. Em vez de sempre permitir atualizações nos controles de acesso e nos metadados, o parâmetro update_mode permite especificar se você quer atualizar apenas os metadados, apenas os controles de acesso ou ambos.

O campo access no recurso do conjunto de dados contém os controles de acesso do conjunto de dados. Os outros campos, como friendlyName, description e labels, representam os metadados do conjunto de dados.

A tabela a seguir mostra a permissão obrigatória e a resposta da API para os diferentes valores aceitos pelo parâmetro update_mode:

Valor de parâmetro Permissões necessárias Resposta da API
UPDATE_MODE_UNSPECIFIED (ou vazio)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 O valor padrão. Retorna os metadados atualizados e os controles de acesso do conjunto de dados.
UPDATE_METADATA
  • bigquery.datasets.update
 Retorna os metadados atualizados do conjunto de dados.
UPDATE_ACL
  • bigquery.datasets.setIamPolicy
 Retorna os controles de acesso atualizados, os campos obrigatórios e os campos somente de saída do recurso do conjunto de dados.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Retorna os metadados e controles de acesso atualizados do conjunto de dados.

Se você não ativar a aplicação antecipada ou se desativar depois de ativar, o BigQuery vai usar o comportamento anterior por padrão. A permissão bigquery.datasets.update permite atualizar os metadados e os controles de acesso.

Exemplo

O exemplo a seguir envia uma solicitação PUT com o parâmetro update_mode definido como METADATA:

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

Substitua:

  • YOUR_PROJECT: o nome do projeto.
  • YOUR_DATASET: o nome do conjunto de dados
  • YOUR_API_KEY: o nome da sua chave de API

Método datasets.insert

Se você ativar a aplicação antecipada e usar o método datasets.insert para criar um conjunto de dados com controles de acesso, o BigQuery vai verificar se as permissões bigquery.datasets.create e bigquery.datasets.setIamPolicy foram concedidas ao usuário.

Se você usar a API para criar um conjunto de dados sem controles de acesso, apenas a permissão bigquery.datasets.create será necessária.