Trabalhar com metadados de objeto
Há dois tipos de metadados de objeto no Amazon S3: metadados definidos pelo sistema e metadados definidos pelo usuário. Os metadados definidos pelo sistema incluem a data de criação, o tamanho e a classe de armazenamento do objeto, entre outros. Os metadados definidos pelo usuário são metadados que você pode optar por definir no momento do upload de um objeto. Esses metadados definidos pelo usuário são um conjunto de pares de nome/valor. Para obter mais informações, consulte Metadados do objeto definidos pelo sistema e Metadados do objeto definidos pelo usuário.
Ao criar um objeto, você especifica a chave do objeto (ou nome da chave), que identifica exclusivamente o objeto em um bucket do Amazon S3. Para obter mais informações, consulte Nomear objetos do Amazon S3. Você também pode definir metadados definidos pelo usuário no Amazon S3 no momento do upload do objeto.
Após fazer upload do objeto, você não pode mais modificar esses metadados definidos pelo usuário. A única forma de modificar esses metadados é fazer uma cópia do objeto e definir os metadados. Para ter mais informações sobre como editar metadados usando o console do Amazon S3, consulte Editar metadados de objeto no console do Amazon S3.
Consultar os metadados e acelerar a descoberta de dados com o S3 Metadata
Para encontrar, armazenar e consultar facilmente os metadados dos objetos do S3, você pode usar o S3 Metadata. Com o S3 Metadata, você pode preparar dados rapidamente para uso em analytics de negócios, recuperação de conteúdo, treinamento de modelos de inteligência artificial e machine learning (IA/ML) e muito mais.
O S3 Metadata acelera a descoberta de dados ao capturar automaticamente os metadados dos objetos nos buckets de uso geral e armazená-los em tabelas do Apache Iceberg totalmente gerenciadas e somente leitura que você pode consultar. Essas tabelas somente leitura são chamadas de tabelas de metadados. À medida que objetos são adicionados, atualizados e removidos dos buckets de uso geral, o S3 Metadata atualiza automaticamente as tabelas de metadados correspondentes para refletir as alterações mais recentes.
Por padrão, o S3 Metadata fornece metadados de objetos definidos pelo sistema, como o horário de criação e a classe de armazenamento de um objeto, e metadados personalizados, como tags e metadados definidos pelo usuário que foram incluídos durante o upload do objeto. O S3 Metadata também fornece metadados de eventos, como quando um objeto é atualizado ou excluído, e a Conta da AWS que fez a solicitação.
As tabelas de metadados são armazenadas em buckets de tabela do S3, que fornecem armazenamento otimizado para dados tabulares. Para consultar os metadados, você pode integrar o bucket de tabela a serviços de analytics da AWS, como Amazon Athena, Amazon Redshift e Amazon QuickSight.
Para ter mais informações sobre o S3 Metadata, consulte Acelerar a descoberta de dados com o S3 Metadata.
Metadados do objeto definidos pelo sistema
Para cada objeto armazenado em um bucket, o Amazon S3 mantém um conjunto de metadados do sistema. O Amazon S3 processa estes metadados do sistema conforme necessário. Por exemplo, o Amazon S3 mantém a data de criação e o tamanho dos metadados, usando essas informações como parte do gerenciamento de objetos.
Existem duas categorias de metadados de sistema:
-
Controlados pelo sistema: os metadados, como a data de criação do objeto, são controlados pelo sistema, o que significa que somente o Amazon S3 pode modificar o valor da data.
-
Controlados pelo usuário: outros metadados de sistema, como a classe de armazenamento configurada para o objeto e se o objeto tem criptografia habilitada no lado do servidor, são exemplos cujos valores são controlados por você. Se o bucket está configurado como um site, você pode querer redirecionar uma solicitação de página para outra página ou para um URL externo. Nesse caso, uma página é um objeto no bucket. O Amazon S3 armazena o valor do redirecionamento da página como metadados do sistema, que você pode controlar.
Ao criar objetos, você pode configurar os valores desses itens de metadados de sistema ou atualizar os valores quando necessário. Para obter mais informações sobre classes de armazenamento, consulte Compreender e gerenciar classes de armazenamento do Amazon S3.
O Amazon S3 usa chaves AWS KMS para criptografar seus objetos do Amazon S3. O AWS KMS criptografa apenas os dados do objeto. A soma de verificação e o algoritmo especificado são armazenados como parte dos metadados do objeto. Se a criptografia no lado do servidor for solicitada para o objeto, a soma de verificação será armazenada em formato criptografado. Para obter mais informações sobre criptografia no lado do servidor, consulte Proteger dados com criptografia.
nota
O cabeçalho da solicitação PUT é limitado a 8 KB. No cabeçalho da solicitação PUT, os metadados definidos pelo sistema são limitados a 2 KB. O tamanho de metadados definidos pelo sistema é medido pela soma do número de bytes na codificação US-ASCII de cada chave e valor.
A tabela a seguir fornece uma lista dos metadados definidos por sistema e se você pode atualizá-los.
| Nome | Descrição | O usuário pode modificar o valor? |
|---|---|---|
Date |
A data e hora atual. | Não |
Cache-Control |
Um campo de cabeçalho geral usado para especificar políticas de armazenamento em cache. | Sim |
Content-Disposition |
Informações de apresentação do objeto. | Sim |
Content-Length |
O tamanho do objeto em bytes. | Não |
Content-Type |
O tipo do objeto. | Sim |
Last-Modified |
A data de criação do objeto ou data da última modificação, o que aconteceu por último. Para carregamentos fracionados, a data de criação do objeto é a data de início do respectivo carregamento. |
Não |
ETag |
Uma tag de entidade (ETag) que representa uma versão específica de um objeto. Para objetos que não são carregados como um carregamento fracionado e não são criptografados ou são criptografados por criptografia no servidor com chaves gerenciadas pelo Simple Storage Service (Amazon S3) (SSE-S3), a ETag é um resumo MD5 dos dados. | Não |
x-amz-server-side-encryption |
Um cabeçalho que indica se a criptografia do lado do servidor está ativada para o objeto e se essa criptografia está usando as chaves do AWS Key Management Service (AWS KMS) (SSE-KMS) ou usando as chaves de criptografia gerenciadas pelo Amazon S3 (SSE-S3). Para obter mais informações, consulte Proteger os dados usando criptografia do lado do servidor. | Sim |
x-amz-checksum-crc64nvme, x-amz-checksum-crc32, x-amz-checksum-crc32c,
x-amz-checksum-sha1, x-amz-checksum-sha256 |
Cabeçalhos que contêm a soma de verificação ou o resumo do objeto. No máximo um desses cabeçalhos será definido por vez, dependendo do algoritmo de soma de verificação que você instruir o Amazon S3 a usar. Para obter mais informações sobre a escolha do algoritmo de soma de verificação, consulte Verificar a integridade do objeto no Amazon S3. | Não |
x-amz-checksum-type |
O tipo de soma de verificação, que determina como as somas de verificação em nível de parte são combinadas para criar uma soma de verificação em nível de objeto para objetos fracionados. | Sim |
x-amz-version-id |
A versão do objeto. Quando você ativa o versionamento em um bucket, o Amazon S3 atribui um ID de versão aos objetos adicionados ao bucket. Para obter mais informações, consulte Reter várias versões de objetos com o Versionamento do S3. | Não |
x-amz-delete-marker |
Um marcador booliano que indica se o objeto é um marcador de exclusão. Esse marcador é usado somente em buckets com versionamento ativado. | Não |
x-amz-storage-class |
A classe de armazenamento usada para armazenar o objeto. Para obter mais informações, consulte Compreender e gerenciar classes de armazenamento do Amazon S3. | Sim |
x-amz-website-redirect-location |
Um cabeçalho que redireciona solicitações do objeto associado para outro objeto no mesmo bucket ou para um URL externo. Para obter mais informações, consulte (Opcional) Configurar um redirecionamento de uma página da Web. | Sim |
x-amz-server-side-encryption-aws-kms-key-id |
Um cabeçalho que indica o ID da chave do KMS de criptografia simétrica do AWS KMS que foi usada para criptografar o objeto. Esse cabeçalho é usado somente quando o cabeçalho x-amz-server-side-encryption está presente e tem o valor de aws:kms. |
Sim |
x-amz-server-side-encryption-customer-algorithm |
Um cabeçalho que indica se a criptografia do lado do servidor com as chaves de criptografia fornecidas pelo cliente (SSE-C) está ativada. Para obter mais informações, consulte Como usar criptografia do lado do servidor com chaves fornecidas pelo cliente (SSE-C). | Sim |
x-amz-tagging |
O conjunto de etiquetas do objeto. O conjunto de etiquetas deve ser codificado como parâmetros de consulta de URL. | Sim |
Metadados do objeto definidos pelo usuário
Ao fazer upload de um objeto, você também pode atribuir metadados ao objeto. Você fornece essas informações opcionais como um par de nome-valor (valor-chave) quando envia uma solicitação PUT ou POST para criar o objeto. Ao fazer upload de objetos usando a API REST, os nomes de metadados opcionais definidos pelo usuário devem começar com x-amz-meta-, para diferenciá-los de outros cabeçalhos HTTP. Quando você recupera o objeto usando a API REST, o prefixo é retornado. Ao fazer upload de objetos usando a API SOAP, o prefixo não é obrigatório. Quando você recupera o objeto usando SOAP API, o prefixo é removido, independentemente da API que você usou para fazer upload do objeto.
nota
As APIs SOAP 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.
Quando os metadados são recuperados por meio da API REST, o Amazon S3 combina os cabeçalhos que têm o mesmo nome (sem distinção entre letras maiúsculas e minúsculas) em uma lista delimitada por vírgulas. Se alguns metadados contêm caracteres não imprimíveis, eles não são retornados. Em vez disso, o cabeçalho x-amz-missing-meta é retornado com o valor do número de entradas de metadados não imprimíveis. A ação HeadObject recupera metadados de um objeto sem retornar o próprio objeto. Essa operação é útil se você estiver interessado apenas nos metadados de um objeto. Para usar HEAD, você deve ter acesso READ ao objeto. Para obter mais informações, consulte HeadObject na Referência de API do Amazon Simple Storage Service.
Metadados definidos pelo usuário são um conjunto de pares chave-valor. O Amazon S3 armazena chaves de metadados definidas pelo usuário em minúsculas.
O Amazon S3 permite caracteres Unicode arbitrários em seus valores de metadados.
Para evitar problemas relacionados à apresentação desses valores de metadados, é necessário estar em conformidade com o uso de caracteres US-ASCII ao usar REST e UTF-8 ao usar SOAP ou uploads baseados em navegador via POST.
Ao usar caracteres não US-ASCII nos valores de metadados, a string Unicode fornecida é examinada quanto a caracteres não US-ASCII. Os caracteres desses cabeçalhos são decodificados conforme o RFC 2047
Veja um exemplo a seguir.
PUT /Key HTTP/1.1 Host:amzn-s3-demo-bucket.s3.amazonaws.com x-amz-meta-nonascii: ÄMÄZÕÑ S3 HEAD /Key HTTP/1.1 Host:amzn-s3-demo-bucket.s3.amazonaws.com x-amz-meta-nonascii: =?UTF-8?B?w4PChE3Dg8KEWsODwpXDg8KRIFMz?= PUT /Key HTTP/1.1 Host:amzn-s3-demo-bucket.s3.amazonaws.com x-amz-meta-ascii: AMAZONS3 HEAD /Key HTTP/1.1 Host:amzn-s3-demo-bucket.s3.amazonaws.com x-amz-meta-ascii: AMAZONS3
nota
O cabeçalho da solicitação PUT é limitado a 8 KB. No cabeçalho da solicitação PUT, os metadados definidos pelo usuário são limitados a 2 KB. O tamanho de metadados definidos pelo usuário é medido pela soma do número de bytes na codificação UTF-8 de cada chave e valor.
Para obter informações sobre como alterar os metadados do objeto depois do upload criando uma cópia, modificando e substituindo o objeto antigo ou criando outra versão dele, consulte Editar metadados de objeto no console do Amazon S3.
