Como atualizar propriedades de conjuntos de dados

Neste documento, você verá como atualizar propriedades de conjuntos de dados no BigQuery. Depois de criar um conjunto de dados, é possível atualizar as seguintes propriedades:

Permissões necessárias

Para atualizar propriedades de conjuntos de dados, é necessário ter pelo menos as permissões bigquery.datasets.update e bigquery.datasets.get. Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.datasets.update e bigquery.datasets.get:

  • bigquery.dataOwner
  • bigquery.admin

Além disso, quando um usuário tem permissões bigquery.datasets.create e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. Com o acesso de bigquery.dataOwner, os usuários conseguem atualizar as propriedades dos conjuntos de dados criados por eles.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Controle de acesso.

Como atualizar descrições de conjunto de dados

É possível atualizar a descrição de um conjunto de dados das seguintes maneiras:

  • usando o Console do Cloud;
  • usando o comando bq da ferramenta de linha de comando bq update;
  • Chamada do método de API datasets.patch
  • usando bibliotecas de cliente;

Para atualizar a descrição de um conjunto de dados:

Console

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

  2. Expanda a opção Ações e clique em Abrir.

  3. No painel Detalhes, clique no ícone de lápis ao lado de Descrição para editar o texto da descrição.

    Configurações de consulta.

  4. Insira uma nova ou edite uma descrição atual na caixa de diálogo. Clique em Atualizar para salvar o novo texto da descrição.

SQL

Para atualizar a descrição de um conjunto de dados, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção description.

No exemplo a seguir, definimos a descrição em um conjunto de dados chamado mydataset:

 ALTER SCHEMA mydataset
 SET OPTIONS(
     description="Description of mydataset"
 )

Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.

bq

Use o comando bq update com a sinalização --description. Caso esteja atualizando um conjunto de dados 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 update \
--description "string" \
project_id:dataset

Substitua:

  • string: o texto que descreve o conjunto de dados entre aspas.
  • project_id: ID do projeto
  • dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Use o comando a seguir para alterar a descrição de mydataset para "Descrição de mydataset". mydataset está no projeto padrão.

bq update --description "Description of mydataset" mydataset

Use o comando a seguir para alterar a descrição de mydataset para "Descrição de mydataset". O conjunto de dados está em myotherproject, e não no projeto padrão.

bq update \
--description "Description of mydataset" \
myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade description no recurso de conjunto de dados. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

Go

Antes de testar essa amostra, siga as instruções de configuração para 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.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateDatasetDescription demonstrates how the Description metadata of a dataset can
// be read and modified.
func updateDatasetDescription(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
	}
	update := bigquery.DatasetMetadataToUpdate{
		Description: "Updated Description.",
	}
	if _, err = ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

Crie uma instância Dataset.Builder a partir de uma instância Dataset atual com o método Dataset.toBuilder(). Configure o objeto de builder do conjunto de dados. Crie o conjunto de dados atualizado com o método Dataset.Builder.build() e chame o método Dataset.update() para enviar a atualização para a API (links em inglês).
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

public class UpdateDatasetDescription {

  public static void runUpdateDatasetDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String newDescription = "this is the new dataset description";
    updateDatasetDescription(datasetName, newDescription);
  }

  public static void updateDatasetDescription(String datasetName, String newDescription) {
    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);
      bigquery.update(dataset.toBuilder().setDescription(newDescription).build());
      System.out.println("Dataset description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Dataset description was not updated \n" + e.toString());
    }
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetDescription() {
  // Updates a dataset's description.

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset description
  const description = 'New dataset description.';
  metadata.description = description;

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${datasetId} description: ${newDescription}`);
}

Python

Antes de testar essa 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.

Configure a propriedade Dataset.description e chame Client.update_dataset() (ambos em inglês) para enviar a atualização para a API.

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.
dataset.description = "Updated description."
dataset = client.update_dataset(dataset, ["description"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with description '{}'.".format(
        full_dataset_id, dataset.description
    )
)

Como atualizar o prazo de validade padrão de tabelas

É possível atualizar o prazo de validade padrão da tabela de um conjunto de dados das seguintes maneiras:

  • usando o Console do Cloud;
  • usando o comando bq da ferramenta de linha de comando bq update;
  • Chamada do método de API datasets.patch
  • usando bibliotecas de cliente.

É possível configurar o prazo de validade padrão da tabela no nível do conjunto de dados ou defini-lo quando a tabela é criada. Ao fazer isso durante a criação da tabela, a expiração padrão da tabela do conjunto de dados será ignorada. Se você não a configurar no nível do conjunto de dados e não defini-la quando a tabela for criada, a tabela nunca expirará, e você precisará excluí-la manualmente.

Ao atualizar a configuração da validade padrão da tabela de um conjunto de dados:

  • Se você alterar o valor de Never para um prazo de validade definido, todas as tabelas no conjunto de dados só expirarão caso esse prazo tenha sido definido na tabela quando ela foi criada.
  • Se você estiver alterando o valor da validade padrão de tabelas, todas as tabelas atuais expirarão de acordo com a configuração de validade original. A nova configuração de expiração será aplicada a todas as novas tabelas criadas no conjunto de dados, a menos que você especifique uma expiração diferente na tabela quando ela for criada.

O valor da expiração padrão da tabela é expresso de diferentes formas, dependendo do local em que você o define. Use o método que garanta o nível apropriado de granularidade:

  • No Console do Cloud, a validade é expressa em dias.
  • Na ferramenta de linha de comando bq, a validade é expressa em segundos.
  • Na API, em milissegundos.

Para atualizar o prazo de validade padrão de um conjunto de dados:

Console

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

  2. Expanda a opção Ações e clique em Abrir.

  3. No painel de detalhes, clique no ícone de lápis ao lado de Informações do conjunto de dados para editar a validade.

  4. Na caixa de diálogo Informações do conjunto de dados, na seção Expiração da tabela padrão, insira um valor para Número de dias após a criação da tabela.

  5. Clique em Save.

SQL

Para atualizar o prazo de validade da tabela padrão, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção default_table_expiration_days.

O exemplo a seguir atualiza a validade padrão de tabelas de um conjunto de dados chamado mydataset.

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_table_expiration_days=3.75
 )

Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.

bq

Para atualizar o prazo de validade padrão de tabelas recém-criadas em um conjunto de dados, digite o comando bq update com a sinalização --default_table_expiration. Caso esteja atualizando um conjunto de dados 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 update \
--default_table_expiration integer \
project_id:dataset

Substitua:

  • integer: a vida útil padrão, em segundos, das tabelas recém-criadas. O valor mínimo é de 3.600 segundos (uma hora). O prazo de validade é a soma do horário UTC atual com o valor inteiro. Especifique 0 para remover o prazo de validade atual. Qualquer tabela criada no conjunto de dados será excluída integer segundos após a hora de criação. Esse valor será aplicado caso a validade da tabela não seja definida quando ela for criada.
  • project_id: o ID do projeto.
  • dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Digite o comando a seguir para definir a validade padrão de tabelas para novas tabelas criadas em mydataset como duas horas (7.200 segundos) a partir do horário atual. O conjunto de dados está no projeto padrão.

bq update --default_table_expiration 7200 mydataset

Digite o comando a seguir para definir a validade padrão de tabelas para novas tabelas criadas em mydataset como duas horas (7.200 segundos) a partir do horário atual. O conjunto de dados está em myotherproject, e não no projeto padrão.

bq update --default_table_expiration 7200 myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade defaultTableExpirationMs no recurso de conjunto de dados. A expiração é expressa em milissegundos na API. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

Go

Antes de testar essa amostra, siga as instruções de configuração para 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.

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// updateDatasetDefaultExpiration demonstrats setting the default expiration of a dataset
// to a specific retention period.
func updateDatasetDefaultExpiration(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
	}
	update := bigquery.DatasetMetadataToUpdate{
		DefaultTableExpiration: 24 * time.Hour,
	}
	if _, err := client.Dataset(datasetID).Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar essa amostra, siga as instruções de configuração para 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.

Crie uma instância Dataset.Builder a partir de uma instância Dataset atual com o método Dataset.toBuilder(). Configure o objeto de builder do conjunto de dados. Crie o conjunto de dados atualizado com o método Dataset.Builder.build() e chame o método Dataset.update() para enviar a atualização para a API (links em inglês).

Configure o prazo de validade padrão com o método Dataset.Builder.setDefaultTableLifetime() (link em inglês).

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.concurrent.TimeUnit;

public class UpdateDatasetExpiration {

  public static void runUpdateDatasetExpiration() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    updateDatasetExpiration(datasetName);
  }

  public static void updateDatasetExpiration(String datasetName) {
    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();

      // Update dataset expiration to one day
      Long newExpiration = TimeUnit.MILLISECONDS.convert(1, TimeUnit.DAYS);

      Dataset dataset = bigquery.getDataset(datasetName);
      bigquery.update(dataset.toBuilder().setDefaultTableLifetime(newExpiration).build());
      System.out.println("Dataset description updated successfully to " + newExpiration);
    } catch (BigQueryException e) {
      System.out.println("Dataset expiration was not updated \n" + e.toString());
    }
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetExpiration() {
  // Updates the lifetime of all tables in the dataset, in milliseconds.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset metadata
  const expirationTime = 24 * 60 * 60 * 1000;
  metadata.defaultTableExpirationMs = expirationTime.toString();

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newExpirationTime = apiResponse.defaultTableExpirationMs;

  console.log(`${datasetId} expiration: ${newExpirationTime}`);
}

Python

Antes de testar essa 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.

Configure a propriedade Dataset.default_table_expiration_ms e chame Client.update_dataset() para enviar a atualização para a API (links em inglês).

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.
dataset.default_table_expiration_ms = 24 * 60 * 60 * 1000  # In milliseconds.

dataset = client.update_dataset(
    dataset, ["default_table_expiration_ms"]
)  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset {} with new expiration {}".format(
        full_dataset_id, dataset.default_table_expiration_ms
    )
)

Como atualizar os prazos de validade padrão de partições

É possível atualizar a validade padrão de partições de um conjunto de dados das seguintes maneiras:

A configuração ou atualização da validade da partição padrão de um conjunto de dados não é compatível com o Console do Cloud.

É possível definir um prazo de validade padrão de partições no nível do conjunto de dados que afete todas as tabelas particionadas recém-criadas. Se preferir, defina um prazo de validade de partições individualmente durante a criação das tabelas particionadas. Se você definir os prazos de validade padrão de partições e tabelas no nível do conjunto de dados, as novas tabelas particionadas terão apenas uma validade de partições. Quando ambas as opções são definidas, a validade padrão de partições modifica a validade padrão de tabelas.

Se você definir o prazo de validade da partição no momento da criação da tabela, esse valor modificará a validade padrão definida no nível do conjunto de dados.

Se você não definir uma validade padrão de partição no nível do conjunto de dados nem a validade de partição durante a criação da tabela, as partições nunca expirarão e será necessário excluí-las manualmente.

Quando definimos uma validade padrão de partições em um conjunto de dados, esse prazo é aplicado a todas as partições nas tabelas particionadas criadas no conjunto de dados. Quando definimos a validade de partições em uma tabela, esse prazo é aplicado a todas as partições criadas na tabela especificada. Atualmente, não é possível aplicar prazos de validade distintos a diferentes partições na mesma tabela.

Ao atualizar a validade padrão de partição de um conjunto de dados:

  • altere o valor de never para um prazo de validade definido. Assim, todas as partições atuais das tabelas particionadas no conjunto de dados não expirarão, a menos que tal prazo tenha sido definido nas tabelas quando elas foram criadas;
  • altere o valor de validade padrão de partição. Assim, todas as partições nas tabelas particionadas atuais expirarão de acordo com o prazo original. A nova validade padrão de partição será aplicada a todas as novas tabelas particionadas criadas no conjunto de dados, a menos que você especifique um prazo diferente durante a criação das tabelas.

O valor da validade padrão da tabela é expresso de formas diferentes, dependendo do local em que é definido. Use o método que garanta o nível apropriado de granularidade:

  • Na ferramenta de linha de comando bq, a validade é expressa em segundos.
  • Na API, em milissegundos.

Para atualizar o prazo de validade da partição padrão de um conjunto de dados:

Console

A atualização da validade padrão de partições de um conjunto de dados não é compatível com o Console do Cloud.

SQL

Para atualizar o prazo de validade padrão da partição, use a instrução ALTER SCHEMA SET OPTIONS para definir a opção default_partition_expiration_days.

O exemplo a seguir atualiza a validade padrão de partições de um conjunto de dados chamado mydataset:

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_partition_expiration_days=3.75
 )

Para informações sobre como executar uma consulta SQL no BigQuery, consulte Como executar jobs de consulta interativa e em lote.

bq

Para atualizar o prazo de validade padrão de um conjunto de dados, insira o comando bq update com a sinalização --default_partition_expiration. Caso esteja atualizando um conjunto de dados 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 update \
--default_partition_expiration integer \
project_id:dataset

Substitua:

  • integer: a vida útil padrão, em segundos, das partições nas tabelas particionadas recém-criadas. Esta sinalização não tem valor mínimo. Especifique 0 para remover o prazo de validade atual. Todas as partições nas tabelas particionadas recém-criadas serão excluídas integer segundos após a data UTC da partição. Esse valor será aplicado se você não definir uma validade de partição na tabela quando ela for criada.
  • project_id: o ID do projeto.
  • dataset: o nome do conjunto de dados que você está atualizando.

Exemplos:

Digite o comando a seguir para definir a validade padrão de partições para tabelas particionadas novas criadas em mydataset como 26 horas (93.600 segundos). O conjunto de dados está no projeto padrão.

bq update --default_partition_expiration 93600 mydataset

Digite o comando a seguir para definir a validade padrão de partições para tabelas particionadas novas criadas em mydataset como 26 horas (93.600 segundos). O conjunto de dados está em myotherproject, e não no projeto padrão.

bq update --default_partition_expiration 93600 myotherproject:mydataset

API

Chame datasets.patch e atualize a propriedade defaultPartitionExpirationMs no recurso de conjunto de dados. A validade é expressa em milissegundos. Como o método datasets.update substitui todo o recurso do conjunto de dados, é melhor usar o método datasets.patch.

Como atualizar controles de acesso do conjunto de dados

O processo de atualização dos controles de acesso do conjunto de dados é muito semelhante ao de atribuição. Não é possível aplicar controles de acesso durante a criação do conjunto de dados usando o Console do Cloud ou a ferramenta de linha de comando bq. Você precisa primeiro criar o conjunto e atualizar os controles de acesso dele. Com a API, é possível atualizar os controles de acesso ao conjunto de dados chamando o método datasets.patch.

Ao atualizar os controles de acesso em um conjunto de dados, é possível modificar o acesso das seguintes entidades:

  • 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 a uma conta de serviço o acesso ao conjunto de dados.
  • 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.
  • Visualização autorizada: fornece acesso de visualização ao conjunto de dados.

Para atualizar os controles de acesso em um conjunto de dados:

Console

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

  2. Expanda a opção Ações e clique em Abrir.

  3. Clique em Compartilhar conjunto de dados.

  4. Para excluir as entradas existentes, na caixa de diálogo Compartilhar conjunto de dados, expanda a entrada e clique no ícone de excluir (lixeira).

  5. Na caixa de diálogo Compartilhar conjunto de dados, para adicionar novas entradas:

    1. Insira a entidade na caixa Adicionar membros.

    2. Em Selecionar um papel, escolha um papel adequado do IAM na lista. Para mais informações sobre as permissões atribuídas a cada papel predefinido do BigQuery, consulte a página Papéis e permissões predefinidas.

    3. Clique em Adicionar.

  6. Para adicionar uma visualização autorizada, clique na guia Visualização autorizada e insira o projeto, o conjunto de dados e a visualização. Depois clique em Adicionar.

  7. Quando terminar de adicionar ou excluir os controles de acesso, clique em Concluído.

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 para o arquivo JSON em 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 ou remover qualquer uma das entradas specialGroup: projectOwners, projectWriters, projectReaders e allAuthenticatedUsers. É possível adicionar, remover ou modificar qualquer uma destas opções: 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.

    bq update --source path_to_file project_id:dataset
    

    Substitua:

    • path_to_file: o caminho para o arquivo JSON em 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 atualize a propriedade access no recurso de conjunto de dados.

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 essa amostra, siga as instruções de configuração para 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.

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 essa amostra, siga as instruções de configuração para 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.

Crie uma instância Dataset.Builder a partir de uma instância Dataset atual com o método Dataset.toBuilder(). Configure o objeto de builder do conjunto de dados. Crie o conjunto de dados atualizado com o método Dataset.Builder.build() e chame o método Dataset.update() para enviar a atualização para a API (links em inglês).

Configure os controles de acesso com o método Dataset.Builder.setAcl() (link em inglês).

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 runUpdateDatasetAccess() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    updateDatasetAccess(datasetName);
  }

  public static void updateDatasetAccess(String datasetName) {
    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);

      // 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);

      // 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());
    }
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetAccess() {
  // Updates a datasets's access controls.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Create new role metadata
  const newRole = {
    role: 'READER',
    entity_type: 'userByEmail',
    userByEmail: 'sample.bigquery.dev@gmail.com',
  };

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add new role to role acess array
  metadata.access.push(newRole);
  const [apiResponse] = await dataset.setMetadata(metadata);
  const newAccessRoles = apiResponse.access;
  newAccessRoles.forEach(role => console.log(role));
}

Python

Antes de testar essa 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.
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)
)

Próximas etapas