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.

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 tags anexadas a um conjunto de dados ou visualizar asTags da seção do painel Editar detalhes para um conjunto de dados, você precisa da permissão do IAM bigquery.datasets.listTagBindings.
• 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.

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 tags, consulte Como criar uma tag e Como adicionar valores de tag.

Anexar tags a um conjunto de dados

Depois de criar uma tag, é possível vinculá-la a um conjunto de dados. É 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

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

   Acessar o BigQuery

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

3. Na seção Informações do conjunto de dados, clique em Editar detalhes.

4. Na seção Tags, selecione as tags que você quer adicionar ao conjunto de dados.

   Observação: a seção Tags não ficará visível se você não tiver a permissão bigquery.datasets.listTagBindings.

5. Clique em Save.

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. Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: o local do conjunto de dados

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. Elas não retornam tags herdadas dos recursos pai.

Console

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

   Acessar o BigQuery

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

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

Observação: se você tiver a permissão bigquery.datasets.listTagBindings, mas não as permissões resourcemanager.tagKeys.get e resourcemanager.tagValues.get somente o ID permanente da tag fica visível.

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

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

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

   Acessar o BigQuery

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

3. Na seção Informações do conjunto de dados, clique em Editar detalhes.

4. Na seção Tags, clique em Excluir item ao lado da tag que você quer excluir.

5. Clique em Save.

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 alpha resource-manager tags bindings delete:

gcloud alpha 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 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. Por exemplo, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: o local do conjunto de dados

Anexar tags ao criar uma tabela

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.

3. Na seção Informações do conjunto de dados, clique em Criar tabela.

4. Insira as informações da nova tabela. Para mais detalhes, consulte Criar e usar tabelas.

5. Na seção Tags, selecione as tags que você quer adicionar à nova tabela. Não é possível inserir IDs de tag manualmente nesta etapa. Só é possível selecionar tags do projeto ou da organização.

6. Clique em Criar tabela.

bq

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

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

Substitua:

• SCHEMA: a definição do esquema in-line.
• TAGS: as tags que você está anexando à nova tabela, 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

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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. É possível anexar no máximo 50 tags a uma tabela.

Console

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

   Acessar o BigQuery

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

3. Na guia Detalhes, clique em Editar detalhes.

4. Na seção Tags, selecione as tags que você quer adicionar à tabela. Não é possível inserir IDs de tag manualmente nesta etapa. Só é possível selecionar tags do projeto ou da organização.

5. Clique em Save.

bq

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

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

Substitua:

• TAGS: as tags que você está anexando à tabela, 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.

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

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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

Console

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

   Acessar o BigQuery

2. 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 a tabela.
• DATASET_ID: o ID do conjunto de dados que contém a tabela.
• TABLE_ID: o ID da tabela.

API

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

Remover tags de uma tabela

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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

Console

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

   Acessar o BigQuery

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

3. Na guia Detalhes, clique em Editar detalhes.

4. Na seção Tags, remova as tags que você quer remover da tabela.

5. Clique em Save.

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, separadas 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

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 [e-mail], 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.

1. Crie uma tag com a chave employee_type e o valor intern:

   

2. No console do Google Cloud, abra a página IAM.

   Acessar IAM

3. 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.

4. No menu Papel, selecione Leitor de dados do BigQuery.

5. Clique em Adicionar condição.

6. Nos campos Título e Descrição, insira valores que descrevem a condição de tag do IAM que você quer criar.

7. Na guia Criador de condições, clique em Adicionar.

8. No menu Tipo de condição, selecione Recurso e, em seguida, selecione Tag.

9. No menu Operador, selecione tem valor.

10. 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.

11. Para salvar a condição de tag, clique em Salvar.

12. Para salvar todas as mudanças feitas no painel Editar permissões, clique em Salvar.

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

    gcloud alpha 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.

• Não é possível usar tags de tabela com a API Cloud Resource Manager.

• É possível anexar no máximo 50 tags a um conjunto de dados ou tabela.

• Consultas com caracteres curinga não são aceitas em 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.