View a markdown version of this page

Annoter vos objets - Amazon Simple Storage Service
Quand utiliser des annotations plutôt que des balises d'objetsOpérations d'API pour les annotationsLimites d'annotationRègles de dénomination des annotationsChiffrementSommes de chèquesComportement de gestion des versionsComportement et cohérence des copiesConsidérationsConfigurations supplémentaires

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Annoter vos objets

Utilisez des annotations pour associer des charges utiles de données nommées à vos objets Amazon S3. Chaque annotation est une charge utile de métadonnées personnalisée d'une taille comprise entre 1 octet et 1 MiB que vous pouvez créer, récupérer, répertorier et supprimer sans modifier l'objet lui-même.

Vous pouvez associer jusqu'à 1 000 annotations à une version d'objet. Chaque annotation porte un nom unique et peut stocker des données structurées telles que les AI-generated étiquettes, le contexte du document, les résultats du traitement ou les enregistrements de conformité.

Les cas d'utilisation courants incluent le stockage des résultats d'inférence du machine learning, AI-generated des intégrations, des étiquettes de modération du contenu, des résultats de classification des documents, du lignage des données et des pistes d'audit, des étiquettes de conformité telles que des indicateurs PII ou des politiques de conservation, des métadonnées d'imagerie médicale, des informations sur les droits des actifs numériques et l'état du pipeline ETL à côté de l'objet source.

Vous gérez les annotations à l'aide d'opérations d'API dédiées. Vous n'avez donc pas besoin de télécharger à nouveau l'objet pour ajouter ou mettre à jour des métadonnées.

Vous pouvez activer une table d'annotations dans le cadre de votre configuration de métadonnées S3 pour interroger les données d'annotation à grande échelle à l'aide d'Athena et d'autres services d'analyse. S3 Metadata stocke les données d'annotation dans Apache Iceberg des tables entièrement gérées qu'Amazon S3 met automatiquement à jour. Pour de plus amples informations, veuillez consulter Identification de vos données avec les tables S3 Metadata.

Les annotations sont disponibles dans toutes les AWS régions commerciales et les régions de Chine (Pékin et Ningxia). Les annotations ne sont pas disponibles dans les régions du Moyen-Orient (Émirats arabes unis) et du Moyen-Orient (Bahreïn). Les tables d'annotation des métadonnées S3 sont disponibles dans toutes les régions où les métadonnées S3 sont disponibles.

Quand utiliser des annotations plutôt que des balises d'objets

Utilisez la comparaison suivante pour déterminer si les annotations ou les balises d'objet sont les mieux adaptées à votre cas d'utilisation.

Caractéristiques Balises d’objet Annotations
Maximum par objet 10 par version d'objet 1 000 par version d'objet
Taille maximum 128 caractères (clé) + 256 caractères (valeur) 512 octets (nom) + 1 MiB (charge utile)
Format de données Key-value paires de cordes N'importe quel UTF-8 texte (JSON, XML, YAML, etc.)
Mutabilité Oui (PutObjectTagging) Oui (PutObjectAnnotation)
Paramétré lors du téléchargement Oui (PutObject, POST) Non (PutObjectAnnotation uniquement, après le téléchargement)

Choisissez des annotations lorsque vous devez stocker des données structurées (telles que JSON ou XML), des charges utiles supérieures à 256 caractères ou plus de 10 entrées de métadonnées par objet. Choisissez des balises d'objet lorsque vous avez besoin d'intégrer les politiques IAM, de filtrer les règles du cycle de vie d'Amazon S3 ou de générer des rapports sur la répartition des coûts.

Opérations d'API pour les annotations

Amazon S3 prend en charge les opérations d'API suivantes pour travailler avec les annotations :

  • PutObjectAnnotation— Crée ou remplace une annotation sur un objet. Vous spécifiez le nom de l'annotation et la charge utile dans la demande.

  • GetObjectAnnotation— Renvoie la charge utile d'une annotation spécifique par son nom.

  • ListObjectAnnotations— Renvoie la liste des annotations d'un objet. La réponse inclut le nom, la taille, l'ETag et la date de dernière modification de chaque annotation.

  • DeleteObjectAnnotation— Supprime une annotation spécifique par son nom.

Amazon S3 prend également en charge les annotations dans les opérations d'API suivantes :

  • CopyObject— Copie les annotations de l'objet source par défaut. Vous pouvez spécifier l'x-amz-annotation-directiveen-tête pour contrôler si les annotations sont copiées (COPY) ou exclues (EXCLUDE).

  • UpdateBucketMetadataAnnotationTableConfiguration— Active ou désactive la table d'annotations dans votre configuration de métadonnées S3.

  • CreateBucketMetadataConfiguration— Accepte un nouveau AnnotationTableConfiguration paramètre pour activer les tables d'annotations lorsque vous créez une configuration de métadonnées S3.

  • GetBucketMetadataConfiguration— Renvoie AnnotationTableConfigurationResult la réponse, qui indique l'état actuel de la table d'annotations.

Limites d'annotation

Chaque version d'objet prend en charge jusqu'à 1 000 annotations. Les annotations associées à une version d'objet doivent avoir des noms d'annotation uniques. Les limites suivantes s'appliquent :

  • Le nom d'une annotation peut avoir une longueur maximale de 512 octets (UTF-8), sous réserve des règles de dénomination ci-dessous.

  • La charge utile d'une annotation doit avoir une taille comprise entre 1 octet et 1 MiB.

  • Le stockage total d'annotations par objet peut atteindre 1 GiB (1 000 annotations à 1 Mo chacune).

  • Algorithmes de somme de contrôle pris en charge : CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

Règles de dénomination des annotations

Les noms des annotations doivent répondre aux exigences suivantes :

  • Doit avoir une longueur comprise entre 1 et 512 octets.

  • Ne peut contenir que les caractères suivants : lettres (n'importe quelle langue), chiffres (0 à 9), trait de soulignement (_), point (.) et tiret (). -

  • Impossible de commencer par aws ou s3 (sans distinction majuscules/majuscules). Par exemple,aws, AWSs3, et S3 sont tous des préfixes réservés.

  • Il ne doit pas être vide ou ne comporter que des espaces blancs.

Chiffrement

Les annotations sont automatiquement chiffrées au repos en utilisant la même configuration de chiffrement que l'objet parent. Le type de chiffrement est hérité de l'objet parent, et non de la valeur par défaut du compartiment.

  • SSE-S3— Si l'objet parent utilise le chiffrement côté serveur avec des clés gérées par Amazon S3 (SSE-S3), les annotations sont chiffrées avec. SSE-S3 Si aucun chiffrement côté serveur n'est configuré pour l'objet parent, les annotations sont chiffrées par SSE-S3 défaut.

  • SSE-KMS— Si l'objet parent utilise le chiffrement côté serveur avec des AWS KMS clés (SSE-KMS), les annotations sont chiffrées avec la même clé KMS. Cela s'applique à la fois aux clés gérées par le client et aux clés AWS gérées. Les clés de compartiment S3 sont prises en charge.

  • DSSE-KMS— Si l'objet parent utilise un chiffrement double couche côté serveur avec des AWS KMS clés (DSSE-KMS), les annotations sont chiffrées à DSSE-KMS l'aide de la même clé.

  • SSE-C— Server-side le chiffrement avec les clés fournies par le client (SSE-C) n'est pas pris en charge pour les annotations. Si vous tentez d'ajouter une annotation à un objet chiffré avec SSE-C, Amazon S3 renvoie une erreur.

Sommes de chèques

Lorsque vous téléchargez une annotation à l'aide dePutObjectAnnotation, vous pouvez fournir une somme de contrôle pour vérifier l'intégrité des données. L'algorithme de somme de contrôle d'une annotation est indépendant de l'algorithme de somme de contrôle de l'objet parent.

Lorsque vous copiez un objet à l'aide d'CopyObjectAmazon S3 conserve les valeurs de la somme de contrôle des annotations depuis la source. Si vous spécifiez un algorithme de somme de contrôle différent dans la demande de copie, le nouvel algorithme s'applique à la fois à l'objet et à ses annotations.

Algorithmes pris en charge : CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

Si l'annotation n'a pas d'algorithme de somme de contrôle ou de valeur de somme de contrôle spécifique, Amazon S3 utilise l' CRC-64/NVME algorithme pour calculer la valeur de somme de contrôle de l'annotation.

Comportement de gestion des versions

Les annotations sont associées à une version d'objet spécifique.

Les annotations d'une version d'objet sont indépendantes des annotations des autres versions du même objet. La création d'une nouvelle version ne copie pas les annotations de la version précédente. La suppression ou l'ajout d'une annotation sur une version n'affecte pas les annotations sur les autres versions. Le remplacement d'un objet remplace ses annotations par les annotations de la nouvelle version (si aucune, elles sont effectivement supprimées).

L'ajout, la mise à jour ou la suppression d'une annotation ne modifie pas l'ETag de l'objet parent.

Dans un bucket non versionné, si vous supprimez ou remplacez l'objet, les annotations sont également supprimées.

Dans un bucket versionné, le comportement suivant s'applique :

  • Une simple demande DELETE (sans spécifier d'ID de version) crée un marqueur de suppression mais préserve les annotations sur la version sous-jacente.

  • La suppression d'un ID de version spécifique entraîne la suppression de cette version et de toutes les annotations associées.

  • Les annotations ne sont pas versionnées de manière indépendante. Lorsque vous remplacez une annotation portant le même nom, Amazon S3 remplace la valeur précédente sans créer de nouvelle version de l'objet.

Important

La suppression des annotations est permanente et irréversible, même dans un compartiment versionné. Contrairement aux objets contenus dans des compartiments versionnés, les annotations ne comportent pas de marqueurs de suppression ni d'historique des versions. Une fois que vous avez supprimé une annotation, elle ne peut pas être récupérée.

Comportement et cohérence des copies

Lorsque vous copiez un objet à l'aide de l'CopyObjectAPI (pour les objets inférieurs à 5 GiB), Amazon S3 copie les annotations avec l'objet en une seule opération.

Lorsque vous copiez des objets à l'aide du téléchargement partitionné (par exemple, lorsque le AWS CLI ou les AWS SDK utilisent Transfer Manager pour des objets d'une taille supérieure à 8 Mo environ), les annotations ne sont pas copiées par défaut. Pour inclure des annotations, spécifiez-les --copy-props all dans la configuration du SDK AWS CLI ou dans la configuration équivalente. Avec cet opt-in, le SDK lit les annotations source, effectue le téléchargement en plusieurs parties, puis écrit chaque annotation sur la destination. Entre la fin du téléchargement et l'écriture de la dernière annotation, l'objet de destination existe sans toutes ses annotations.

Considérations

  • Vous ne pouvez pas ajouter d'annotations dans le cadre d'une demande de téléchargement en plusieurs parties PutObject ou en plusieurs parties. Pour ajouter des annotations à un objet, appelez une PutObjectAnnotation fois que l'objet a été chargé. Pour copier un objet existant avec ses annotations vers un nouvel emplacement, utilisez CopyObject la directive d'annotation par défaut.

  • Pour ajouter ou mettre à jour des annotations sur de nombreux objets en bloc, utilisez Batch Operations pour appeler une fonction Lambda qui PutObjectAnnotation appelle chaque objet. Pour de plus amples informations, veuillez consulter Invocation AWS Lambda fonction.

  • Les annotations ne sont pas prises en charge par les fonctionnalités suivantes : S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, S3 Express One Zone (compartiments de répertoires) et Amazon S3 Files.

  • Pour vous assurer que vous écrivez des annotations sur la version actuelle d'un objet et non sur une version qui a été remplacée, utilisez l'en-tête x-amz-object-if-match conditionnel avec PutObjectAnnotation ou. DeleteObjectAnnotation Cet en-tête valide l'ETag de l'objet parent pour confirmer que l'objet n'a pas été remplacé depuis sa dernière lecture par l'appelant. L'ajout de balises ou d'annotations ne modifie pas l'ETag.

  • Vous ne pouvez pas ajouter une annotation sous réserve de la présence ou de l'absence d'une autre annotation. L'x-amz-object-if-matchen-tête valide uniquement l'ETag de l'objet parent, et non l'état de l'annotation.

  • Les charges utiles d'annotation doivent être du texte UTF-8 codé valide. Pour stocker des données binaires, encodez-les en Base64 avant d'écrire l'annotation.

  • Vous pouvez appeler des opérations d'API d'annotation (PutObjectAnnotation,, GetObjectAnnotationListObjectAnnotations,DeleteObjectAnnotation) sur des objets de n'importe quelle classe de stockage, notamment S3 Glacier et S3 Glacier Deep Archive, sans avoir à restaurer l'objet au préalable.

Configurations supplémentaires

Cette section explique comment les annotations sont liées aux autres configurations.

Réplication

Si la réplication S3 est configurée sur votre compartiment, Amazon S3 réplique automatiquement les annotations. Chaque annotation est répliquée indépendamment. Pour de plus amples informations, veuillez consulter Ce qui est répliqué par Amazon S3.

Pour répliquer des annotations, ajoutez des autorisations s3:GetObjectVersionAnnotationForReplication au compartiment source dans votre rôle IAM de réplication. Pour de plus amples informations, veuillez consulter Configuration des autorisations pour la réplication en direct.

Pour empêcher la réplication d'annotations tout en autorisant la réplication d'objets, ajoutez une déclaration de refus s3:ReplicateObjectAnnotation dans la politique de rôle de réplication. La réplication des objets continue de réussir ; seule la réplication des annotations est bloquée.

Notifications d’événements

Amazon S3 peut envoyer des notifications d'événements lorsque des annotations sont créées, mises à jour ou supprimées. Vous pouvez configurer les types d'événements suivants :

  • s3:ObjectAnnotation:Put— Envoyé lors de la création ou de la mise à jour d'une annotation.

  • s3:ObjectAnnotation:Delete— Envoyé lorsqu'une annotation est supprimée.

Pour de plus amples informations, veuillez consulter Types de notification d’événements et destinations associées.