Marcar tabelas e conjuntos de dados

Neste documento, descrevemos como usar tags para aplicar condicionalmente as políticas do Identity and Access Management (IAM) a tabelas e conjuntos de dados do BigQuery.

Uma tag é um par de chave-valor que você pode anexar diretamente a uma tabela ou conjunto de dados ou que uma tabela ou um conjunto de dados pode herdar de outros recursos do Google Cloud. É possível aplicar condicionalmente políticas baseadas em um recurso que tem uma tag específica. Por exemplo, é possível conceder condicionalmente o papel Leitor de dados do BigQuery a um principal em qualquer conjunto de dados com a tag environment:dev.

Para mais informações sobre o uso de tags na hierarquia de recursos do Google Cloud, consulte Visão geral sobre tags.

Para conceder permissões a muitos recursos relacionados do BigQuery ao mesmo tempo, incluindo recursos que ainda não existem, considere usar as Condições do IAM.

Antes de começar

Você precisa conceder papéis do IAM que forneçam aos usuários as permissões necessárias para realizar cada tarefa neste documento. Você também precisa criar chaves e valores de tag para anexar aos recursos.

Permissões necessárias

Para usar tags no BigQuery, é necessário ter as seguintes permissões:

Para anexar uma tag a um conjunto de dados, você precisa da permissão bigquery.datasets.createTagBinding do IAM no conjunto de dados e da permissão resourcemanager.tagValueBindings.create no nível do projeto no valor da tag que você quer anexar.
Para anexar uma tag a uma tabela, você precisa da permissão bigquery.tables.createTagBinding do IAM na tabela e da permissão resourcemanager.tagValueBindings.create no nível do projeto no valor da tag que você quer anexar.
Para remover uma tag de um conjunto de dados, você precisa da permissão bigquery.datasets.deleteTagBinding do IAM no conjunto de dados e a permissão resourcemanager.tagValueBindings.delete no nível do projeto no valor da tag que você quer excluir.
Para remover uma tag de uma tabela, você precisa da permissão bigquery.tables.deleteTagBinding do IAM na tabela e a permissão resourcemanager.tagValueBindings.delete no nível do projeto no valor da tag que você quer excluir.
Para listar as chaves de tag associadas a uma organização ou um projeto pai no painel Editar detalhes de um conjunto de dados ou tabela, você precisa da permissão resourcemanager.tagKeys.list no painel da chave de tag nível pai e a permissão resourcemanager.tagKeys.get para cada chave de tag.
Para listar os valores de tag das chaves associadas a uma organização ou um projeto pai no painel Editar detalhes de um conjunto de dados ou tabela, você precisa da permissão resourcemanager.tagValues.list no nível pai do valor da tag e a permissão resourcemanager.tagValues.get para cada valor.

Se você usa tags com a API Cloud Resource Manager ou a gcloud, você também precisa das seguintes permissões:

Para listar as tags anexadas a um conjunto de dados com a API Cloud Resource Manager ou a gcloud CLI, você precisa do bigquery.datasets.listTagBindings do IAM.
Para listar as tags efetivas para um conjunto de dados, você precisa do argumento bigquery.datasets.listEffectiveTags do IAM.
Para listar as tags anexadas a uma tabela com a API Cloud Resource Manager ou a gcloud CLI, você vai precisar da a permissão do IAM bigquery.tables.listTagBindings.
Para listar as tags efetivas de uma tabela, você precisa do argumento bigquery.tables.listEffectiveTags do IAM.

Os dois papéis predefinidos do IAM incluem todas as permissões necessárias do BigQuery:

Proprietário de dados do BigQuery (roles/bigquery.dataOwner)
Administrador do BigQuery (roles/bigquery.admin)

As permissões do Resource Manager estão incluídas no papel Usuário de tags (roles/resourcemanager.tagUser).

Também é possível usar tags para negar condicionalmente o acesso com políticas do IAM a tabelas e conjuntos de dados do BigQuery (prévia). Para mais informações, consulte Políticas de negação.

Criar chaves e valores de tags

Antes de anexar uma tag, é preciso criá-la e configurar o valor dela. Para criar chaves e valores de tag, consulte Como criar uma tag e Como adicionar valores de tag.

Anexar tags a um conjunto de dados

É possível criar um novo conjunto de dados do BigQuery ao anexar uma tag ou anexar uma tag a um conjunto de dados atual. É possível anexar somente um valor de tag a um conjunto de dados para qualquer chave de tag. É possível anexar no máximo 50 tags a um conjunto de dados.

Console

Para novos conjuntos de dados:

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.
Clique more_vert Ver ações > Criar conjunto de dados.
Em Tags, clique em Selecionar escopo.
Selecione o escopo em que suas tags existem.
Selecione e adicione as tags que você quer acrescentar ao conjunto de dados.
Clique em Criar conjunto de dados.

Para conjuntos de dados atuais:

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Editar detalhes.
Na seção Tags, selecione as tags que você quer adicionar ao conjunto de dados.
Clique em Salvar.

bq

Para novos conjuntos de dados, use a função Comando bq mk --dataset com a flag --add_tags:

bq mk --dataset \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID

Para conjuntos de dados existentes, use o Comando bq update com a flag --add_tags:

bq update \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID

Substitua:

TAG: a tag que você está anexando à nova tabela. Várias tags são separadas por vírgulas. Por exemplo, 556741164180/env:prod,myProject/department:sales. Cada tag precisa ter o nome da chave com namespace e o nome curto do valor.
PROJECT_ID: o ID do projeto em que você está criando um conjunto de dados ou onde um conjunto de dados existente está localizado.
DATASET_ID: o ID do novo conjunto de dados que você está criando, ou o ID de um conjunto de dados existente.

gcloud

Para anexar uma tag a um conjunto de dados usando a linha de comando, crie um recurso de vinculação de tag usando o comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

TAGVALUE_NAME: o ID permanente ou o nome do namespace do valor da tag a ser anexado, como tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
RESOURCE_ID: o ID completo do conjunto de dados, incluindo o nome de domínio da API (//bigquery.googleapis.com/) para identificar o tipo de recurso. Exemplo: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
LOCATION: o local do conjunto de dados

API

Para novos conjuntos de dados, chame a função Método datasets.insert e adicione suas tags ao campo resource_tags.

Para conjuntos de dados existentes, chame primeiro a função Método datasets.get para receber o recurso do conjunto de dados, incluindo o campo resource_tags. Adicione suas tags no campo resource_tags e transmita o recurso do conjunto de dados atualizado usando método datasets.update.

Listar tags anexadas a um conjunto de dados

As etapas a seguir apresentam uma lista de vinculações de tag anexadas diretamente a um conjunto de dados. Eles não retornam tags herdadas dos recursos pai.

Console

No Console do Google Cloud, acesse a página BigQuery.

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

As tags aparecem na seção Informações do conjunto de dados.

bq

Para listar as tags anexadas a um conjunto de dados, use o método comando bq show.

bq show PROJECT_ID:DATASET_ID

Substitua:

PROJECT_ID: o ID do projeto que contém esse conjunto de dados.
DATASET_ID: o ID do conjunto de dados para o qual você quer listar as tags.

gcloud

Para ver uma lista de vinculações de tags anexadas a um recurso, use o comando gcloud resource-manager tags bindings list:

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

RESOURCE_ID: o ID completo do conjunto de dados, incluindo o nome de domínio da API (//bigquery.googleapis.com/) para identificar o tipo de recurso. Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset.
LOCATION: o local do conjunto de dados.

O resultado será assim:

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

API

Chame o Método datasets.get para receber o recurso do conjunto de dados. O recurso do conjunto de dados inclui tags anexadas ao conjunto de dados no campo resource_tags.

Visualizações

Use a visualização INFORMATION_SCHEMA.SCHEMATA_OPTIONS:

Por exemplo, a consulta a seguir mostra todas as tags anexadas a todos os conjuntos de dados de uma região. Esta consulta retorna uma tabela com colunas, incluindo schema_name (os nomes dos conjuntos de dados), option_name (sempre 'tags'), object_type (sempre ARRAY<STRUCT<STRING, STRING>>) e option_value, que contém matrizes de objetos STRUCT que representam tags associadas a cada conjunto de dados. Para conjuntos de dados sem tags atribuídas, a coluna option_value retorna uma matriz vazia.

SELECT * from region-REGION.INFORMATION_SCHEMA.SCHEMATA_OPTIONS
WHERE option_name='tags'

Substitua:

REGION: a região em que seus conjuntos de dados estão localizados.

Remover tags de um conjunto de dados

É possível desanexar uma tag de um recurso excluindo o recurso de vinculação de tags. Para excluir uma tag, primeiro é necessário removê-la.

Console

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Editar detalhes.
Na seção Tags, clique em Excluir item ao lado da tag que você quer excluir.
Clique em Salvar.

bq

Use o comando bq update com a sinalização --remove_tags.

bq update \
    --remove_tags=REMOVED_TAG \
    PROJECT_ID:DATASET_ID

Substitua:

REMOVED_TAG: a tag que você está removendo da tabela. Várias tags são separadas por vírgulas. Aceita apenas chaves sem pares de valor. Por exemplo, 556741164180/env,myProject/department. Cada tag deve ter o nome da chave com namespace.
PROJECT_ID: o ID do projeto que contém seu conjunto de dados.
DATASET_ID: o ID do conjunto de dados do qual remover as tags. .

Como alternativa, para remover todas as tags de um conjunto de dados, use o método comando bq update com a flag --clear_all_tags:

bq update \
    --clear_all_tags
    PROJECT_ID:DATASET_ID

gcloud

Para remover uma tag de um conjunto de dados usando a linha de comando, exclua a vinculação de tag usando o comando gcloud resource-manager tags bindings delete:

gcloud resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

TAGVALUE_NAME: o ID permanente ou o nome do namespace do valor da tag a ser removido ,como tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
RESOURCE_ID: o ID completo do conjunto de dados, incluindo o nome de domínio da API para identificar o tipo de recurso (//bigquery.googleapis.com/). Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset.
LOCATION: o local do conjunto de dados.

API

Chame o método datasets.get para receber o recurso do conjunto de dados, incluindo o campo resource_tags. Remova suas tags do campo resource_tags e transmita o recurso de conjunto de dados atualizado usando o método datasets.update.

Anexar tags ao criar uma tabela

Depois de criar uma tag, você pode anexá-la a uma nova tabela. Só é possível anexar um valor de tag a um conjunto de dados em cada chave de tag. É possível anexar no máximo 50 tags a uma tabela.

Console

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Criar tabela.
Insira as informações da nova tabela. Para mais detalhes, consulte Criar e usar tabelas.
Na seção Tags, selecione as tags que você quer adicionar à nova tabela.
Clique em Criar tabela.

bq

Use o comando bq mk --table com a sinalização --add_tags.

bq mk --table \
    --schema=SCHEMA \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID.TABLE_ID

Substitua:

SCHEMA: a definição do esquema in-line.
TAG: a tag que você está anexando à nova tabela. Várias tags são separadas por vírgulas. Por exemplo, 556741164180/env:prod,myProject/department:sales. Cada tag precisa ter o nome da chave com namespace e o nome curto do valor.
PROJECT_ID: o ID do projeto em que você está criando uma tabela.
DATASET_ID: o ID do conjunto de dados em que você está criando uma tabela.
TABLE_ID: o ID da nova tabela que você está criando.

API

Chame o método tables.insert com um recurso de tabela definido e inclua as tags no campo resource_tags.

Anexar tags a uma tabela

Depois de criar uma tag, você pode anexá-la a uma tabela já existente. Só é possível anexar um valor de tag a uma tabela em cada chave de tag.

Console

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e conjunto de dados e, em seguida, selecione uma tabela.
Na guia Detalhes, clique em Editar detalhes.
Na seção Tags, selecione as tags que você quer adicionar à tabela.
Clique em Salvar.

bq

Use o comando bq update com a sinalização --add_tags.

bq update \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID.TABLE_ID

Substitua:

TAG: a tag que você está anexando à tabela. Várias tags são separadas por vírgulas. Por exemplo, 556741164180/env:prod,myProject/department:sales. Cada tag precisa ter o nome da chave com namespace e o nome curto do valor.
PROJECT_ID: o ID do projeto que contém seus artefatos.
DATASET_ID: o ID do conjunto de dados que contém a tabela.
TABLE_ID: o ID da tabela que você está atualizando.

gcloud

Para anexar uma tag a uma tabela usando a linha de comando, crie um recurso de vinculação de tag usando o comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

TAGVALUE_NAME: o ID permanente ou o nome do namespace do valor da tag a ser anexado, como tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
RESOURCE_ID: o ID completo da tabela, incluindo o nome de domínio da API (//bigquery.googleapis.com/) para identificar o tipo de recurso. Exemplo: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset/my_table.
LOCATION: o local da sua tabela.

API

Chame o método tables.update com um recurso de tabela definido e inclua as tags no campo resource_tags.

Listar tags anexadas a uma tabela

É possível listar as tags anexadas diretamente a uma tabela. Esse processo não lista as tags herdadas dos recursos pai.

Console

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e conjunto de dados e, em seguida, selecione uma tabela.

As tags aparecem na guia Detalhes.

bq

Use o comando bq show e procure a coluna tags. Se não houver tags na tabela, a coluna tags não será exibida.

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

Substitua:

PROJECT_ID: o ID do projeto que contém seus artefatos.
DATASET_ID: o ID do conjunto de dados que contém a tabela.
TABLE_ID: o ID da tabela.

gcloud

Para ver uma lista de vinculações de tags anexadas a um recurso, use o comando gcloud resource-manager tags bindings list:

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

RESOURCE_ID: o ID completo da tabela, incluindo o nome de domínio da API (//bigquery.googleapis.com/) para identificar o tipo de recurso. Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset/my_table.
LOCATION: o local do conjunto de dados.

O resultado será assim:

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

API

Chame o método tables.get com um recurso de tabela definido e procure o campo resource_tags.

Visualizações

Use a visualização INFORMATION_SCHEMA.TABLE_OPTIONS:

Por exemplo, a consulta a seguir mostra todas as tags anexadas a todas as tabelas em um conjunto de dados. Esta consulta retorna uma tabela com colunas, incluindo schema_name (o nome dos conjuntos de dados), option_name (sempre 'tags'), object_type (sempre ARRAY<STRUCT<STRING, STRING>>) e option_value, que contém matrizes de objetos STRUCT que representam tags associadas a cada conjunto de dados. Para tabelas de dados sem tags atribuídas, a coluna option_value retorna uma matriz vazia.

SELECT * from DATASET_ID.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name='tags'

Substitua DATASET_ID pelo ID do conjunto de dados que contém sua tabela.

Remover tags de uma tabela

Para remover uma associação de tag de uma tabela, exclua a vinculação. Para excluir uma tag, primeiro é necessário removê-la.

Console

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery
No painel Explorer, expanda seu projeto e conjunto de dados e, em seguida, selecione uma tabela.
Na guia Detalhes, clique em Editar detalhes.
Na seção Tags, remova as tags que você quer remover da tabela.
Clique em Salvar.

bq

Para remover algumas tags de uma tabela, use o comando bq update com a sinalização --remove_tags:

bq update \
    --remove_tags=TAG_KEYS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Substitua:

TAG_KEYS: as chaves de tag que você está removendo da tabela, separados por vírgulas. Por exemplo, 556741164180/env,myProject/department. Cada chave de tag precisa ter o nome de chave com namespace.
PROJECT_ID: o ID do projeto que contém seus artefatos.
DATASET_ID: o ID do conjunto de dados que contém a tabela.
TABLE_ID: o ID da tabela que você está atualizando.

Para remover todas as tags de uma tabela, use o comando bq update com a sinalização --clear_all_tags:

bq update \
    --clear_all_tags \
    PROJECT_ID:DATASET_ID.TABLE_ID

gcloud

Para remover uma associação de tag de uma tabela usando a linha de comando, exclua a vinculação de tags usando comando gcloud resource-manager tags bindings delete:

gcloud resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Substitua:

TAGVALUE_NAME: o ID permanente ou o nome do namespace do valor da tag a ser excluído, como tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
RESOURCE_ID: o ID completo da tabela, incluindo o nome de domínio da API (//bigquery.googleapis.com/) para identificar o tipo de recurso. Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset/my_table.
LOCATION: o local do conjunto de dados.

API

Chame o método tables.update com um recurso de tabela definido e remova as tags no campo resource_tags. Para remover todas as tags, remova o campo resource_tags.

Excluir tags

Não será possível excluir uma tag se ela for referenciada por um conjunto de dados ou por uma tabela. Exclua todos os recursos atuais de vinculação de tags antes de excluir a chave ou o valor da tag. Para excluir chaves e valores de tags, consulte Como excluir tags.

Exemplo

Digamos que você seja um administrador de uma organização. Todos os seus analistas de dados são membros do grupo analytics@example.com, que tem o papel do IAM de Leitor de dados do BigQuery no projeto userData. Um analista de dados estagiário é contratado e, de acordo com a política da empresa, precisa ter permissão apenas para visualizar o conjunto de dados anonymousData no projeto userData. É possível controlar o acesso dele usando tags.

Crie uma tag com a chave employee_type e o valor intern:
No console do Google Cloud, abra a página IAM.

Acessar IAM
Localize a linha que contém o estagiário a quem você quer restringir o acesso ao conjunto de dados e clique em Editar principal nessa linha.
No menu Papel, selecione Leitor de dados do BigQuery.
Clique em Adicionar condição.
Nos campos Título e Descrição, insira valores que descrevem a condição de tag do IAM que você quer criar.
Na guia Criador de condições, clique em Adicionar.
No menu Tipo de condição, selecione Recurso e, em seguida, selecione Tag.
No menu Operador, selecione tem valor.
No campo Caminho do valor, insira o caminho do valor da tag no formato ORGANIZATION/TAG_KEY/TAG_VALUE. Por exemplo, example.org/employee_type/intern.

Essa condição de tag do IAM restringe o acesso do estagiário aos conjuntos de dados que têm a tag intern.
Para salvar a condição de tag, clique em Salvar.
Para salvar as mudanças feitas no painel Editar permissões, clique em Salvar.

Para anexar o valor da tag intern ao conjunto de dados anonymousData, use a linha de comando para executar o comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
--tag-value=tagValues/4567890123 \
--parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
--location=US

Limitações

As tags de tabela não são compatíveis com tabelas do BigQuery Omni, tabelas em conjuntos de dados ocultos ou tabelas temporárias. Além disso, as consultas entre regiões no BigQuery Omni não usam tags durante verificações de controle de acesso de tabelas em outras regiões.
É possível anexar no máximo 50 tags a um conjunto de dados ou tabela.
As verificações de controle de acesso para consultas de caracteres curinga não consideram acesso condicional concedido a tabelas com tags.
Alguns serviços fora do BigQuery não podem verificar corretamente as condições da tag do IAM. Se a condição da tag for positiva, ou seja, o usuário receberá um papel em um recurso somente se ele tiver uma tag específica, o acesso será negado ao recurso, independentemente das tags anexadas a ele. Se a condição da tag for negativa, ou seja, um usuário recebe um papel em um recurso somente se ele não tiver uma tag específica, a condição da tag não será verificada.

Por exemplo, o Data Catalog não pode verificar as condições da tag do IAM em conjuntos de dados do BigQuery. Suponha que haja uma política condicional do IAM que forneça a um estagiário o Leitor de dados do BigQuery em conjuntos de dados com a tag employee_type=intern. Como essa é uma condição de tag positiva, o estagiário não pode visualizar conjuntos de dados pesquisando no Data Catalog, mesmo que esses conjuntos tenham a tag employee_type=intern. Se a condição da tag fosse alterada para negativa, para que o estagiário só pudesse ver os conjuntos de dados que não têm a tag employee_type=intern, a verificação seria ignorada, e o estagiário poderia ver os conjuntos de dados que normalmente não poderiam acessar no BigQuery.

Prática recomendada: use condições positivas da tag do IAM em vez de negativas para evitar a concessão não intencional de papéis.

A seguir

Para uma visão geral das tags no Google Cloud, consulte Visão geral sobre tags.
Para mais informações sobre como usar tags, consulte Como criar e gerenciar tags.
Para informações sobre como controlar o acesso aos recursos do BigQuery com as condições do IAM, consulte Controlar o acesso com as condições do IAM.