Alterações aos controlos de acesso ao nível do conjunto de dados

A partir de 17 de março de 2026, a autorização de gestão de identidade e de acesso (IAM) é necessária para ver os controlos de acesso de um conjunto de dados e para consultar a vista INFORMATION_SCHEMA.OBJECT_PRIVILEGES.bigquery.datasets.getIamPolicy A autorização bigquery.datasets.setIamPolicy é necessária para atualizar os controlos de acesso de um conjunto de dados ou para criar um conjunto de dados com controlos de acesso através da API.

Ative a aplicação antecipada

Antes de 17 de março de 2026, pode optar pela aplicação antecipada das alterações de autorizações. Quando ativa esta opção, a autorização bigquery.datasets.getIamPolicy é necessária para obter os controlos de acesso de um conjunto de dados, e a autorização bigquery.datasets.setIamPolicy é necessária para atualizar os controlos de acesso de um conjunto de dados ou para criar um conjunto de dados com controlos de acesso através da API.

Para optar pela aplicação antecipada, defina a enable_fine_grained_dataset_acls_optiondefinição de configuração como TRUE ao nível da organização ou do projeto. Para ver instruções sobre como ativar as definições de configuração, consulte o artigo Faça a gestão das definições de configuração.

Exemplos de definições de configuração

Os exemplos seguintes mostram como definir e remover a definição de configuração enable_fine_grained_dataset_acls_option.

Configure as definições da organização

Para configurar as definições da organização, use a ALTER ORGANIZATION SET OPTIONS declaração DDL. O exemplo seguinte define enable_fine_grained_dataset_acls_option como TRUE ao 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 seguinte limpa a definição enable_fine_grained_dataset_acls_option ao nível da organização:

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

Configure as definições do projeto

Para configurar as definições do projeto, use a ALTER PROJECT SET OPTIONS declaração DDL. A declaração DDL aceita opcionalmente a variável ALTER PROJECT SET OPTIONSproject_id. Se o project_id não for especificado, a predefinição é o projeto atual onde a consulta é executada.

O exemplo seguinte 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 pelo ID do seu projeto.

O exemplo seguinte limpa a definição ao nível do projeto enable_fine_grained_dataset_acls_option:

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

Alterações às funções personalizadas

Esta alteração às autorizações necessárias afeta as funções personalizadas existentes que concedem a autorização bigquery.datasets.get, bigquery.datasets.create ou bigquery.datasets.update e que também não concedem a autorização bigquery.datasets.getIamPolicy ou bigquery.datasets.setIamPolicy.

Quaisquer funções personalizadas que incluam apenas a autorização bigquery.datasets.get, bigquery.datasets.update ou bigquery.datasets.create têm de ser atualizadas para incluir a autorização bigquery.datasets.getIamPolicy ou bigquery.datasets.setIamPolicy até 17 de março de 2026, se quiser manter a funcionalidade existente das funções personalizadas. Se as suas funções personalizadas precisarem de ver 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 esta alteração. Todas as funções predefinidas que concedem a autorização bigquery.datasets.get também concedem a autorização bigquery.datasets.getIamPolicy. Todas as funções predefinidas que concedem a autorização bigquery.datasets.update também concedem a autorização bigquery.datasets.setIamPolicy.

Alterações aos comandos da ferramenta de linhas de comando bq

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

bq show

Pode usar o comando bq show com a seguinte flag:

--dataset_view={METADATA|ACL|FULL}
Especifica como aplicar autorizações quando está a ver os controlos de acesso ou os metadados de um conjunto de dados. Use um dos seguintes valores:
  • METADATA: ver apenas os metadados do conjunto de dados. Este valor requer a autorização bigquery.datasets.get.
  • ACL: ver apenas os controlos de acesso do conjunto de dados. Este valor requer a autorização bigquery.datasets.getIamPolicy.
  • FULL: ver os metadados e os controlos de acesso do conjunto de dados. Este valor requer a autorização bigquery.datasets.get e as autorizações bigquery.datasets.getIamPolicy.

bq update

Pode usar o comando bq update com a seguinte flag:

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

Alterações às declarações da linguagem de controlo de dados (DCL)

Quando opta pela aplicação antecipada, são necessárias as seguintes autorizações para executar declarações GRANT e REVOKE em conjuntos de dados através da linguagem de controlo de dados (DCL):

  • bigquery.datasets.setIamPolicy

Alterações às INFORMATION_SCHEMA consultas de visualização

Quando opta pela aplicação antecipada, a bigquery.datasets.getIamPolicyautorização é necessária para consultar a visualização INFORMATION_SCHEMA.OBJECT_PRIVILEGES.

Alterações aos métodos da API

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

datasets.get method

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

Este parâmetro dá-lhe mais controlo sobre as informações devolvidas pelo método datasets.get. Em vez de devolver sempre os controlos de acesso e os metadados, o parâmetro dataset_view permite-lhe especificar se pretende devolver apenas os metadados, apenas os controlos de acesso ou ambos.

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

A tabela seguinte mostra a autorização necessária e a resposta da API para os diferentes valores suportados pelo parâmetro dataset_view:

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

Se não ativar a aplicação antecipada ou se a desativar depois de a ativar, pode usar o parâmetro dataset_view com os valores METADATA ou ACL. Os valores FULL e DATASET_VIEW_UNSPECIFIED (ou vazios) são predefinidos para o comportamento anterior. A autorização bigquery.datasets.get permite-lhe obter os metadados e os controlos de acesso.

Exemplo

O exemplo seguinte envia um pedido 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 o seguinte:

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

datasets.update method

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

Este parâmetro dá-lhe mais controlo sobre os campos atualizados pelo método datasets.update. Em vez de permitir sempre atualizações aos controlos de acesso e aos metadados, o parâmetro update_mode permite-lhe especificar se pretende atualizar apenas os metadados, apenas os controlos de acesso ou ambos.

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

A tabela seguinte mostra a autorização necessária e a resposta da API para os diferentes valores suportados pelo parâmetro update_mode:

Valor do parâmetro Autorizações necessárias Resposta da API
UPDATE_MODE_UNSPECIFIED (ou vazio)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 O valor predefinido. Devolve os metadados atualizados e os controlos de acesso do conjunto de dados.
UPDATE_METADATA
  • bigquery.datasets.update
 Devolve os metadados atualizados do conjunto de dados.
UPDATE_ACL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Devolve os controlos de acesso atualizados, os campos obrigatórios e os campos no recurso do conjunto de dados que são apenas de saída.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Devolve os metadados atualizados e os controlos de acesso do conjunto de dados.

Se não aceitar a aplicação antecipada ou se recusar depois de aceitar, o BigQuery volta ao comportamento anterior. A autorização bigquery.datasets.update permite-lhe atualizar os metadados e os controlos de acesso.

Exemplo

O exemplo seguinte envia um pedido 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 o seguinte:

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

datasets.patch method

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

Este parâmetro dá-lhe mais controlo sobre os campos atualizados pelo método datasets.patch. Em vez de permitir sempre atualizações aos controlos de acesso e aos metadados, o parâmetro update_mode permite-lhe especificar se pretende atualizar apenas os metadados, apenas os controlos de acesso ou ambos.

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

A tabela seguinte mostra a autorização necessária e a resposta da API para os diferentes valores suportados pelo parâmetro update_mode:

Valor do parâmetro Autorizações necessárias Resposta da API
UPDATE_MODE_UNSPECIFIED (ou vazio)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 O valor predefinido. Devolve os metadados atualizados e os controlos de acesso do conjunto de dados.
UPDATE_METADATA
  • bigquery.datasets.update
 Devolve os metadados atualizados do conjunto de dados.
UPDATE_ACL
  • bigquery.datasets.setIamPolicy
 Devolve os controlos de acesso atualizados, os campos obrigatórios e os campos no recurso do conjunto de dados que são apenas de saída.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Devolve os metadados atualizados e os controlos de acesso do conjunto de dados.

Se não aceitar a aplicação antecipada ou se recusar depois de aceitar, o BigQuery volta ao comportamento anterior. A autorização bigquery.datasets.update permite-lhe atualizar os metadados e os controlos de acesso.

Exemplo

O exemplo seguinte envia um pedido 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 o seguinte:

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

datasets.insert method

Se optar pela aplicação antecipada e usar o método datasets.insert para criar um conjunto de dados com controlos de acesso, o BigQuery verifica se as autorizações bigquery.datasets.create e bigquery.datasets.setIamPolicy foram concedidas ao utilizador.

Se usar a API para criar um conjunto de dados sem controlos de acesso, só é necessária a autorização bigquery.datasets.create.