Anotação de objetos
Use anotações para anexar cargas úteis de dados nomeados aos objetos do Amazon S3. Cada anotação é uma carga útil de metadados personalizados entre 1 byte e 1 MiB de tamanho que você pode criar, recuperar, listar e excluir sem modificar o objeto em si.
Você pode associar até 1.000 anotações a uma versão do objeto. Cada anotação tem um nome exclusivo e pode armazenar dados estruturados, como rótulos gerados por IA, contexto de documentos, resultados de processamento ou registros de conformidade.
Os casos de uso comuns incluem armazenar resultados de inferência de machine learning, incorporações geradas por IA, rótulos de moderação de conteúdo, saída de classificação de documentos, linhagem de dados e trilhas de auditoria, rótulos de conformidade, como sinalizadores de PII ou políticas de retenção, metadados de imagens médicas, informações sobre direitos de ativos digitais e status do pipeline de ETL junto com o objeto de origem.
Como você gerencia anotações usando operações de API dedicadas, não precisa recarregar o objeto para adicionar ou atualizar metadados.
Você pode ativar uma tabela de anotação como parte da configuração do S3 Metadata para consultar dados de anotação em grande escala usando o Athena e outros serviços de análise. O S3 Metadata armazena dados de anotações em tabelas do Apache Iceberg totalmente gerenciadas que o Amazon S3 mantém atualizadas automaticamente. Para obter mais informações, consulte Descobrir seus dados com tabelas do S3 Metadata.
As anotações estão disponíveis em todas as regiões da AWS comerciais e regiões da China (Pequim e Ningxia). As anotações não estão disponíveis nas regiões Oriente Médio (EAU) e Oriente Médio (Bahrein). As tabelas de anotação do S3 Metadata estão disponíveis em todas as regiões em que o S3 Metadata está disponível.
Quando usar anotações e tags de objeto
Use a comparação a seguir para determinar se as anotações ou as tags de objeto são as mais adequadas para seu caso de uso.
| Característica | Tags de objeto | Anotações |
|---|---|---|
| Máximo por objeto | 10 por versão do objeto | 1.000 por versão do objeto |
| Tamanho máximo | 128 caracteres (chave) + 256 caracteres (valor) | 512 bytes (nome) + 1 MiB (carga útil) |
| Formato de dados | Pares de string de chave-valor | Qualquer texto UTF-8 (JSON, XML, YAML etc.) |
| Mutabilidade | Sim (PutObjectTagging) | Sim (PutObjectAnnotation) |
| Definir durante o upload | Sim (PutObject, POST) | Não (somente PutObjectAnnotation, após o upload) |
Escolha anotações quando precisar armazenar dados estruturados (como JSON ou XML), cargas úteis com mais de 256 caracteres ou mais de 10 entradas de metadados por objeto. Escolha tags de objeto quando precisar de integração de políticas do IAM, filtragem de regras de ciclo de vida do Amazon S3 ou relatórios de alocação de custos.
Operações de API para anotações
O Amazon S3 oferece suporte às seguintes operações de API para trabalhar com anotações:
-
PutObjectAnnotation: cria ou substitui uma anotação em um objeto. Você especifica o nome da anotação e a carga útil na solicitação.
-
GetObjectAnnotation: retorna a carga útil de uma anotação específica por nome.
-
ListObjectAnnotations: retorna a lista de anotações em um objeto. A resposta inclui nome, tamanho, ETag e data da última modificação de cada anotação.
-
DeleteObjectAnnotation: remove uma anotação específica por nome.
O Amazon S3 também oferece suporte às seguintes operações de API:
-
CopyObject: copia anotações do objeto de origem por padrão. Você pode especificar o cabeçalho
x-amz-annotation-directivepara controlar se as anotações são copiadas (COPY) ou excluídas (EXCLUDE). -
UpdateBucketMetadataAnnotationTableConfiguration: ativa ou desativa a tabela de anotação na configuração do S3 Metadata.
-
CreateBucketMetadataConfiguration: aceita um novo parâmetro
AnnotationTableConfigurationpara ativar tabelas de anotação ao criar uma configuração do S3 Metadata. -
GetBucketMetadataConfiguration: retorna
AnnotationTableConfigurationResultna resposta, que indica o status atual da tabela de anotação.
Limites de anotação
Cada versão do objeto oferece suporte a até 1.000 anotações. As anotações associadas a uma versão do objeto devem ter nomes exclusivos. Os limites a seguir se aplicam ao seguinte:
-
O nome de uma anotação pode ter até 512 bytes de comprimento (UTF-8), sujeito às regras de nomenclatura abaixo.
-
A carga útil de uma anotação deve ter entre 1 byte e 1 MiB de tamanho.
-
O armazenamento total de anotações por objeto pode ter até 1 GiB (1.000 anotações com 1 MiB cada).
-
Algoritmos de soma de verificação compatíveis: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Regras de nomenclatura de anotações
Os nomes de anotação devem satisfazer os seguintes requisitos:
-
Devem ter entre 1 e 512 bytes de comprimento.
-
Podem conter somente os seguintes caracteres: letras (qualquer idioma), dígitos (0-9), sublinhado (
_), ponto (.) e hífen (-). -
Não podem começar com
awsous3(não diferenciar maiúsculas de minúsculas). Por exemplo,aws,AWS,s3eS3são prefixos reservados. -
Não devem estar vazios nem consistir apenas em espaços em branco.
Criptografia
As anotações são criptografadas automaticamente em repouso usando a mesma configuração de criptografia do objeto pai. O tipo de criptografia é herdado do objeto pai, não do bucket padrão.
-
SSE-S3: se o objeto pai usar criptografia do lado do servidor com chaves gerenciadas pelo Amazon S3 (SSE-S3), as anotações serão criptografadas com SSE-S3. Se o objeto pai não tiver criptografia do lado do servidor configurada, as anotações serão criptografadas com SSE-S3 por padrão.
-
SSE-KMS: se o objeto pai usar criptografia do lado do servidor com chaves do AWS KMS (SSE-KMS), as anotações serão criptografadas com a mesma chave do KMS. Isso se aplica a chaves gerenciadas pelo cliente e pela AWS. Há suporte para chaves de bucket do S3.
-
DSSE-KMS: se o objeto pai usar criptografia de camada dupla do lado do servidor com chaves do AWS KMS (DSSE-KMS), as anotações serão criptografadas com DSSE-KMS usando a mesma chave.
-
SSE-C: a criptografia no lado do servidor com chaves fornecidas pelo cliente (SSE-C) não é compatível com anotações. Se você tentar adicionar uma anotação a um objeto criptografado com SSE-C, o Amazon S3 retornará um erro.
Somas de verificação
Ao fazer upload de uma anotação usando PutObjectAnnotation, você pode fornecer uma soma de verificação para verificar a integridade dos dados. O algoritmo de soma de verificação de uma anotação é independente do algoritmo de soma de verificação do objeto pai.
Ao copiar um objeto usando CopyObject, o Amazon S3 preserva os valores da soma de verificação da anotação na origem. Se você especificar um algoritmo de soma de verificação diferente na solicitação de cópia, o novo algoritmo se aplicará tanto ao objeto quanto às anotações.
Algoritmos compatíveis: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Se a anotação não tiver um algoritmo ou valor de soma de verificação especificado, o Amazon S3 usará o algoritmo CRC-64/NVME para calcular o valor da soma de verificação para a anotação.
Comportamento de versionamento
As anotações são anexadas a uma versão específica do objeto.
As anotações de uma versão do objeto são independentes das anotações em outras versões do mesmo objeto. A criação de uma nova versão não copia as anotações da versão anterior. Excluir ou adicionar uma anotação em uma versão não afeta as anotações em outras versões. A substituição de um objeto troca as anotações por quaisquer anotações que a nova versão tenha (se não houver nenhuma, as anotações serão excluídas).
Adicionar, atualizar ou remover uma anotação não modifica a ETag do objeto pai.
Em um bucket sem versão, se você excluir ou substituir o objeto, as anotações serão excluídas com ele.
Em um bucket com versão, o seguinte comportamento se aplica:
-
Uma simples solicitação DELETE (sem especificar um ID de versão) cria um marcador de exclusão, mas preserva as anotações na versão subjacente.
-
A exclusão de um ID de versão específico exclui essa versão e todas as anotações associadas.
-
As versões das anotações não são independentes. Quando você substitui uma anotação com o mesmo nome, o Amazon S3 substitui o valor anterior sem criar uma nova versão do objeto.
Importante
A exclusão de anotações é permanente e irreversível, mesmo em um bucket com versão. Diferentemente dos objetos em buckets com versão, as anotações não têm marcadores de exclusão nem histórico de versões. Depois que você excluir uma anotação, não será possível recuperá-la.
Comportamento e consistência da cópia
Quando você copia um objeto usando a API CopyObject (para objetos menores que 5 GiB), o Amazon S3 copia as anotações junto com o objeto em uma única operação.
Quando você copia objetos usando o upload de várias partes (por exemplo, quando os SDKs da AWS CLI ou da AWS usam o Transfer Manager para objetos maiores que aproximadamente 8 MB), por padrão, as anotações não são copiadas. Para incluir anotações, especifique --copy-props all na configuração da AWS CLI ou do SDK equivalente. Com essa ativação, o SDK lê as anotações de origem, conclui o upload de várias partes e, em seguida, grava cada anotação no destino. Entre a conclusão do upload e a gravação da última anotação, o objeto de destino existe sem nenhuma das anotações.
Considerações
-
Você não pode adicionar anotações como parte de uma solicitação
PutObjectou de upload de várias partes. Para adicionar anotações a um objeto, chamePutObjectAnnotationdepois que o objeto for carregado. Para copiar um objeto existente com as anotações para um novo local, useCopyObjectcom a diretiva de anotação padrão. -
Para adicionar ou atualizar anotações em vários objetos em massa, use Operações em lote para invocar uma função do Lambda que chama
PutObjectAnnotationem cada objeto. Para obter mais informações, consulte Invocar função do AWS Lambda. -
As anotações não são compatíveis com os seguintes recursos: S3 Inventory Reports, API Gateway, Lente de Armazenamento do S3, Amazon S3 File Gateway, Amazon FSx, S3 no Outposts, S3 Express One Zone (buckets de diretório) e Amazon S3 Files.
-
Para garantir que você grave anotações na versão atual de um objeto e não em uma que tenha sido substituída, use o cabeçalho condicional
x-amz-object-if-matchcomPutObjectAnnotationouDeleteObjectAnnotation. Esse cabeçalho valida a ETag do objeto pai para confirmar que o objeto não foi substituído desde a última vez que o chamador o leu. A adição de tags ou anotações não altera a ETag. -
Você não pode adicionar uma anotação condicionalmente à presença ou ausência de outra anotação. O cabeçalho
x-amz-object-if-matchvalida somente a ETag do objeto pai, não o estado da anotação. -
As cargas úteis de anotação devem ser texto válido com codificação UTF-8. Para armazenar dados binários, codifique os dados com Base64 antes de gravar a anotação.
-
Você pode chamar operações de API de anotação (
PutObjectAnnotation,GetObjectAnnotation,ListObjectAnnotations,DeleteObjectAnnotation) em objetos em qualquer classe de armazenamento, incluindo S3 Glacier e S3 Glacier Deep Archive, sem restaurar o objeto primeiro.
Configurações adicionais
Esta seção explica como as anotações estão relacionadas a outras configurações.
Replicação
Se você tiver a replicação do S3 configurada no bucket, o Amazon S3 replicará as anotações automaticamente. Cada anotação é replicada de forma independente. Para obter mais informações, consulte O que o Amazon S3 replica?.
Para replicar anotações, adicione s3:GetObjectVersionAnnotationForReplication às permissões do bucket de origem no perfil do IAM de replicação. Para obter mais informações, consulte Configurar permissões para replicação em tempo real.
Para evitar a replicação de anotações e, ao mesmo tempo, permitir a replicação de objetos, adicione uma instrução de negação para s3:ReplicateObjectAnnotation na política de perfil de replicação. A replicação de objetos continua sendo bem-sucedida; somente a replicação de anotações é bloqueada.
Notificações de eventos
O Amazon S3 pode enviar notificações de eventos quando as anotações são criadas, atualizadas ou excluídas. Você pode configurar os seguintes tipos de evento:
-
s3:ObjectAnnotation:Put: enviado quando uma anotação é criada ou atualizada. -
s3:ObjectAnnotation:Delete: enviado quando uma anotação é excluída.
Para obter mais informações, consulte Tipos e destinos de notificações de evento.
