# Categorizar objetos usando tags
Use a marcação de objetos para classificar o armazenamento. Cada tag é um par de chave-valor.
Você pode adicionar tags a objetos novos ao fazer upload deles ou pode adicioná-las aos objetos existentes.
+ Você pode associar até 10 tags a um objeto. As tags associadas a um objeto devem ter chaves de tag exclusivas.
+ Um chave de tag pode ter até 128 caracteres Unicode e os valores de tag podem ter até 256 caracteres Unicode. As tags de objeto do Amazon S3 são representadas internamente em UTF-16. Observe que, em UTF-16, os caracteres utilizam posições de um ou de dois caracteres.
+ As chaves e os valores diferenciam letras maiúsculas de minúsculas.
+ Consulte mais informações sobre restrições de tags em [User-defined tag restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html#allocation-tag-restrictions) no *Guia do usuário do Gerenciamento de Faturamento e Custos da AWS*. Consulte as restrições básicas de tag em [Restrições de tags](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions) no *Guia do usuário do Amazon EC2*.
**Exemplos**
Considere os seguintes exemplos de marcação:
**Example Informação de PHI**
Suponha que um objeto contenha dados de informações de saúde protegidas (PHI). Você pode marcar o objeto usando o par de chave/valor a seguir.
```
PHI=True
```
ou
```
Classification=PHI
```
**Example Arquivos do projeto**
Suponha que você armazene arquivos de projeto em seu bucket do S3. Você pode marcar esses objetos com uma chave denominada `Project` e um valor, como mostrado a seguir.
```
Project=Blue
```
**Example Várias tags**
Você pode adicionar várias tags a um objeto, como mostrado a seguir.
```
Project=x
Classification=confidential
```
**Prefixos e tags de nome de chave**
Os prefixos de nome da chave do objeto também permitem categorizar o armazenamento. No entanto, a categorização baseada em prefixo é unidimensional. Considere os seguintes nomes de chave de objeto:
```
photos/photo1.jpg
project/projectx/document.pdf
project/projecty/document2.pdf
```
Esses nomes de chave têm os prefixos `photos/`, `project/projectx/` e `project/projecty/`. Esses prefixos habilitam a classificação de uma dimensão. Isto é, tudo que tiver um prefixo pertencerá a uma categoria. Por exemplo, o prefixo `project/projectx` identifica todos os documentos relacionados ao projeto x.
Com a marcação, você agora tem outra dimensão. Se você quiser que photo1 esteja na categoria projeto x, poderá marcar o objeto conforme necessário.
**Benefícios adicionais**
Além de classificação de dados, a marcação oferece benefícios como os seguintes:
+ As tags de objeto permitem ter controle de acesso de permissões. Por exemplo, você pode conceder a um usuário permissões a objetos somente leitura com etiquetas específicas.
+ As tags de objeto permitem o gerenciamento de ciclo de vida do objeto em que você pode especificar um filtro com base em tag, além de um prefixo de nome da chave, em uma regra de ciclo de vida.
+ Ao usar a análise do Amazon S3, você pode configurar filtros para agrupar objetos para análise por tags de objeto, prefixo de nome da chave ou ambos, prefixo e tags.
+ Você também pode personalizar métricas do Amazon CloudWatch para exibir informações por filtros de tag específicos. As seguintes seções fornecem detalhes.
**Importante**
É aceitável usar tags para identificar objetos que contêm dados confidenciais, como informações de identificação pessoal (PII) ou informações de saúde protegidas (PHI). No entanto, as próprias tags não devem conter nenhuma informação confidencial.
**Adição de conjuntos de tags de objeto a vários objetos do Amazon S3 com uma única solicitação**
Para adicionar conjuntos de tags de objeto a mais de um objeto do Amazon S3 com uma única solicitação, você pode usar operações em lote do S3. Você fornece às operações em lote do S3 uma lista de objetos nos quais operar. O S3 Batch Operations chama a respectiva operação de API para executar a operação especificada. Um único trabalho de operações em lote pode realizar a operação especificada em bilhões de objetos contendo exabytes de dados.
O recurso S3 Batch Operations rastreia o progresso, envia notificações e armazena um relatório de conclusão detalhado de todas as ações, fornecendo uma experiência totalmente gerenciada, auditável e sem servidor. É possível usar as operações em lote do S3 por meio do console do Amazon S3, da AWS CLI, de AWS SDKs ou da API REST. Para obter mais informações, consulte [Conceitos básicos sobre operações em lote do S3](batch-ops.md#batch-ops-basics).
Para obter mais informações sobre tags de objeto, consulte [Gerenciar tags de objeto](tagging-managing.md).
## Operações de API relacionadas à marcação de objetos
O Amazon S3 oferece suporte às seguintes operações de API que são especificamente para marcação de objetos:
**Operações de API do objeto**
+ [Atribuição de tags de objeto PUT](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTtagging.html): Substitui tags em um objeto. Especifique tags no corpo de solicitação. Há dois cenários distintos de gerenciamento de tags de objeto usando essa API.
+ O objeto não tem tags – Usando essa API, você pode adicionar um conjunto de tags a um objeto (o objeto não tem nenhuma tag anterior).
+ O objeto tem um conjunto de tags existentes – Para modificar o conjunto de tags existente, você deve primeiro recuperar o conjunto de tags existente, modificá-lo no lado do cliente e usar essa API para substituir o conjunto de tags.
**nota**
Se você enviar essa solicitação com o conjunto de tags vazio, o Amazon S3 excluirá o conjunto de tags existente no objeto. Se você usar esse método, será cobrado por uma solicitação de nível 1 (PUT). Para obter mais informações, consulte [Definição de preço do Amazon S3](https://d0.awsstatic.com/whitepapers/aws_pricing_overview.pdf).
A solicitação de [Atribuição de tags de objeto DELETE](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html) é preferível, pois atinge o mesmo resultado sem incorrer em cobranças.
+ [Atribuição de tags de objeto GET](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html): retorna o conjunto de tags associado a um objeto. O Amazon S3 retorna tags de objetos no corpo da resposta.
+ [Atribuição de tags de objeto DELETE](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html): exclui o conjunto de tags associado a um objeto.
**Outras operações de API que oferecem suporte à atribuição de tags**
+ [Objeto PUT](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html) e [Iniciar multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/API/mpUploadInitiate.html): você pode especificar tags ao criar objetos. Especifique tags usando o cabeçalho de solicitação `x-amz-tagging`.
+ [Objeto GET](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html): em vez de retornar o conjunto de tags, o Amazon S3 retorna a contagem de tags de objeto no cabeçalho `x-amz-tag-count` (somente se o solicitante tiver permissões para ler tags) porque o tamanho de resposta do cabeçalho está limitado a 8 KB. Caso queira ver as tags, faça outra solicitação para a operação de API [Atribuição de tags de objeto GET](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html).
+ [Objeto POST](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html): você pode especificar tags na solicitação POST.
Contanto que as tags na solicitação não ultrapassem o limite de tamanho de cabeçalho de solicitações HTTP de 8 KB, você pode usar a `PUT Object `API para criar objetos com tags. Se as tags especificadas ultrapassarem o limite de tamanho do cabeçalho, você poderá usar esse método POST para incluir as tags no corpo.
[Objeto PUT - Copiar](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectCOPY.html): você pode especificar a `x-amz-tagging-directive` na solicitação para instruir o Amazon S3 a copiar (comportamento padrão) as tags ou substituir as tags por um novo conjunto de tags fornecido na solicitação.
Observe o seguinte:
+ A atribuição de tags de objetos do S3 é muito consistente. Para obter mais informações, consulte [Modelo de consistência de dados do Amazon S3](Welcome.md#ConsistencyModel).
## Configurações adicionais
Esta seção explica como a marcação de objetos está relacionada a outras configurações.
### Marcação de objetos e gerenciamento do ciclo de vida
Na configuração de ciclo de vida de bucket, você pode especificar um filtro para selecionar um subconjunto de objetos ao qual a regra se aplica. Você pode especificar um filtro com base em prefixos de nome de chave, em tags de objeto ou em ambos.
Suponha que você armazene fotos (brutas e no formato concluído) no bucket do Amazon S3. Você pode marcar esses objetos como mostrado a seguir.
```
phototype=raw
or
phototype=finished
```
Você pode considerar a possibilidade de arquivar as fotos brutas no Amazon Glacier um pouco depois de criá-las. Você pode configurar uma regra de ciclo de vida com um filtro que identifica o subconjunto de objetos com o prefixo de nome de chave (`photos/`) que têm uma tag específica (`phototype=raw`).
Para obter mais informações, consulte [Gerenciar o ciclo de vida dos objetos](object-lifecycle-mgmt.md).
### Marcação e replicação de objetos
Se você tiver configurado a replicação no bucket, o Amazon S3 replicará as tags, contanto que você conceda permissão ao Amazon S3 para ler as tags. Para obter mais informações, consulte [Visão geral da configuração da replicação em tempo real](replication-how-setup.md).
### Notificações de evento de marcação de objetos
É possível configurar uma notificação de evento do Amazon S3 para receber um aviso quando uma etiqueta de objeto for adicionada ou excluída de um objeto. O tipo de evento `s3:ObjectTagging:Put` notifica você quando ocorre PUT de uma etiqueta em um objeto ou quando uma etiqueta existente é atualizada. O tipo de evento `s3:ObjectTagging:Delete` notifica você quando uma etiqueta é removida de um objeto. Para obter mais informações, consulte [Habilitar notificações de eventos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-enable-disable-notification-intro.html).
Para obter mais informações sobre a marcação de objetos, consulte os seguintes tópicos:
**Topics**
+ [
## Operações de API relacionadas à marcação de objetos
](#tagging-apis)
+ [
## Configurações adicionais
](#tagging-other-configs)
+ [
# Marcação e políticas de controle de acesso
](tagging-and-policies.md)
+ [
# Gerenciar tags de objeto
](tagging-managing.md)
# Marcação e políticas de controle de acesso
Você também pode usar políticas de permissões (políticas de bucket e de usuário) para gerenciar permissões relacionadas à atribuição de tags de objetos. Para ver ações de política, consulte os seguintes tópicos:
+ [Operações com objetos](security_iam_service-with-iam.md#using-with-s3-actions-related-to-objects)
+ [Operações de buckets](security_iam_service-with-iam.md#using-with-s3-actions-related-to-buckets)
As tags de objeto permitem ter controle de acesso para gerenciar permissões. Você pode conceder permissões condicionais com base em tags de objeto. O Amazon S3 oferece suporte às seguintes chaves de condição que podem ser usadas para conceder permissões condicionais com base em tags de objeto:
+ `s3:ExistingObjectTag/` – Use esta chave de condição para verificar se uma tag de objeto existente tem a chave e o valor de tag específicos.
**nota**
Para conceder permissões para as operações `PUT Object` e `DELETE Object`, não é permitido usar essa chave de condição. Isto é, você não pode criar uma política para conceder ou negar permissões de usuário para excluir ou substituir um objeto existente com base nas tags existentes.
+ `s3:RequestObjectTagKeys` – Use esta chave de condição para restringir as chaves de tag que deseja permitir em objetos. Isso é útil para adicionar tags a objetos usando as solicitações PutObjectTagging e PutObject e de POST objeto.
+ `s3:RequestObjectTag/` – Use esta chave de condição para restringir as chaves e os valores de tag que deseja permitir em objetos. Isso é útil para adicionar tags a objetos usando as solicitações PutObjectTagging e PutObject e de bucket POST.
Para obter uma lista completa de chaves de condição específicas de serviço do Amazon S3, consulte [Exemplos de políticas de bucket usando chaves de condição](amazon-s3-policy-keys.md). As seguintes políticas de permissões ilustram como a marcação de objetos permite gerenciar permissões de acesso.
**Example 1: Permitir que um usuário leia somente os objetos que têm a chave e o valor de uma etiqueta específica**
A política de permissões a seguir limita a capacidade de leitura dos usuários para que leiam somente objetos que tenham a chave e o valor da tag `environment: production`. Essa política usa a chave de condição `s3:ExistingObjectTag` para especificar a chave e o valor da etiqueta.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/JohnDoe"
]
},
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:GetObjectVersion"],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Condition": {
"StringEquals":
{"s3:ExistingObjectTag/environment": "production"}
}
}
]
}
```
**Example 2: Restringir quais chaves de etiqueta de objeto os usuários podem adicionar**
A política de permissões a seguir concede ao usuário permissões para executar a ação `s3:PutObjectTagging`, que permite que o usuário adicione tags a um objeto existente. A condição usa a chave de condição `s3:RequestObjectTagKeys` para especificar as chaves de etiqueta permitidas, como `Owner` ou `CreationDate`. Para obter mais informações, consulte [Criar uma condição que testa vários valores de chave](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_multi-value-conditions.html) no *Guia do usuário do IAM*.
A política garante que cada chave de etiqueta especificada na solicitação seja uma chave de etiqueta autorizada. O qualificador `ForAnyValue` na condição garante que pelo menos uma das chaves especificadas esteja presente na solicitação.
****
```
{
"Version":"2012-10-17",
"Statement": [
{"Principal":{"AWS":[
"arn:aws:iam::111122223333:role/JohnDoe"
]
},
"Effect": "Allow",
"Action": [
"s3:PutObjectTagging"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*"
],
"Condition": {"ForAnyValue:StringEquals": {"s3:RequestObjectTagKeys": [
"Owner",
"CreationDate"
]
}
}
}
]
}
```
**Example 3: Exigir a chave e o valor de uma etiqueta específica ao permitir que os usuários adicionem etiquetas de objeto**
O exemplo de política a seguir concede ao usuário permissão para executar a ação `s3:PutObjectTagging`, que permite que o usuário adicione etiquetas a um objeto existente. A condição requer que o usuário inclua uma chave de etiqueta específica (como `Project`) com o valor definido como `X`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{"Principal":{"AWS":[
"arn:aws:iam::111122223333:user/JohnDoe"
]
},
"Effect": "Allow",
"Action": [
"s3:PutObjectTagging"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*"
],
"Condition": {"StringEquals": {"s3:RequestObjectTag/Project": "X"
}
}
}
]
}
```
# Gerenciar tags de objeto
Esta seção explica como você pode gerenciar tags de objeto usando os AWS SDKs for Java e .NET ou o console do Amazon S3.
A marcação de objetos é uma forma de categorizar o armazenamento nos buckets de uso geral. Cada tag é um par de valores chave que segue as regras a seguir:
+ Você pode associar até 10 tags a um objeto. As tags associadas a um objeto devem ter chaves de tag exclusivas.
+ Um chave de tag pode ter até 128 caracteres Unicode e os valores de tag podem ter até 256 caracteres Unicode. As tags de objeto do Amazon S3 são representadas internamente em UTF-16. Observe que, em UTF-16, os caracteres utilizam posições de um ou de dois caracteres.
+ As chaves e os valores diferenciam letras maiúsculas de minúsculas.
Para obter mais informações sobre tags de objeto, consulte [Categorizar objetos usando tags](object-tagging.md). Para obter mais informações sobre restrições de tags, consulte [Restrições de tags definidas pelo usuário](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) no *Manual do usuário do Gerenciamento de Faturamento e Custos da AWS*.
## Uso do console do S3
**Para adicionar tags a um objeto**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. No painel de navegação à esquerda, escolha **Buckets de uso geral**.
1. Na lista de buckets, escolha o nome do bucket que contém o objeto.
1. Marque a caixa de seleção à esquerda dos nomes dos objetos que você quer alterar.
1. No menu **Actions** (Ações), escolha **Edit** (Editar).
1. Revise os objetos listados e escolha **Add tags** (Adicionar tags).
1. Cada tag de objeto é um par de chave-valor. Insira uma **Key (Chave)** e um **Value (Valor)**. Para adicionar outra tag, escolha **Add Tag (Adicionar tag)**.
Você pode digitar até 10 tags para um objeto.
1. Selecione **Save changes**.
O Amazon S3 adiciona as tags aos objetos especificados.
Para obter mais informações, consulte também [Exibir propriedades do objeto no console do Amazon S3](view-object-properties.md) e [Fazer upload de objetos](upload-objects.md) neste guia.
## Uso da SDKs AWS
------
#### [ Java ]
Para gerenciar tags de objeto usando o AWS SDK para Java, você pode definir tags para um novo objeto e recuperar ou substituir tags referentes a um objeto existente. Para obter mais informações sobre marcação de objetos, consulte [Categorizar objetos usando tags](object-tagging.md).
Faça upload de um objeto em um bucket e defina etiquetas usando um S3Client. Para ver exemplos, consulte [Upload an object to a bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObject_section.html) na *Referência de API do Amazon S3*.
------
#### [ .NET ]
O exemplo a seguir mostra como usar o AWS SDK para .NET para definir as tags para um objeto novo e recuperar ou substituir as tags para um objeto existente. Para obter mais informações sobre marcação de objetos, consulte [Categorizar objetos usando tags](object-tagging.md).
Para obter informações sobre como configurar e executar exemplos de código, consulte [Conceitos básicos do AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) no *Guia do desenvolvedor do AWS SDK for .NET*.
```
using Amazon;
using Amazon.S3;
using Amazon.S3.Model;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
namespace Amazon.DocSamples.S3
{
public class ObjectTagsTest
{
private const string bucketName = "*** bucket name ***";
private const string keyName = "*** key name for the new object ***";
private const string filePath = @"*** file path ***";
// Specify your bucket region (an example region is shown).
private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2;
private static IAmazonS3 client;
public static void Main()
{
client = new AmazonS3Client(bucketRegion);
PutObjectWithTagsTestAsync().Wait();
}
static async Task PutObjectWithTagsTestAsync()
{
try
{
// 1. Put an object with tags.
var putRequest = new PutObjectRequest
{
BucketName = bucketName,
Key = keyName,
FilePath = filePath,
TagSet = new List{
new Tag { Key = "Keyx1", Value = "Value1"},
new Tag { Key = "Keyx2", Value = "Value2" }
}
};
PutObjectResponse response = await client.PutObjectAsync(putRequest);
// 2. Retrieve the object's tags.
GetObjectTaggingRequest getTagsRequest = new GetObjectTaggingRequest
{
BucketName = bucketName,
Key = keyName
};
GetObjectTaggingResponse objectTags = await client.GetObjectTaggingAsync(getTagsRequest);
for (int i = 0; i < objectTags.Tagging.Count; i++)
Console.WriteLine("Key: {0}, Value: {1}", objectTags.Tagging[i].Key, objectTags.Tagging[i].Value);
// 3. Replace the tagset.
Tagging newTagSet = new Tagging();
newTagSet.TagSet = new List{
new Tag { Key = "Key3", Value = "Value3"},
new Tag { Key = "Key4", Value = "Value4" }
};
PutObjectTaggingRequest putObjTagsRequest = new PutObjectTaggingRequest()
{
BucketName = bucketName,
Key = keyName,
Tagging = newTagSet
};
PutObjectTaggingResponse response2 = await client.PutObjectTaggingAsync(putObjTagsRequest);
// 4. Retrieve the object's tags.
GetObjectTaggingRequest getTagsRequest2 = new GetObjectTaggingRequest();
getTagsRequest2.BucketName = bucketName;
getTagsRequest2.Key = keyName;
GetObjectTaggingResponse objectTags2 = await client.GetObjectTaggingAsync(getTagsRequest2);
for (int i = 0; i < objectTags2.Tagging.Count; i++)
Console.WriteLine("Key: {0}, Value: {1}", objectTags2.Tagging[i].Key, objectTags2.Tagging[i].Value);
}
catch (AmazonS3Exception e)
{
Console.WriteLine(
"Error encountered ***. Message:'{0}' when writing an object"
, e.Message);
}
catch (Exception e)
{
Console.WriteLine(
"Encountered an error. Message:'{0}' when writing an object"
, e.Message);
}
}
}
}
```
------