# Organizar, listar e trabalhar com seus objetos No Amazon S3, você pode usar prefixos para organizar seu armazenamento. Um prefixo é um agrupamento lógico dos objetos em um bucket. O valor do prefixo é semelhante a um nome de diretório que permite que você armazene dados semelhantes em um bucket no mesmo diretório. Quando você faz upload de objetos de maneira programática, é possível usar prefixos para organizar seus dados. No console do Amazon S3, os prefixos são chamados de pastas. Você pode exibir todos os objetos e pastas no console do S3 navegando até um bucket. Você também pode exibir informações sobre cada objeto incluindo propriedades do objeto. Para obter mais informações sobre como listar e organizar seus dados no Amazon S3, consulte os tópicos a seguir. **Topics** + [Organizar objetos usando prefixos](using-prefixes.md) + [Listar chaves de objeto programaticamente](ListingKeysUsingAPIs.md) + [Organizar objetos no console do Amazon S3 usando pastas](using-folders.md) + [Exibir propriedades do objeto no console do Amazon S3](view-object-properties.md) + [Categorizar objetos usando tags](object-tagging.md) # Organizar objetos usando prefixos Você pode usar prefixos para organizar os dados armazenados nos buckets do Amazon S3. Um prefixo é uma string no início do nome da chave do objeto. Um prefixo pode ter qualquer comprimento, sujeito ao comprimento máximo do nome da chave do objeto (1.024 bytes). Você pode pensar nos prefixos como uma forma de organizar seus dados de forma semelhante aos diretórios. No entanto, os prefixos não são diretórios. Pesquisar por prefixo limita os resultados a somente essas chaves que começam com o prefixo especificado. O delimitador faz com que uma operação de lista acumule todas as chaves que compartilham um prefixo comum em um único resultado da lista de resumo. A finalidade dos parâmetros de prefixo e delimitador é ajudá-lo a organizar e navegar, hierarquicamente, por suas chaves. Para fazer isso, escolha primeiro um delimitador para seu bucket, tal como barra (/), que você não prevê que apareça em nomes de chave. Você pode usar outro caractere como um delimitador. Não há nada de especial no caractere barra (/), mas esse um delimitador de prefixo muito comum. Em seguida, crie seus nomes de chave concatenando todos os níveis de contenção de hierarquia, separando cada nível com o delimitador. Por exemplo, se você estava armazenando informações sobre cidades, pode, naturalmente, organizá-las por continente, país, província ou estado. Como esses nomes geralmente não usam pontuação, você pode usar a barra (/) como delimitador. Os seguintes exemplos usam uma barra (/) como delimitador. + Europa/França/Nova Aquitânia/Bordeaux + América do Norte/Canadá/Quebec/Montreal + América do Norte /EUA/Washington/Bellevue + América do Norte /EUA/Washington/Seattle Se você armazenou dados de cada cidade do mundo desta forma, ficaria estranho gerenciar um namespace plano de chave. Usando `Prefix` e `Delimiter` com a operação de lista, você pode usar a hierarquia que criou para listar os dados. Por exemplo, para listar todos os estados nos EUA, defina `Delimiter='/'` e `Prefix='North America/USA/'`. Para listar todas as províncias no Canadá para as quais você tem dados, defina `Delimiter='/'` e `Prefix='North America/Canada/'`. Para obter mais informações sobre delimitadores, prefixos e pastas aninhadas, consulte [Diferença entre prefixos e pastas aninhadas](https://repost.aws/knowledge-center/s3-prefix-nested-folders-difference). ## Listar objetos usando prefixos e delimitadores Se emitir uma solicitação de lista com um delimitador, você poderá pesquisar a hierarquia apenas em um nível, pulando e resumindo as chaves aninhadas (possivelmente milhões) em níveis mais profundos. Por exemplo, suponha que você tenha um bucket (*amzn-s3-demo-bucket*) com as seguintes chaves: `sample.jpg` `photos/2006/January/sample.jpg` `photos/2006/February/sample2.jpg` `photos/2006/February/sample3.jpg` `photos/2006/February/sample4.jpg` O bucket de exemplo tem somente `sample.jpg` o objeto no nível raiz. Para listar somente os objetos no nível raiz no bucket, você envia uma solicitação GET no bucket com o caractere delimitador barra (`/`). Em resposta, o Simple Storage Service (Amazon S3) retorna a chave do objeto `sample.jpg` porque não contém o caractere delimitador `/`. Todas as outras chaves contêm o caractere delimitador. O Simple Storage Service (Amazon S3) agrupa essas chaves e retorna um único elemento `CommonPrefixes` com valor de prefixo `photos/`, que é uma substring que vai do início dessas chaves até a primeira ocorrência do delimitador especificado. **Example** ``` 1. 2. amzn-s3-demo-bucket 3. 4. 5. 1000 6. / 7. false 8. 9. sample.jpg 10. 2011-07-24T19:39:30.000Z 11. "d1a7fb5eab1c16cb4f7cf341cf188c3d" 12. 6 13. 14. 75cc57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a 15. 16. STANDARD 17. 18. 19. photos/ 20. 21. ``` Para obter mais informações sobre como listar chaves de objeto programaticamente, consulte [Listar chaves de objeto programaticamente](ListingKeysUsingAPIs.md). # Listar chaves de objeto programaticamente No Amazon S3, as chaves podem ser listadas por prefixo. Você pode escolher um prefixo comum para os nomes das chaves relacionadas e marcar essas chaves com um caractere especial que delimite a hierarquia. Em seguida, você pode usar a operação de lista para selecionar e procurar chaves hierarquicamente. Isso é semelhante à forma como arquivos são armazenados em diretórios em um sistema de arquivos. O Amazon S3 expõe uma operação de lista que permite a enumeração das chaves contidas em um bucket. As chaves são selecionadas para a listagem pelo bucket e pelo prefixo. Por exemplo, considere um bucket chamado “`dictionary`” que contém uma chave para cada palavra inglesa. Você pode fazer uma chamada para listar todas as chaves no bucket iniciadas com a letra “q”. Os resultados da lista são obtidos sempre em ordem binária UTF-8. As operações de lista SOAP e REST retornam um documento XML que contém nomes de chaves correspondentes e informações sobre o objeto identificado em cada chave. **nota** As APIs SOAP para o Amazon S3 não estão disponíveis para novos clientes e chegam ao fim da vida útil (EOL) em 31 de agosto de 2025. Recomendamos usar a API REST ou os AWS SDKs. Grupos de chaves que compartilham um prefixo terminado por um delimitador especial podem ser rolados para acima pelo prefixo comum para fins de listagem. Isso permite que aplicativos organizem e naveguem por suas chaves hierarquicamente, de maneira muito similar a como você organizaria seus arquivos em diretórios em um sistema de arquivos. Por exemplo, para estender o bucket de dicionário para conter mais do que apenas palavras inglesas, você poderia formar chaves prefixando cada palavra com seu idioma e um delimitador, tal como "`French/logical`". Usando esse esquema de nomeação e o recurso hierárquico de listagem, você poderia recuperar uma lista somente de palavras francesas. Você também poderia pesquisar a parte superior da lista de idiomas sem ter que iterar com todas as chaves de iteração lexicográficas. Para obter mais informações sobre esse aspecto de listagem, consulte [Organizar objetos usando prefixos](using-prefixes.md). **API REST** Se a sua aplicação exigir, você pode enviar solicitações REST diretamente. Você pode enviar uma solicitação GET para retornar alguns ou todos os objetos em um bucket ou pode usar critérios de seleção para obter um subconjunto de objetos em um bucket. Para obter mais informações, consulte [GET Bucket (listar objetos) versão 2](https://docs.aws.amazon.com/AmazonS3/latest/API/v2-RESTBucketGET.html) na *Referência da API do Amazon Simple Storage Service*. **Implementação eficiente de lista** A performance da lista não é substancialmente afetada pelo número total de chaves no bucket. Também não é afetada pela presença ou ausência dos argumentos `prefix`, `marker`, `maxkeys` ou `delimiter`. **Iterar em resultados de várias páginas** Como os buckets podem conter um número praticamente ilimitado de chaves, os resultados completos de uma consulta de lista podem ser muito extensos. Para gerenciar grandes conjuntos de resultados, a API do Amazon S3 é compatível com a paginação para separá-los em várias respostas. Cada resposta de chaves de lista retorna uma página com até 1.000 chaves com um indicador apontando se a resposta está truncada. Você envia uma série de solicitações de chaves de lista até receber todas elas. AWS As bibliotecas wrapper do SDK fornecem a mesma paginação. ## Exemplos Ao listar todos os objetos no bucket, observe que você deve ter a permissão `s3:ListBucket`. ------ #### [ CLI ] **list-objects** O seguinte exemplo usa o comando `list-objects` para exibir os nomes de todos os objetos presentes no bucket especificado: ``` aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}' ``` O exemplo usa o argumento `--query` para filtrar a saída de `list-objects` até encontrar o valor e o tamanho da chave de cada objeto Para obter mais informações sobre objetos, consulte [Trabalhar com objetos no Amazon S3](uploading-downloading-objects.md). + Consulte detalhes da API em [ListObjects](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-objects.html) na *Referência de comandos da AWS CLI*. **ls** O exemplo a seguir lista todos os objetos e prefixos em um bucket usando o comando `ls`. Para usar esse exemplo de comando, substitua **amzn-s3-demo-bucket** pelo nome do seu bucket. ``` $ aws s3 ls s3://amzn-s3-demo-bucket ``` + Consulte mais informações sobre o comando de algo nível `ls` em [List buckets and objects](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-listing-buckets) no *Guia do usuário do AWS Command Line Interface*. ------ #### [ PowerShell ] **Ferramentas para PowerShell V4** **Exemplo 1: este comando recupera as informações sobre todos os itens no bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket ``` **Exemplo 2: este comando recupera as informações sobre o item “sample.txt” do bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt ``` **Exemplo 3: este comando recupera as informações sobre todos os itens com prefixo “sample” do bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample ``` + Para ver detalhes da API, consulte [ListObjects](https://docs.aws.amazon.com/powershell/v4/reference) na *Ferramentas da AWS para PowerShell Cmdlet Reference (V4)*. **Ferramentas para PowerShell V5** **Exemplo 1: este comando recupera as informações sobre todos os itens no bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket ``` **Exemplo 2: este comando recupera as informações sobre o item “sample.txt” do bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt ``` **Exemplo 3: este comando recupera as informações sobre todos os itens com prefixo “sample” do bucket “test-files".** ``` Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample ``` + Para ver detalhes da API, consulte [ListObjects](https://docs.aws.amazon.com/powershell/v5/reference) na *Ferramentas da AWS para PowerShell Cmdlet Reference (V5)*. ------ # Organizar objetos no console do Amazon S3 usando pastas Nos buckets de uso geral do Amazon S3, os objetos são os recursos primários e são armazenados em buckets. Os buckets de uso geral do Amazon S3 têm uma estrutura plana em vez de uma hierarquia como você normalmente veria em um sistema de arquivos. No entanto, para fins de simplicidade organizacional, o console do Amazon S3 oferece suporte ao conceito de *pastas* como meio de agrupar objetos. O console faz isso usando um *prefixo* de nome compartilhado para os objetos agrupados. Em outras palavras, os objetos agrupados têm nomes que começam com uma string comum. Essa string comum, ou prefixo compartilhado, é o nome da pasta. Os nomes de objeto também são chamados de *nomes de chave*. Por exemplo, é possível usar o console para criar uma pasta chamada `photos` em um bucket de uso geral e armazenar um objeto chamado `myphoto.jpg` nela. Em seguida, o objeto é armazenado como o nome da chave `photos/myphoto.jpg`, em que `photos/` é o prefixo. Estes são mais dois exemplos: + Se você tiver três objetos no bucket de uso geral (`logs/date1.txt`, `logs/date2.txt` e `logs/date3.txt`), o console mostrará uma pasta chamada `logs`. Se você abrir a pasta no console, verá três objetos: `date1.txt`, `date2.txt` e `date3.txt`. + Se você tiver um objeto chamado `photos/2017/example.jpg`, o console mostrará uma pasta chamada `photos` que contém a pasta `2017`. A pasta `2017` contém o objeto `example.jpg`. Você pode ter pastas dentro de pastas, mas não buckets dentro de buckets. Você pode carregar e copiar objetos diretamente em uma pasta. As pastas podem ser criadas, excluídas e tornadas públicas, mas não podem ser renomeadas. Os objetos podem ser copiados de uma pasta para outra. **Importante** Quando você cria uma pasta no console do Amazon S3, o S3 cria um objeto de zero byte. Essa chave de objeto é definida como o nome da pasta que você forneceu, com um caractere de barra (`/`) no final. Por exemplo, no console do Amazon S3, se você criar uma pasta chamada `photos` no bucket, o console do Amazon S3 criará um objeto de zero byte com a chave `photos/`. O console cria esse objeto para ser compatível com a ideia de pastas. Além disso, qualquer objeto existente que tenha sido nomeado com um caractere de barra (`/`) no final aparecerá como uma pasta no console do Amazon S3. Por exemplo, um objeto com o nome de chave `examplekeyname/` aparece como uma pasta no console do Amazon S3 e não como um objeto. Caso contrário, ele se comporta como qualquer outro objeto e pode ser visualizado e manipulado por meio da AWS Command Line Interface (AWS CLI), de AWS SDKs ou da API REST. Também não é possível fazer upload de um objeto que tenha um nome de chave com um caractere de barra (`/`) no final usando o console do Amazon S3. No entanto, é possível fazer upload de objetos nomeados com uma barra (`/`) no final usando a AWS Command Line Interface (AWS CLI), os AWS SDKs ou a API REST. Além disso, o console do Amazon S3 não exibe o conteúdo e os metadados dos objetos de pasta da mesma forma que exibe para outros objetos. Quando você usa o console para copiar um objeto nomeado com uma barra (`/`) no final, uma pasta é criada no local de destino, mas os dados e os metadados do objeto não são copiados. Além disso, uma barra (`/`) nos nomes de chave de objeto pode exigir tratamento especial. Para obter mais informações, consulte [Nomear objetos do Amazon S3](object-keys.md). Para criar pastas em buckets de diretório, faça upload de uma pasta. Para obter mais informações, consulte [Fazer upload de objetos em um bucket de diretório](directory-buckets-objects-upload.md). **Topics** + [Criar uma pasta](#create-folder) + [Tornar as pastas públicas](#public-folders) + [Calcular o tamanho da pasta](#calculate-folder) + [Excluir pastas](#delete-folders) ## Criar uma pasta Esta seção descreve como usar o console do Amazon S3 para criar uma pasta. **Importante** Se a política de bucket não permitir o carregamento de objetos para esse bucket sem tags, metadados ou beneficiados da lista de controle de acesso (ACL), você não poderá criar uma pasta usando o procedimento a seguir. Em vez disso, carregue uma pasta vazia e especifique as configurações a seguir na configuração de carregamento. **Para criar uma pasta** 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 no qual você deseja criar uma pasta. 1. Na guia **Objetos**, escolha **Criar pasta**. 1. Insira um nome para a pasta (por exemplo, **favorite-pics**). **nota** Os nomes de pasta estão sujeitos a certas limitações e diretrizes e são considerados parte do nome da chave de um objeto, que é limitado a 1.024 bytes. Para obter mais informações, consulte [Nomear objetos do Amazon S3](object-keys.md). 1. (Opcional) Se a política do bucket exigir que os objetos sejam criptografados com uma chave de criptografia específica, em **Criptografia do lado do servidor**, você deverá escolher **Especificar chave de criptografia** e especificar a mesma chave de criptografia ao criar uma pasta. Caso contrário, a criação da pasta falhará. 1. Selecione **Criar pasta**. ## Tornar as pastas públicas Recomendamos bloquear todo o acesso público às pastas e aos buckets do Amazon S3, a menos que você exija especificamente uma pasta ou um bucket públicos. Ao tornar uma pasta pública, qualquer pessoa na Internet pode visualizar todos os objetos agrupados nessa pasta. No console do Amazon S3, você pode tornar uma pasta pública. Também é possível tornar uma pasta pública criando uma política de bucket que limita o acesso aos dados por prefixo. Para obter mais informações, consulte [Gerenciamento de identidade e acesso para o Amazon S3](security-iam.md). **Atenção** Após tornar uma pasta pública no console do Amazon S3, não será possível torná-la privada novamente. Em vez disso, é necessário definir permissões em cada objeto individual na pasta pública para que o objeto não tenha acesso público. Para obter mais informações, consulte [Configurar ACLs](managing-acls.md). **Topics** + [Criar uma pasta](#create-folder) + [Tornar as pastas públicas](#public-folders) + [Calcular o tamanho da pasta](#calculate-folder) + [Excluir pastas](#delete-folders) ## Calcular o tamanho da pasta Esta seção descreve como usar o console do Amazon S3 para calcular o tamanho de uma pasta. **Como calcular o tamanho de uma pasta** 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 **Buckets de uso geral**, escolha o nome do bucket no qual a pasta está armazenada. 1. Na lista **Objetos**, marque a caixa de seleção ao lado do nome da pasta. 1. Escolha **Actions** (Ações), depois escolha **Calculate total size** (Calcular tamanho total). **nota** Ao sair da página, as informações da pasta (incluindo o tamanho total) não estarão mais disponíveis. É necessário calcular o tamanho total novamente se quiser vê-lo outra vez. **Importante** Quando você usa a ação **Calculate total size** (Calcular tamanho total) em objetos ou pastas especificados em seu bucket, o Amazon S3 calcula o número total de objetos e o tamanho total do armazenamento. No entanto, carregamentos fracionados incompletos ou em andamento e versões anteriores ou desatualizadas não são calculados no número total de objetos ou no tamanho total. Essa ação calcula somente o número total de objetos e o tamanho total da versão atual ou mais recente de cada objeto armazenado no bucket. Por exemplo, se houver duas versões de um objeto em seu bucket, a calculadora de armazenamento no Amazon S3 as contará como apenas um objeto. Como resultado, o número total de objetos que é calculado no console do Amazon S3 pode ser diferente da métrica **Quantidade de objetos** mostrada na funcionalidade Lente de Armazenamento do S3 e do número informado pela métrica `NumberOfObjects` do Amazon CloudWatch. Da mesma forma, o tamanho total do armazenamento também pode ser diferente da métrica **Total Storage** (Armazenamento total) mostrada no S3 Storage Lens e da métrica `BucketSizeBytes` mostrada no CloudWatch. ## Excluir pastas Esta seção explica como usar o console do Amazon S3 para excluir pastas de um bucket do S3. Para obter informações sobre os recursos e a definição de preço do Amazon S3, consulte [Amazon S3](https://aws.amazon.com/s3/). **Para excluir pastas de um bucket do S3** 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 **Buckets de uso geral**, escolha o nome do bucket do qual você deseja excluir pastas. 1. Na lista **Objetos**, marque a caixa de seleção ao lado das pastas e dos objetos que deseja excluir. 1. Escolha **Excluir**. 1. Na página **Excluir objetos**, verifique se os nomes das pastas e dos objetos selecionados para exclusão estão listados em **Objetos especificados**. 1. Na caixa **Delete objects (Excluir objetos)**, insira **delete** e escolha **Delete objects (Excluir objetos)**. **Atenção** Essa ação exclui todos os objetos especificados. Ao excluir pastas, aguarde a conclusão da ação de exclusão antes de adicionar objetos novos à pasta. Caso contrário, os objetos novos também podem ser excluídos. # Exibir propriedades do objeto no console do Amazon S3 Você pode usar o console do Amazon S3 para exibir as propriedades de um objeto, como a classe de armazenamento, as configurações de criptografia, as etiquetas e os metadados. **Para visualizar as propriedades de 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** ou **Buckets de diretórios**. 1. Na lista de buckets, escolha o nome do bucket que contém o objeto. 1. Na lista **Objects (Objetos)**, escolha o nome do objeto do qual você deseja visualizar as propriedades. A **Object overview (Visão geral do objeto)** de seu objeto é aberta. Você pode rolar para baixo para exibir as propriedades do objeto. 1. Na página **Visão geral do objeto**, você pode visualizar ou configurar as propriedades a seguir para o objeto. **nota** Se você alterar as propriedades **Storage Class (Classe de armazenamento)**, **Encryption (Criptografia)** ou **Metadata (Metadados)**, um novo objeto será criado para substituir o antigo. Se o versionamento do S3 estiver habilitado, uma nova versão do objeto será criada e o objeto existente se tornará uma versão mais antiga. A função que altera a propriedade também se torna o proprietário do novo objeto ou (versão do objeto). Para alterar as propriedades **Classe de armazenamento**, **Criptografia** ou **Metadados** de um objeto que tenha tags definidas pelo usuário, é necessário ter a permissão `s3:GetObjectTagging`. Para alterar essas propriedades de um objeto que não tem etiquetas definidas pelo usuário, mas que tem mais de 16 MB, você também precisa ter a permissão `s3:GetObjectTagging`. Se a política do bucket de destino negar a ação `s3:GetObjectTagging`, essas propriedades do objeto serão atualizadas, mas as etiquetas definidas pelo usuário serão removidas do objeto e você receberá um erro. 1. **Storage class (Classe de armazenamento)** – cada objeto no Amazon S3 tem uma classe de armazenamento associada a ela. A classe de armazenamento que você decide usar depende da frequência com que acessa o objeto. A classe de armazenamento padrão de objetos do S3 em buckets de uso geral é STANDARD. A classe de armazenamento padrão de objetos do S3 em buckets de diretório é S3 Express One Zone. Escolha qual classe de armazenamento usar ao fazer upload de um objeto. Para obter mais informações sobre classes de armazenamento, consulte [Compreender e gerenciar classes de armazenamento do Amazon S3](storage-class-intro.md). Para alterar a classe de armazenamento depois de fazer upload de um objeto em um bucket de uso geral, escolha **Classe de armazenamento**. Escolha a classe de armazenamento desejada e **Save (Salvar)**. **nota** Não é possível alterar a classe de armazenamento de objetos em um bucket de diretório. 1. **Server-side encryption settings (Configurações de criptografia no lado do servidor)**: você pode usar a criptografia no lado do servidor para criptografar seus objetos do S3. Para obter mais informações, consulte [Especificação de criptografia no lado do servidor com o AWS KMS (SSE-KMS)](specifying-kms-encryption.md) ou [Especificar a criptografia do lado do servidor com chaves gerenciadas pelo Amazon S3 (SSE-S3)](specifying-s3-encryption.md). 1. **Metadata (Metadados)** – cada objeto no Amazon S3 tem um conjunto de pares de nome-valor que representa seus metadados. Para obter informações sobre como adicionar metadados a um objeto do S3, consulte [Editar metadados de objeto no console do Amazon S3](add-object-metadata.md). 1. **Tags**: você categoriza o armazenamento adicionando tags a um objeto do S3 em um bucket de uso geral. Para obter mais informações, consulte [Categorizar objetos usando tags](object-tagging.md). 1. **Retenção jurídica e retenção do bloqueio de objetos**: você pode impedir que um objeto em um bucket de uso geral seja excluído. Para obter mais informações, consulte [Bloquear objetos com o Bloqueio de Objetos](object-lock.md). # 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); } } } } ``` ------