# Anotación de los objetos Utilice anotaciones para adjuntar cargas útiles de datos con nombre a los objetos de Amazon S3. Cada anotación es una carga útil de metadatos personalizada de entre 1 byte y 1 MiB de tamaño que puede crear, recuperar, mostrar y eliminar sin modificar el objeto en sí mismo. Puede asociar hasta 1000 anotaciones a una versión de objeto. Cada anotación tiene un nombre único y puede almacenar datos estructurados, como etiquetas generadas por la IA, el contexto del documento, los resultados del procesamiento o los registros de conformidad. Los casos de uso comunes incluyen el almacenamiento de los resultados de las inferencias de machine learning, las incrustaciones generadas por la IA, las etiquetas de moderación de contenido, los resultados de la clasificación de documentos, el linaje de datos y los registros de auditoría, las etiquetas de conformidad, como las marcas de información de identificación personal o las políticas de retención, los metadatos de imágenes médicas, la información sobre los derechos de los activos digitales y el estado de la canalización de ETL junto con el objeto de origen. Las anotaciones se administran mediante operaciones de API específicas, por lo que no es necesario volver a cargar el objeto para agregar o actualizar los metadatos. Puede habilitar una tabla de anotaciones como parte de la configuración de metadatos de S3 para consultar datos de anotaciones a escala mediante Athena y otros servicios de análisis. Los metadatos de S3 almacenan los datos de las anotaciones en tablas de Apache Iceberg totalmente administradas que Amazon S3 mantiene actualizadas automáticamente. Para obtener más información, consulte [Detección de los datos con tablas de metadatos de S3](metadata-tables-overview.md). Las anotaciones están disponibles en todas las regiones de AWS comerciales y en las regiones de China (Beijing y Ningxia). Las anotaciones no están disponibles en las regiones de Medio Oriente (EAU) ni Medio Oriente (Baréin). Las tablas de anotaciones de metadatos de S3 están disponibles en todas las regiones en las que están disponibles metadatos de S3. ## Cuándo usar anotaciones en lugar de etiquetas de objeto Utilice la siguiente comparación para determinar si las anotaciones o etiquetas de objeto son las que mejor se adaptan a su caso de uso. | Característica | Etiquetas de objetos | Anotaciones | | --- | --- | --- | | Máximo por objeto | 10 por versión de objeto | 1000 por versión de objeto | | Tamaño máximo | 128 caracteres (clave) \+ 256 caracteres (valor) | 512 bytes (nombre) \+ 1 MiB (carga útil) | | Formato de los datos | Pares de cadenas clave-valor | Cualquier texto UTF-8 (JSON, XML, YAML, etc.) | | Mutabilidad | Sí (PutObjectTagging) | Sí (PutObjectAnnotation) | | Se establece durante la carga | Sí (PutObject, POST) | No (solo PutObjectAnnotation, después de la carga) | Elija las anotaciones cuando necesite almacenar datos estructurados (como JSON o XML), cargas útiles de más de 256 caracteres o más de 10 entradas de metadatos por objeto. Elija etiquetas de objetos cuando necesite la integración de políticas de IAM, el filtrado de reglas del ciclo de vida de Amazon S3 o los informes de asignación de costos. ## Operaciones de la API para anotaciones Amazon S3 admite las siguientes operaciones de la API para trabajar con anotaciones: + **PutObjectAnnotation**: crea o sobrescribe una anotación en un objeto. El nombre de la anotación y la carga útil se especifican en la solicitud. + **GetObjectAnnotation**: devuelve la carga útil de una anotación específica por nombre. + **ListObjectAnnotations**: devuelve la lista de anotaciones de un objeto. La respuesta incluye el nombre, el tamaño, la ETag y la fecha de la última modificación de cada anotación. + **DeleteObjectAnnotation**: elimina una anotación específica por nombre. Amazon S3 también admite anotaciones en las operaciones de la API siguientes: + **CopyObject**: copia las anotaciones del objeto de origen de forma predeterminada. Puede especificar el encabezado `x-amz-annotation-directive` para controlar si las anotaciones se copian (`COPY`) o se excluyen (`EXCLUDE`). + **UpdateBucketMetadataAnnotationTableConfiguration**: habilita o deshabilita la tabla de anotaciones en la configuración de metadatos de S3. + **CreateBucketMetadataConfiguration**: acepta un nuevo parámetro `AnnotationTableConfiguration` para habilitar las tablas de anotaciones al crear una configuración de metadatos de S3. + **GetBucketMetadataConfiguration**: devuelve `AnnotationTableConfigurationResult` en la respuesta, que indica el estado actual de la tabla de anotaciones. ## Límites de anotación Cada versión de objeto admite hasta 1000 anotaciones. Las anotaciones que están asociadas con una versión de objeto deben tener nombres de anotación exclusivos. Se aplican los siguientes límites: + El nombre de una anotación puede tener una longitud máxima de 512 bytes (UTF-8), sujeto a las reglas de nomenclatura que se indican a continuación. + La carga útil de una anotación debe tener un tamaño de entre 1 byte y 1 MiB. + El almacenamiento total de anotaciones por objeto puede ser de hasta 1 GiB (1000 anotaciones a 1 MiB cada una). + Algoritmos de suma de comprobación compatibles: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128. ## Reglas de nomenclatura de anotaciones Los nombres de las anotaciones deben cumplir con los siguientes requisitos: + Deben tener una longitud entre 1 y 512 bytes. + Solo puede contener los siguientes caracteres: letras (en cualquier idioma), dígitos (0-9), guión bajo (`_`), punto (`.`) y guion (`-`). + No puede empezar por `aws` o `s3` (no distingue entre mayúsculas y minúsculas). Por ejemplo, `aws`, `AWS`, `s3` y `S3` son todos prefijos reservados. + No deben estar vacíos ni constar solo de espacios en blanco. ## Cifrado Las anotaciones se cifran automáticamente en reposo con la misma configuración de cifrado que el objeto principal. El tipo de cifrado se hereda del objeto principal, no del bucket predeterminado. + **SSE-S3**: si el objeto principal utiliza el cifrado del servidor con claves administradas por Amazon S3 (SSE-S3), las anotaciones se cifran con SSE-S3. Si el objeto principal no tiene configurado el cifrado del servidor, las anotaciones se cifran con SSE-S3 de forma predeterminada. + **SSE-KMS**: si el objeto principal utiliza el cifrado del servidor con claves de AWS KMS (SSE-KMS), las anotaciones se cifran con la misma clave de KMS. Esto se aplica a las claves administradas por el cliente y a las claves administradas por AWS. Se admiten claves de bucket de S3. + **DSSE-KMS**: si el objeto principal utiliza el cifrado del servidor de doble capa con claves de AWS KMS (DSSE-KMS), las anotaciones se cifran con DSSE-KMS mediante la misma clave. + **SSE-C**: el cifrado del servidor con claves proporcionadas por el cliente (SSE-C) no se admite para las anotaciones. Si intenta agregar una anotación a un objeto cifrado con SSE-C, Amazon S3 devolverá un error. ## Sumas de comprobación Al cargar una anotación mediante `PutObjectAnnotation`, puede proporcionar una suma de comprobación para verificar la integridad de los datos. El algoritmo de suma de comprobación de una anotación es independiente del algoritmo de suma de comprobación del objeto principal. Cuando copia un objeto con `CopyObject`, Amazon S3 conserva los valores de la suma de comprobación de la anotación del origen. Si especifica un algoritmo de suma de comprobación diferente en la solicitud de copia, el nuevo algoritmo se aplica al objeto y a sus anotaciones. Algoritmos compatibles: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128. Si la anotación no tiene un algoritmo de suma de comprobación o un valor de suma de comprobación especificado, Amazon S3 utiliza el algoritmo CRC-64/NVME para calcular el valor de la suma de comprobación de la anotación. ## Comportamiento de control de versiones Las anotaciones se adjuntan a una versión de objeto específica. Las anotaciones de una versión del objeto son independientes de las anotaciones de otras versiones del mismo objeto. Al crear una nueva versión, no se copian las anotaciones de la versión anterior. La eliminación o agregación de una anotación en una versión no afecta a las anotaciones de otras versiones. Al sobrescribir un objeto, se sustituyen sus anotaciones por las anotaciones que tenga la nueva versión (si no hay ninguna, se eliminan de forma efectiva). Agregar, actualizar o eliminar una anotación no modifica la ETag del objeto principal. En un bucket no versionado, si elimina o sobrescribe el objeto, las anotaciones se eliminan junto con él. En un bucket con control de versiones, se aplica el siguiente comportamiento: + Una simple solicitud DELETE (sin especificar un ID de versión) crea un marcador de borrado, pero conserva las anotaciones de la versión subyacente. + Al eliminar un ID de versión específico, se elimina esa versión y todas las anotaciones asociadas. + Las anotaciones no se versionan de forma independiente. Al sobrescribir una anotación con el mismo nombre, Amazon S3 reemplaza el valor anterior sin crear una nueva versión del objeto. **importante** La eliminación de anotaciones es permanente e irreversible, incluso en un bucket con control de versiones. A diferencia de los objetos de los buckets con control de versiones, las anotaciones no tienen marcadores de borrado ni historial de versiones. Una vez que elimina una anotación, no se puede recuperar. ## Comportamiento y coherencia de la copia Al copiar un objeto mediante la API `CopyObject` (para objetos de menos de 5 GiB), Amazon S3 copia las anotaciones junto con el objeto en una sola operación. Al copiar objetos mediante una carga multiparte (por ejemplo, cuando la AWS CLI o los AWS SDK utilizan administrador de transferencias para objetos de un tamaño superior a aproximadamente 8 MB), las anotaciones no se copian de forma predeterminada. Para incluir anotaciones, especifique `--copy-props all` en la AWS CLI o la configuración del SDK equivalente. Con esta opción, el SDK lee las anotaciones de origen, completa la carga multiparte y, a continuación, escribe cada anotación en el destino. Entre la finalización de la carga y la última escritura de la anotación, el objeto de destino existe sin todas sus anotaciones. ## Consideraciones + No puede agregar anotaciones como parte de una solicitud de carga `PutObject` o multiparte. Para agregar anotaciones a un objeto, llame a `PutObjectAnnotation` después de cargar el objeto. Para copiar un objeto existente con sus anotaciones en una nueva ubicación, use `CopyObject` con la directiva de anotación predeterminada. + Para agregar o actualizar anotaciones en varios objetos de forma masiva, utilice Operaciones por lotes para invocar una función de Lambda que llame a `PutObjectAnnotation` en cada objeto. Para obtener más información, consulte [Invocar a la función AWS Lambda](batch-ops-invoke-lambda.md). + Las siguientes características no admiten anotaciones: informes de inventario de S3, API Gateway, Lente de almacenamiento de S3, puerta de enlace de archivo de Amazon S3, Amazon FSx, S3 en Outposts, S3 Express One Zone (buckets de directorio) y Amazon S3 Files. + Para asegurarse de escribir las anotaciones en la versión actual de un objeto y no en una que se haya sobrescrito, utilice el encabezado condicional `x-amz-object-if-match` con `PutObjectAnnotation` o `DeleteObjectAnnotation`. Este encabezado valida la ETag del objeto principal para confirmar que el objeto no se ha sobrescrito desde la última vez que el intermediario lo leyó. La agregación de etiquetas o anotaciones no cambia la ETag. + No puede agregar una anotación condicionalmente a la presencia o ausencia de otra anotación. El encabezado `x-amz-object-if-match` valida solo la ETag del objeto principal, no el estado de la anotación. + Las cargas útiles de anotación deben ser texto codificado en UTF-8 válido. Para almacenar datos binarios, codifique los datos con Base64 antes de escribir la anotación. + Puede llamar a las operaciones de la API de anotación (`PutObjectAnnotation`, `GetObjectAnnotation`, `ListObjectAnnotations`, `DeleteObjectAnnotation`) en objetos de cualquier clase de almacenamiento, incluidos S3 Glacier y S3 Glacier Deep Archive, sin restaurar primero el objeto. ## Configuraciones adicionales En esta sección, se explica cómo las anotaciones se relacionan con otras configuraciones. ### Replicación Si tiene la replicación de S3 configurada en el bucket, Amazon S3 replica las anotaciones automáticamente. Cada anotación se replica de forma independiente. Para obtener más información, consulte [¿Qué replica Amazon S3?](replication-what-is-isnot-replicated.md). Para replicar las anotaciones, agregue `s3:GetObjectVersionAnnotationForReplication` a los permisos del bucket de origen en el rol de IAM de replicación. Para obtener más información, consulte [Configuración de permisos para la replicación en directo](setting-repl-config-perm-overview.md). Para evitar la replicación de anotaciones y, al mismo tiempo, permitir la replicación de objetos, agregue una instrucción de denegación para `s3:ReplicateObjectAnnotation` en la política de roles de replicación. La replicación de objetos sigue siendo correcta; solo se bloquea la replicación de anotaciones. ### Notificaciones de eventos Amazon S3 puede enviar notificaciones de eventos cuando se crean, actualizan o eliminan anotaciones. Puede configurar los siguientes tipos de eventos: + `s3:ObjectAnnotation:Put`: se envía cuando se crea o actualiza una anotación. + `s3:ObjectAnnotation:Delete`: se envía cuando se elimina una anotación. Para obtener más información, consulte [Tipos y destinos de las notificaciones de eventos](notification-how-to-event-types-and-destinations.md).