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

A partir de 15 de setembro de 2025, a permissão bigquery.datasets.getIamPolicy 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

Até 15 de setembro de 2025, você pode ativar a aplicação antecipada das mudanças de permissão. Quando você ativa a permissão bigquery.datasets.getIamPolicy, ela é necessária para receber 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 de dados 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 informações sobre como ativar as configurações, consulte Gerenciar configurações de configuração.

Exemplos de configuração

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 bigquery.datasets.get, bigquery.datasets.create ou bigquery.datasets.update e não concedem 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é 15 de setembro de 2025, se você quiser manter a funcionalidade atual dos papéis personalizados. Se suas funções personalizadas precisarem visualizar ou atualizar apenas 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 os metadados de um conjunto de dados. Use um dos seguintes valores:

• METADATA: visualizar apenas os metadados do conjunto de dados. Esse valor exige a permissão bigquery.datasets.get.
• ACL: visualizar apenas os controles de acesso do conjunto de dados. Esse valor exige a permissão bigquery.datasets.getIamPolicy.
• FULL: visualizar 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 os metadados de um conjunto de dados. Use um dos seguintes valores:

• UPDATE_METADATA: atualiza apenas os metadados do conjunto de dados. Esse valor exige a permissão bigquery.datasets.update.
• UPDATE_ACL: atualiza apenas os controles de acesso do conjunto de dados. Esse valor exige a permissão bigquery.datasets.setIamPolicy.
• UPDATE_FULL: atualizar 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)

Quando você ativa 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 INFORMATION_SCHEMA

Quando você ativa 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 necessária e a resposta da API para os diferentes valores aceitos pelo parâmetro dataset_view:

Se você não ativar a aplicação antecipada ou desativar a opção depois de ativá-la, poderá usar o parâmetro dataset_view com os valores METADATA ou ACL. Os valores FULL e DATASET_VIEW_UNSPECIFIED (ou vazios) são padrão para o comportamento anterior. A permissão bigquery.datasets.get permite que você receba 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 de controles de acesso e metadados, o parâmetro update_mode permite especificar se você quer atualizar 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 necessária e a resposta da API para os diferentes valores aceitos pelo parâmetro update_mode:

Se você não ativar a aplicação antecipada ou desativar a opção depois de ativá-la, o BigQuery vai usar o comportamento anterior. 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 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 de controles de acesso e metadados, o parâmetro update_mode permite especificar se você quer atualizar 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 necessária e a resposta da API para os diferentes valores aceitos pelo parâmetro update_mode:

Se você não ativar a aplicação antecipada ou desativar a opção depois de ativá-la, o BigQuery vai usar o comportamento anterior. 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 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 são 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.