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 Mo 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 possède un nom unique et peut stocker des données structurées telles que des 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 de l'apprentissage automatique, AI-generated les intégrations, les étiquettes de modération du contenu, les résultats de classification des documents, le lignage des données et les pistes d'audit, les étiquettes de conformité telles que les indicateurs PII ou les politiques de conservation, les métadonnées d'imagerie médicale, les informations relatives aux droits sur les 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 tableaux entièrement gérés 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 Moyen-Orient (Émirats arabes unis) et 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 les annotations par rapport aux balises d'objet
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) |
| Régler lors du téléchargement | Oui (PutObject, POST) | Non (PutObjectAnnotation uniquement, après téléchargement) |
Choisissez des annotations lorsque vous devez stocker des données structurées (telles que JSON ou XML), des charges utiles de plus de 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 des politiques IAM, de filtrer les règles de 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 relatives à 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 depuis 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
AnnotationTableConfigurationparamètre pour activer les tables d'annotations lorsque vous créez une configuration de métadonnées S3. -
GetBucketMetadataConfiguration— Renvoie
AnnotationTableConfigurationResultla 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 :
-
Un nom d'annotation peut avoir une longueur maximale de 512 octets (UTF-8), sous réserve des règles de dénomination ci-dessous.
-
La taille d'une charge utile d'annotation doit être comprise entre 1 octet et 1 Mo.
-
Le stockage total d'annotations par objet peut atteindre 1 Go (1 000 annotations de 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 :
-
La longueur doit être 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
awsous3(sans distinction majuscules/minuscules). Par exemple,aws,AWSs3, etS3sont tous des préfixes réservés. -
Ne doit pas être vide ni être composé uniquement d'espaces blancs.
Chiffrement
Les annotations sont automatiquement chiffrées au repos en utilisant la même configuration de chiffrement que celle de l'objet parent. Le type de chiffrement est hérité de l'objet parent, et non de la valeur par défaut du bucket.
-
SSE-S3— Si l'objet parent utilise un 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 crypté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 S3 Bucket 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 à l'aide de 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é SSE-C, Amazon S3 renvoie une erreur.
Sommes de contrôle
Lorsque vous 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 deCopyObject, Amazon S3 conserve les valeurs de la somme de contrôle des annotations provenant de 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 ne possède pas d'algorithme de somme de contrôle ou de valeur de somme de contrôle spécifié, Amazon S3 utilise l' CRC-64/NVME algorithme pour calculer la valeur de somme de contrôle pour l'annotation.
Comportement de gestion des versions
Les annotations sont associées à une version spécifique de l'objet.
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 n'est disponible, les supprime effectivement).
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 supprimées avec celui-ci.
Dans un bucket versionné, le comportement suivant s'applique :
-
Une simple requête DELETE (sans spécifier d'ID de version) crée un marqueur de suppression mais conserve les annotations sur la version sous-jacente.
-
La suppression d'un ID de version spécifique supprime cette version et toutes les annotations associées.
-
Les annotations ne sont pas versionnées indépendamment. 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 bucket versionné. Contrairement aux objets 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 Go), 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 les kits de AWS développement logiciel AWS CLI ou SDK utilisent Transfer Manager pour des objets d'une taille supérieure à environ 8 Mo), 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 une configuration équivalente. Avec cette option, le SDK lit les annotations de la source, termine le téléchargement en plusieurs parties, puis écrit chaque annotation vers la destination. Entre la fin du chargement et la dernière écriture d'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
PutObjectou en plusieurs parties. Pour ajouter des annotations à un objet, appelez unePutObjectAnnotationfois que l'objet a été chargé. Pour copier un objet existant avec ses annotations vers un nouvel emplacement, utilisezCopyObjectla directive d'annotation par défaut. -
Pour ajouter ou mettre à jour des annotations sur de nombreux objets en bloc, utilisez les opérations par lots pour appeler une fonction Lambda qui appelle
PutObjectAnnotationchaque 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 : Rapports d'inventaire S3, 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 pour la version actuelle d'un objet et non pour une version qui a été remplacée, utilisez l'en-tête
x-amz-object-if-matchconditionnel avecPutObjectAnnotationou.DeleteObjectAnnotationCet en-tête valide l'ETag de l'objet parent pour confirmer que l'objet n'a pas été remplacé depuis la dernière fois que l'appelant l'a lu. L'ajout de balises ou d'annotations ne modifie pas l'ETag. -
Vous ne pouvez pas ajouter d'annotation en fonction 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, pas l'état de l'annotation. -
Les charges utiles des annotations doivent être du texte UTF-8 codé valide. Pour stocker des données binaires, codez-les avec Base64 avant d'écrire l'annotation.
-
Vous pouvez appeler des opérations d'API d'annotation (
PutObjectAnnotation,GetObjectAnnotationListObjectAnnotations,DeleteObjectAnnotation) sur des objets appartenant à n'importe quelle classe de stockage, y compris S3 Glacier et S3 Glacier Deep Archive, sans 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 des annotations tout en autorisant la réplication des objets, ajoutez une instruction 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é lorsqu'une annotation est créée ou mise à jour. -
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.
