# Marcar recursos do Athena com tags Uma tag consiste em uma chave e um valor, ambos definidos por você. Ao marcar um recurso do Athena, você atribui metadados personalizados a ele. Você pode usar etiquetas para categorizar seus recursos da AWS de diferentes formas, como por finalidade, proprietário ou ambiente. No Athena, recursos como grupos de trabalho, catálogos de dados e reservas de capacidade são recursos etiquetáveis. Por exemplo, você pode criar um conjunto de tags para grupos de trabalho na sua conta que ajuda a rastrear os proprietários do grupo de trabalho ou identificar grupos de trabalho por finalidade. Se você também habilitar as tags como tags de alocação de custos no console do Billing and Cost Management, os custos associados à execução de consultas aparecerão em seu Relatório de custos e uso com essa tag de alocação de custos. Recomendamos usar as [práticas recomendadas de marcação com tags](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html) da AWS para criar um conjunto consistente de tags que atenda às necessidades da sua organização. Você pode trabalhar com etiquetas usando o console do Athena ou as operações de API. **Topics** + [Conceitos Básicos de Tags](#tag-basics) + [Restrições de tags](#tag-restrictions) + [Trabalhar com tags para grupos de trabalho](tags-console.md) + [Usar API e operações de tag da AWS CLI](tags-operations.md) + [Usar políticas de controle de acesso do IAM baseadas em tags](tags-access-control.md) ## Conceitos Básicos de Tags Uma etiqueta é um rótulo atribuído a um recurso do Athena. Cada tag consiste de uma chave e um valor opcional, que podem ser definidos. As etiquetas permitem categorizar seus recursos da AWS de maneiras diferentes. Por exemplo, você pode definir um conjunto de tags para os grupos de trabalho da sua conta que ajudem a rastrear o proprietário ou a finalidade de cada grupo de trabalho. É possível adicionar etiquetas ao criar um grupo de trabalho ou catálogo de dados do Athena ou adicionar, editar ou remover etiquetas dele. Você pode editar uma tag no console. Se você usar as operações da API para editar uma tag, remova a tag antiga e adicione uma nova. Caso exclua um recurso, todas as respectivas tags também serão excluídas. O Athena não atribui etiquetas automaticamente aos recursos. É possível editar chaves de tags e valores, e é possível remover as tags de um recurso a qualquer momento. É possível definir o valor de uma tag a uma string vazia, mas não pode configurar o valor de um tag como nula. Não adicione chaves de tag duplicadas ao mesmo recurso. Se você fizer isso, o Athena emitirá uma mensagem de erro. Se você usar a ação **TagResource** para marcar um recurso usando uma chave de tag existente, o novo valor da tag substituirá o valor antigo. No IAM, é possível controlar quais usuários na sua conta da Amazon Web Services têm permissão para criar, editar, remover ou listar etiquetas. Para obter mais informações, consulte [Usar políticas de controle de acesso do IAM baseadas em tags](tags-access-control.md). Para obter uma lista completa de ações de etiqueta do Amazon Athena, consulte os nomes das ações de API na [Referência de API do Amazon Athena](https://docs.aws.amazon.com/athena/latest/APIReference/). Você pode usar tags para faturamento. Para obter mais informações, consulte [Usar etiquetas para faturamento](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html) no *Guia do usuário do Gerenciamento de Faturamento e Custos da AWS*. Para obter mais informações, consulte [Restrições de tags](#tag-restrictions). ## Restrições de tags As tags têm as seguintes restrições: + No Athena, você pode marcar grupos de trabalho, catálogos de dados e reservas de capacidade. Você não pode marcar consultas com tags. + O número máximo de tags por recurso é 50. Para permanecer no limite, revise e exclua tags não utilizadas. + Em todos os recursos, cada chave de tag deve ser exclusiva e possuir apenas um valor. Não adicione chaves de tag duplicadas ao mesmo tempo ao mesmo recurso. Se você fizer isso, o Athena emitirá uma mensagem de erro. Se você marcar um grupo de trabalho usando uma chave de tag existente em uma ação `TagResource` separada, o novo valor da tag substituirá o valor antigo. + O comprimento da chave da tag é de 1-128 caracteres Unicode em UTF-8. + O comprimento do valor da tag é de 0-256 caracteres Unicode em UTF-8. Marcar operações, como adicionar, editar, remover ou listar tags, exigem que você especifique um ARN para o recurso do grupo de trabalho. + O Athena permite usar letras, números, espaços representados em UTF-8 e os seguintes caracteres: \$1 - = . \$1 : / @. + As chaves e os valores de tags diferenciam maiúsculas de minúsculas. + O prefixo `"aws:"` nas chaves de tag é reservado para uso da AWS. Você não pode editar nem excluir chaves de tag com esse prefixo. As tags com esse prefixo não contam contra o limite de tags por recurso. + As etiquetas atribuídas estão disponíveis somente para a sua conta da Amazon Web Services. # Trabalhar com tags para grupos de trabalho Usando o console do Athena, você pode ver quais etiquetas estão em uso por cada grupo de trabalho na sua conta. Você só pode visualizar as tags por grupo de trabalho. Você também pode usar o console do Athena para aplicar, editar ou remover as etiquetas de um grupo de trabalho por vez. Você pode pesquisar grupos de trabalho usando as tags criadas. **Topics** + [Exibir tags para grupos de trabalho individuais](#tags-display) + [Adicionar e excluir tags em um grupo de trabalho individual](#tags-add-delete) ## Exibir tags para grupos de trabalho individuais **Para exibir as etiquetas de um grupo de trabalho individual no console do Athena** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Se o painel de navegação do console não estiver visível, escolha o menu de expansão à esquerda. ![\[Escolha o menu de expansão.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/nav-pane-expansion.png) 1. No menu de navegação, escolha **Workgroups** (Grupos de trabalho) e escolha o grupo de trabalho desejado. 1. Execute um destes procedimentos: + Escolha a guia **Tags**. Se a lista de etiquetas for longa, use a caixa de pesquisa. + Escolha **Edit** (Editar) e, em seguida, role para baixo até a seção **Tags** (Etiquetas). ## Adicionar e excluir tags em um grupo de trabalho individual Você pode gerenciar as tags de um único grupo de trabalho diretamente pela guia **Workgroups (Grupos de trabalho)**. **nota** Se você deseja que os usuários adicionem etiquetas ao criarem um grupo de trabalho no console ou especifiquem etiquetas quando usarem a ação **CreateWorkGroup**, conceda a eles permissões do IAM para as ações **TagResource** e **CreateWorkGroup**. **Para adicionar uma etiqueta ao criar um novo grupo de trabalho** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. No menu de navegação, escolha **Workgroups** (Grupos de trabalho). 1. Escolha **Create workgroup** (Criar grupo de trabalho) e preencha os valores, conforme necessário. Para saber detalhes das etapas, consulte [Criar um grupo de trabalho](creating-workgroups.md). 1. Na seção **Tags** (Etiquetas), adicione uma ou mais etiquetas especificando chaves e valores. Não adicione chaves de tag duplicadas ao mesmo tempo ao mesmo grupo de trabalho. Se você fizer isso, o Athena emitirá uma mensagem de erro. Para obter mais informações, consulte [Restrições de tags](tags.md#tag-restrictions). 1. Ao concluir, escolha **Create workgroup** (Criar grupo de trabalho). **Para adicionar ou editar uma tag a um grupo de trabalho existente** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. No painel de navegação, escolha **Global networks** (Redes globais). 1. Escolha o grupo de trabalho que você deseja modificar. 1. Execute um destes procedimentos: + Escolha a guia **Tags** e escolha **Gerenciar tags**. + Escolha **Edit** (Editar) e, em seguida, role para baixo até a seção **Tags** (Etiquetas). 1. Especifique uma chave e um valor para cada etiqueta. Para obter mais informações, consulte [Restrições de tags](tags.md#tag-restrictions). 1. Escolha **Salvar**. **Para excluir uma tag de um grupo de trabalho individual** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. No painel de navegação, escolha **Global networks** (Redes globais). 1. Escolha o grupo de trabalho que você deseja modificar. 1. Execute um destes procedimentos: + Escolha a guia **Tags** e escolha **Gerenciar tags**. + Escolha **Edit** (Editar) e, em seguida, role para baixo até a seção **Tags** (Etiquetas). 1. Na lista de etiquetas, escolha **Remove** (Remover) para a etiqueta que você quer excluir e, em seguida, escolha **Save** (Salvar). # Usar API e operações de tag da AWS CLI Use as seguintes operações de tag para adicionar, remover ou listar tags em um recurso. **** | solicitações de | CLI | Descrição da ação | | --- | --- | --- | | TagResource | tag-resource | Adicione ou substitua uma ou mais tags no recurso que tem o ARN especificado. | | UntagResource | untag-resource | Exclua uma ou mais tags do recurso que tem o ARN especificado. | | ListTagsForResource | list‑tags‑for‑resource | Liste uma ou mais tags para o recurso que tem o ARN especificado. | **Adicionar tags ao criar um recurso** Para adicionar tags ao criar um grupo de trabalho ou catálogo de dados, use o parâmetro `tags` com as operações `CreateWorkGroup` ou `CreateDataCatalog` da API ou com os comandos AWS CLI ou `create-work-group` da `create-data-catalog`. ## Gerenciar tags por meio de ações da API Os exemplos a seguir mostram como usar ações da API de tags para gerenciar tags em grupos de trabalho e catálogos de dados. Os exemplos estão na linguagem de programação Java. ### Exemplo: TagResource O exemplo a seguir adiciona duas tags ao grupo de trabalho `workgroupA`: ``` List tags = new ArrayList<>(); tags.add(new Tag().withKey("tagKey1").withValue("tagValue1")); tags.add(new Tag().withKey("tagKey2").withValue("tagValue2")); TagResourceRequest request = new TagResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA") .withTags(tags); client.tagResource(request); ``` O exemplo a seguir adiciona duas tags ao catálogo de dados `datacatalogA`: ``` List tags = new ArrayList<>(); tags.add(new Tag().withKey("tagKey1").withValue("tagValue1")); tags.add(new Tag().withKey("tagKey2").withValue("tagValue2")); TagResourceRequest request = new TagResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA") .withTags(tags); client.tagResource(request); ``` **nota** Não adicione chaves de tag duplicadas ao mesmo recurso. Se você fizer isso, o Athena emitirá uma mensagem de erro. Se você marcar um grupo de trabalho usando uma chave de tag existente em uma ação `TagResource` separada, o novo valor da tag substituirá o valor antigo. ### Exemplo: UntagResource O exemplo a seguir remove `tagKey2` do grupo de trabalho `workgroupA`: ``` List tagKeys = new ArrayList<>(); tagKeys.add("tagKey2"); UntagResourceRequest request = new UntagResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA") .withTagKeys(tagKeys); client.untagResource(request); ``` O exemplo a seguir remove `tagKey2` do catálogo de dados `datacatalogA`: ``` List tagKeys = new ArrayList<>(); tagKeys.add("tagKey2"); UntagResourceRequest request = new UntagResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA") .withTagKeys(tagKeys); client.untagResource(request); ``` ### Exemplo: ListTagsForResource O exemplo a seguir lista as tags do grupo de trabalho `workgroupA`: ``` ListTagsForResourceRequest request = new ListTagsForResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA"); ListTagsForResourceResult result = client.listTagsForResource(request); List resultTags = result.getTags(); ``` O exemplo a seguir lista as tags do catálogo de dados `datacatalogA`: ``` ListTagsForResourceRequest request = new ListTagsForResourceRequest() .withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"); ListTagsForResourceResult result = client.listTagsForResource(request); List resultTags = result.getTags(); ``` ## Gerenciar tags usando a AWS CLI Os exemplos a seguir mostram como usar a AWS CLI para criar e gerenciar tags em catálogos de dados. ### Adicionar tags a um recurso: tag-resource O comando `tag-resource` adiciona uma ou mais tags a um recurso especificado. **Sintaxe** `aws athena tag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tags Key=string,Value=string Key=string,Value=string` O parâmetro `--resource-arn` especifica o recurso ao qual as tags são adicionadas. O parâmetro `--tags` especifica uma lista de pares de chave-valor separados por espaço a serem adicionados como tags ao recurso. **Example** O exemplo a seguir adiciona tags ao catálogo de dados `mydatacatalog`. ``` aws athena tag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tags Key=Color,Value=Orange Key=Time,Value=Now ``` Para mostrar o resultado, use o comando `list-tags-for-resource`. Para obter informações sobre como adicionar etiquetas ao usar o comando `create-data-catalog`, consulte [Registrar um catálogo: create-data-catalog](datastores-hive-cli.md#datastores-hive-cli-registering-a-catalog). ### Listar tags de um recurso: list-tags-for-resource O comando `list-tags-for-resource` lista as tags do recurso especificado. **Sintaxe** `aws athena list-tags-for-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name` O parâmetro `--resource-arn` especifica o recurso para o qual as tags são listadas. O exemplo a seguir lista as tags do catálogo de dados `mydatacatalog`. ``` aws athena list-tags-for-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog ``` O resultado de exemplo a seguir está em formato JSON. ``` { "Tags": [ { "Key": "Time", "Value": "Now" }, { "Key": "Color", "Value": "Orange" } ] } ``` ### Remover tags de um recurso: untag-resource O comando `untag-resource` remove as chaves de tag especificadas e seus valores associados do recurso especificado. **Sintaxe** `aws athena untag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tag-keys key_name [key_name ...]` O parâmetro `--resource-arn` especifica o recurso do qual as tags são removidas. O parâmetro `--tag-keys` usa uma lista separada por espaços de nomes de chave. Para cada nome de chave especificado, o comando `untag-resource` remove a chave e seu valor. O exemplo a seguir remove as chaves `Color` e `Time` e seus valores do recurso de catálogo `mydatacatalog`. ``` aws athena untag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tag-keys Color Time ``` # Usar políticas de controle de acesso do IAM baseadas em tags As etiquetas permitem que você escreva uma política do IAM que inclua o bloco `Condition` para controlar o acesso a um recurso com base em suas etiquetas. Esta seção inclui exemplos de políticas de tags para recursos de grupos de trabalho e catálogos de dados. ## Exemplos de política de etiquetas para grupos de trabalho ### Exemplo: política básica de aplicação de tags A seguinte política do IAM permite que você execute consultas e interaja com as etiquetas do grupo de trabalho chamado `workgroupA`: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:ListWorkGroups", "athena:ListEngineVersions", "athena:ListDataCatalogs", "athena:ListDatabases", "athena:GetDatabase", "athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "athena:GetWorkGroup", "athena:TagResource", "athena:UntagResource", "athena:ListTagsForResource", "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:BatchGetQueryExecution", "athena:ListQueryExecutions", "athena:StopQueryExecution", "athena:GetQueryResults", "athena:GetQueryResultsStream", "athena:CreateNamedQuery", "athena:GetNamedQuery", "athena:BatchGetNamedQuery", "athena:ListNamedQueries", "athena:DeleteNamedQuery", "athena:CreatePreparedStatement", "athena:GetPreparedStatement", "athena:ListPreparedStatements", "athena:UpdatePreparedStatement", "athena:DeletePreparedStatement" ], "Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA" } ] } ``` ------ ### Exemplo: bloco de política que nega ações em um grupo de trabalho com base em par de chave e valor de tag As tags associadas a um recurso, como um grupo de trabalho, são chamadas de tags de recurso. As tags de recursos permitem escrever blocos de política, como os seguintes, que negam as ações listadas em qualquer grupo de trabalho marcado com um par de chave-valor como `stack`, `production`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "athena:GetWorkGroup", "athena:UpdateWorkGroup", "athena:DeleteWorkGroup", "athena:TagResource", "athena:UntagResource", "athena:ListTagsForResource", "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:BatchGetQueryExecution", "athena:ListQueryExecutions", "athena:StopQueryExecution", "athena:GetQueryResults", "athena:GetQueryResultsStream", "athena:CreateNamedQuery", "athena:GetNamedQuery", "athena:BatchGetNamedQuery", "athena:ListNamedQueries", "athena:DeleteNamedQuery", "athena:CreatePreparedStatement", "athena:GetPreparedStatement", "athena:ListPreparedStatements", "athena:UpdatePreparedStatement", "athena:DeletePreparedStatement" ], "Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*", "Condition": { "StringEquals": { "aws:ResourceTag/stack": "production" } } } ] } ``` ------ ### Exemplo: bloco de política que restringe solicitações de ação de alteração de tag a tags específicas As tags que são passadas como parâmetros para operações que alteram tags (por exemplo, `TagResource`, `UntagResource` ou `CreateWorkGroup` com tags) são chamadas de tags de solicitação. O seguinte exemplo de bloco de política permite a operação `CreateWorkGroup` apenas se uma das tags passadas tiver a chave `costcenter` e o valor `1`, `2` ou `3`. **nota** Se você deseja permitir que um perfil do IAM especifique as etiquetas como parte de uma operação `CreateWorkGroup`, certifique-se de conceder ao perfil as permissões para as ações `TagResource` e `CreateWorkGroup`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:CreateWorkGroup", "athena:TagResource" ], "Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*", "Condition": { "StringEquals": { "aws:RequestTag/costcenter": [ "1", "2", "3" ] } } } ] } ``` ------ ## Exemplos de políticas de etiquetas para catálogos de dados ### Exemplo: política básica de aplicação de tags A seguinte política do IAM permite interagir com as etiquetas do catálogo de dados chamado `datacatalogA`: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:ListWorkGroups", "athena:ListEngineVersions", "athena:ListDataCatalogs", "athena:ListDatabases", "athena:GetDatabase", "athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "athena:GetWorkGroup", "athena:TagResource", "athena:UntagResource", "athena:ListTagsForResource", "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:BatchGetQueryExecution", "athena:ListQueryExecutions", "athena:StopQueryExecution", "athena:GetQueryResults", "athena:GetQueryResultsStream", "athena:CreateNamedQuery", "athena:GetNamedQuery", "athena:BatchGetNamedQuery", "athena:ListNamedQueries", "athena:DeleteNamedQuery" ], "Resource": [ "arn:aws:athena:us-east-1:123456789012:workgroup/*" ] }, { "Effect": "Allow", "Action": [ "athena:CreateDataCatalog", "athena:GetDataCatalog", "athena:UpdateDataCatalog", "athena:DeleteDataCatalog", "athena:ListDatabases", "athena:GetDatabase", "athena:ListTableMetadata", "athena:GetTableMetadata", "athena:TagResource", "athena:UntagResource", "athena:ListTagsForResource" ], "Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA" } ] } ``` ------ ### Exemplo: bloco de política que nega ações em um grupo de trabalho com base em um par de chave e valor de tag Você pode usar tags de recursos para gravar blocos de política que negam ações específicas em catálogos de dados marcados com pares de chave-valor de tag específicos. O exemplo a seguir nega ações em catálogos de dados que têm o par de chave-valor da tag `stack`, `production`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "athena:CreateDataCatalog", "athena:GetDataCatalog", "athena:UpdateDataCatalog", "athena:DeleteDataCatalog", "athena:GetDatabase", "athena:ListDatabases", "athena:GetTableMetadata", "athena:ListTableMetadata", "athena:StartQueryExecution", "athena:TagResource", "athena:UntagResource", "athena:ListTagsForResource" ], "Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*", "Condition": { "StringEquals": { "aws:ResourceTag/stack": "production" } } } ] } ``` ------ ### Exemplo: bloco de política que restringe solicitações de ação de alteração de tag a tags específicas As tags que são passadas como parâmetros para operações que alteram tags (por exemplo, `TagResource`, `UntagResource` ou `CreateDataCatalog` com tags) são chamadas de tags de solicitação. O seguinte exemplo de bloco de política permite a operação `CreateDataCatalog` apenas se uma das tags passadas tiver a chave `costcenter` e o valor `1`, `2` ou `3`. **nota** Se você deseja permitir que um perfil do IAM especifique as etiquetas como parte de uma operação `CreateDataCatalog`, certifique-se de conceder ao perfil as permissões para as ações `TagResource` e `CreateDataCatalog`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:CreateDataCatalog", "athena:TagResource" ], "Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*", "Condition": { "StringEquals": { "aws:RequestTag/costcenter": [ "1", "2", "3" ] } } } ] } ``` ------