View a markdown version of this page

Kommentieren Sie Ihre Objekte - Amazon Simple Storage Service
Wann sollten Anmerkungen im Vergleich zu Objekt-Tags verwendet werdenAPI-Operationen für AnmerkungenGrenzwerte für AnmerkungenRegeln für die Benennung von AnmerkungenVerschlüsselungPrüfsummenVerhalten bei der VersionierungVerhalten und Konsistenz beim KopierenÜberlegungenZusätzliche Konfigurationen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Kommentieren Sie Ihre Objekte

Verwenden Sie Anmerkungen, um benannte Datennutzlasten an Ihre Amazon S3-Objekte anzuhängen. Jede Anmerkung ist eine benutzerdefinierte Metadaten-Nutzlast mit einer Größe zwischen 1 Byte und 1 MiB, die Sie erstellen, abrufen, auflisten und löschen können, ohne das Objekt selbst zu ändern.

Sie können einer Objektversion bis zu 1.000 Anmerkungen zuordnen. Jede Anmerkung hat einen eindeutigen Namen und kann strukturierte Daten wie AI-generated Beschriftungen, Dokumentkontext, Verarbeitungsergebnisse oder Compliance-Datensätze speichern.

Zu den häufigsten Anwendungsfällen gehören das Speichern von Inferenzergebnissen aus maschinellem Lernen, AI-generated Einbettungen, Beschriftungen zur Inhaltsmoderation, Ausgabe von Dokumentklassifizierungen, Datenherkunft und Prüfpfaden, Compliance-Labels wie PII-Flags oder Aufbewahrungsrichtlinien, Metadaten zur medizinischen Bildgebung, Informationen zu digitalen Vermögenswerten und ETL-Pipeline-Status zusammen mit dem Quellobjekt.

Sie verwalten Anmerkungen mithilfe spezieller API-Operationen, sodass Sie das Objekt nicht erneut hochladen müssen, um Metadaten hinzuzufügen oder zu aktualisieren.

Sie können eine Annotationstabelle als Teil Ihrer S3-Metadatenkonfiguration aktivieren, um mithilfe von Athena und anderen Analysediensten umfangreiche Annotationsdaten abzufragen. S3 Metadata speichert Annotationsdaten in vollständig verwalteten Apache Iceberg Tabellen, die Amazon S3 automatisch auf dem neuesten Stand hält. Weitere Informationen finden Sie unter Entdecken Sie Ihre Daten mit S3-Metadata-Tabellen.

Anmerkungen sind in allen AWS Handelsregionen und Regionen Chinas (Peking und Ningxia) verfügbar. Anmerkungen sind in den Regionen Naher Osten (VAE) und Naher Osten (Bahrain) nicht verfügbar. S3-Metadaten-Annotationstabellen sind in allen Regionen verfügbar, in denen S3-Metadaten verfügbar sind.

Wann sollten Anmerkungen im Vergleich zu Objekt-Tags verwendet werden

Ermitteln Sie anhand des folgenden Vergleichs, ob Anmerkungen oder Objekt-Tags für Ihren Anwendungsfall am besten geeignet sind.

Merkmal Objekt-Tags Anmerkungen
Maximum pro Objekt 10 pro Objektversion 1.000 pro Objektversion
Maximale Größe 128 Zeichen (Schlüssel) + 256 Zeichen (Wert) 512 Byte (Name) + 1 MiB (Nutzlast)
Data format (Datenformat) Key-value Zeichenkettenpaare Beliebiger UTF-8 Text (JSON, XML, YAML usw.)
Veränderlichkeit Ja (PutObjectTagging) Ja (PutObjectAnnotation)
Wird beim Upload festgelegt Ja (PutObject, POST) Nein (PutObjectAnnotation nur nach dem Upload)

Wählen Sie Anmerkungen, wenn Sie strukturierte Daten (wie JSON oder XML), Nutzlasten mit mehr als 256 Zeichen oder mehr als 10 Metadateneinträge pro Objekt speichern müssen. Wählen Sie Objekt-Tags, wenn Sie eine IAM-Richtlinienintegration, eine Amazon S3-Lifecycle-Regelfilterung oder Berichte zur Kostenverteilung benötigen.

API-Operationen für Anmerkungen

Amazon S3 unterstützt die folgenden API-Operationen für die Arbeit mit Anmerkungen:

  • PutObjectAnnotation— Erzeugt oder überschreibt eine Anmerkung zu einem Objekt. Sie geben den Namen und die Nutzlast der Anmerkung in der Anfrage an.

  • GetObjectAnnotation— Gibt die Nutzlast einer bestimmten Anmerkung anhand des Namens zurück.

  • ListObjectAnnotations— Gibt die Liste der Anmerkungen zu einem Objekt zurück. Die Antwort enthält den Namen, die Größe, das ETag und das Datum der letzten Änderung jeder Anmerkung.

  • DeleteObjectAnnotation— Entfernt eine bestimmte Anmerkung anhand des Namens.

Amazon S3 unterstützt auch Anmerkungen in den folgenden API-Vorgängen:

  • CopyObject— Kopiert standardmäßig Anmerkungen aus dem Quellobjekt. Sie können den x-amz-annotation-directive Header angeben, um zu steuern, ob Anmerkungen kopiert (COPY) oder ausgeschlossen (EXCLUDE) werden.

  • UpdateBucketMetadataAnnotationTableConfiguration— Aktiviert oder deaktiviert die Annotationstabelle in Ihrer S3-Metadatenkonfiguration.

  • CreateBucketMetadataConfiguration— Akzeptiert einen neuen AnnotationTableConfiguration Parameter, um Annotationstabellen zu aktivieren, wenn Sie eine S3-Metadatenkonfiguration erstellen.

  • GetBucketMetadataConfiguration— Gibt AnnotationTableConfigurationResult in der Antwort den aktuellen Status der Annotationstabelle zurück.

Grenzwerte für Anmerkungen

Jede Objektversion unterstützt bis zu 1.000 Anmerkungen. Anmerkungen, die einer Objektversion zugeordnet sind, müssen eindeutige Annotationsnamen haben. Es gelten die folgenden Limits:

  • Ein Annotationsname kann bis zu 512 Byte lang sein (UTF-8), vorbehaltlich der unten aufgeführten Benennungsregeln.

  • Eine Nutzlast für Anmerkungen muss zwischen 1 Byte und 1 MiB groß sein.

  • Der gesamte Annotationsspeicher pro Objekt kann bis zu 1 GiB betragen (1.000 Anmerkungen mit jeweils 1 MiB).

  • Unterstützte Prüfsummenalgorithmen: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

Regeln für die Benennung von Anmerkungen

Namen von Anmerkungen müssen die folgenden Anforderungen erfüllen:

  • Muss zwischen 1 und 512 Byte lang sein.

  • Darf nur die folgenden Zeichen enthalten: Buchstaben (jede Sprache), Ziffern (0-9), Unterstrich (_), Punkt (.) und Bindestrich (). -

  • Kann nicht mit aws oder beginnen (Groß- und Kleinschreibung wird nicht beachtets3). Zum Beispiel S3 sind, aws AWSs3, und alles reservierte Präfixe.

  • Darf nicht leer sein oder nur aus Leerzeichen bestehen.

Verschlüsselung

Anmerkungen werden im Ruhezustand automatisch mit derselben Verschlüsselungskonfiguration wie das übergeordnete Objekt verschlüsselt. Der Verschlüsselungstyp wird vom übergeordneten Objekt übernommen, nicht vom Bucket-Standard.

  • SSE-S3— Wenn das übergeordnete Objekt eine serverseitige Verschlüsselung mit von Amazon S3 verwalteten Schlüsseln (SSE-S3) verwendet, werden Anmerkungen mit verschlüsselt. SSE-S3 Wenn für das übergeordnete Objekt keine serverseitige Verschlüsselung konfiguriert ist, werden Anmerkungen standardmäßig mit verschlüsselt. SSE-S3

  • SSE-KMS— Wenn das übergeordnete Objekt die serverseitige Verschlüsselung mit AWS KMS keys (SSE-KMS) verwendet, werden Anmerkungen mit demselben KMS-Schlüssel verschlüsselt. Dies gilt sowohl für vom Kunden verwaltete Schlüssel als auch für AWS verwaltete Schlüssel. S3 Bucket Keys werden unterstützt.

  • DSSE-KMS— Wenn das übergeordnete Objekt eine duale serverseitige Verschlüsselung mit AWS KMS keys (DSSE-KMS) verwendet, werden Anmerkungen mit DSSE-KMS demselben Schlüssel verschlüsselt.

  • SSE-C— Die Server-side Verschlüsselung mit vom Kunden bereitgestellten Schlüsseln (SSE-C) wird für Anmerkungen nicht unterstützt. Wenn Sie versuchen, einem mit verschlüsselten Objekt eine Anmerkung hinzuzufügen SSE-C, gibt Amazon S3 einen Fehler zurück.

Prüfsummen

Wenn Sie eine Anmerkung mit hochladenPutObjectAnnotation, können Sie eine Prüfsumme angeben, um die Datenintegrität zu überprüfen. Der Prüfsummenalgorithmus für eine Anmerkung ist unabhängig vom Prüfsummenalgorithmus des übergeordneten Objekts.

Wenn Sie ein Objekt mit kopierenCopyObject, behält Amazon S3 die Annotationsprüfsummenwerte aus der Quelle bei. Wenn Sie in der Kopieranforderung einen anderen Prüfsummenalgorithmus angeben, gilt der neue Algorithmus sowohl für das Objekt als auch für seine Anmerkungen.

Unterstützte Algorithmen: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

Wenn die Anmerkung keinen bestimmten Prüfsummenalgorithmus oder Prüfsummenwert hat, verwendet Amazon S3 den Algorithmus, um den Prüfsummenwert für die Anmerkung zu berechnen. CRC-64/NVME

Verhalten bei der Versionierung

Anmerkungen werden an eine bestimmte Objektversion angehängt.

Anmerkungen zu einer Objektversion sind unabhängig von Anmerkungen zu anderen Versionen desselben Objekts. Beim Erstellen einer neuen Version werden keine Anmerkungen aus der vorherigen Version kopiert. Das Löschen oder Hinzufügen einer Anmerkung zu einer Version wirkt sich nicht auf Anmerkungen zu anderen Versionen aus. Beim Überschreiben eines Objekts werden dessen Anmerkungen durch die Anmerkungen der neuen Version ersetzt (falls keine vorhanden sind, werden sie effektiv gelöscht).

Durch das Hinzufügen, Aktualisieren oder Entfernen einer Anmerkung wird das ETag des übergeordneten Objekts nicht geändert.

Wenn Sie in einem Bucket ohne Versionierung das Objekt löschen oder überschreiben, werden auch die Anmerkungen gelöscht.

In einem versionierten Bucket gilt das folgende Verhalten:

  • Eine einfache DELETE-Anfrage (ohne Angabe einer Versions-ID) erstellt eine Löschmarkierung, behält jedoch die Anmerkungen zur zugrunde liegenden Version bei.

  • Durch das Löschen einer bestimmten Versions-ID werden diese Version und alle zugehörigen Anmerkungen gelöscht.

  • Anmerkungen werden nicht unabhängig versioniert. Wenn Sie eine Anmerkung mit demselben Namen überschreiben, ersetzt Amazon S3 den vorherigen Wert, ohne eine neue Objektversion zu erstellen.

Wichtig

Das Löschen von Anmerkungen ist dauerhaft und irreversibel, selbst in einem versionierten Bucket. Im Gegensatz zu Objekten in versionierten Buckets verfügen Annotationen nicht über Löschmarkierungen oder einen Versionsverlauf. Sobald Sie eine Anmerkung gelöscht haben, kann sie nicht wiederhergestellt werden.

Verhalten und Konsistenz beim Kopieren

Wenn Sie ein Objekt mithilfe der CopyObject API kopieren (für Objekte, die kleiner als 5 GiB sind), kopiert Amazon S3 die Anmerkungen zusammen mit dem Objekt in einem einzigen Vorgang.

Wenn Sie Objekte mithilfe eines mehrteiligen Uploads kopieren (z. B. wenn die AWS CLI oder AWS SDKs den Transfer Manager für Objekte verwenden, die größer als etwa 8 MB sind), werden Anmerkungen standardmäßig nicht kopiert. Um Anmerkungen einzubeziehen, geben Sie dies --copy-props all in der AWS CLI oder der entsprechenden SDK-Konfiguration an. Mit dieser Option liest das SDK Quellanmerkungen, schließt den mehrteiligen Upload ab und schreibt dann jede Anmerkung in das Ziel. Zwischen dem Abschluss des Uploads und dem letzten Schreiben der Anmerkung existiert das Zielobjekt ohne all seine Anmerkungen.

Überlegungen

  • Sie können keine Anmerkungen als Teil einer PutObject oder einer mehrteiligen Upload-Anfrage hinzufügen. Um einem Objekt Anmerkungen hinzuzufügen, rufen Sie PutObjectAnnotation nach dem Hochladen des Objekts auf. Um ein vorhandenes Objekt mit seinen Anmerkungen an eine neue Position zu kopieren, verwenden Sie es CopyObject zusammen mit der Standard-Annotationsdirektive.

  • Um Anmerkungen für viele Objekte gleichzeitig hinzuzufügen oder zu aktualisieren, verwenden Sie Batch Operations, um eine Lambda-Funktion aufzurufen, die jedes Objekt aufruftPutObjectAnnotation. Weitere Informationen finden Sie unter Invoke AWS Lambda function.

  • Anmerkungen werden von den folgenden Funktionen nicht unterstützt: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, S3 Express One Zone (Verzeichnis-Buckets) und Amazon S3 Files.

  • Um sicherzustellen, dass Sie Anmerkungen in die aktuelle Version eines Objekts schreiben und nicht in eine, die überschrieben wurde, verwenden Sie den bedingten Header mit oder. x-amz-object-if-match PutObjectAnnotation DeleteObjectAnnotation Dieser Header validiert das ETag des übergeordneten Objekts, um sicherzustellen, dass das Objekt nicht überschrieben wurde, seit der Aufrufer es das letzte Mal gelesen hat. Durch das Hinzufügen von Tags oder Anmerkungen wird das ETag nicht geändert.

  • Sie können eine Anmerkung nicht abhängig vom Vorhandensein oder Fehlen einer anderen Anmerkung hinzufügen. Der x-amz-object-if-match Header validiert nur das ETag des übergeordneten Objekts, nicht den Annotationsstatus.

  • Nutzdaten für Anmerkungen müssen gültiger UTF-8 codierter Text sein. Um Binärdaten zu speichern, codieren Sie die Daten mit Base64, bevor Sie die Anmerkung schreiben.

  • Sie können API-Operationen (PutObjectAnnotation,GetObjectAnnotation,DeleteObjectAnnotation) für Objekte in jeder SpeicherklasseListObjectAnnotations, einschließlich S3 Glacier und S3 Glacier Deep Archive, aufrufen, ohne das Objekt zuerst wiederherzustellen.

Zusätzliche Konfigurationen

In diesem Abschnitt wird erklärt, wie Anmerkungen sich auf andere Konfigurationen beziehen.

Replikation

Wenn Sie S3-Replikation in Ihrem Bucket konfiguriert haben, repliziert Amazon S3 Anmerkungen automatisch. Jede Anmerkung wird unabhängig repliziert. Weitere Informationen finden Sie unter Was repliziert Amazon S3?.

Um Anmerkungen zu replizieren, fügen Sie s3:GetObjectVersionAnnotationForReplication den Quell-Bucket Berechtigungen in Ihrer Replikations-IAM-Rolle hinzu. Weitere Informationen finden Sie unter Einrichten von Berechtigungen für die Live-Replikation.

Um die Replikation von Anmerkungen zu verhindern und gleichzeitig die Objektreplikation zuzulassen, fügen Sie der Replikationsrollenrichtlinie eine s3:ReplicateObjectAnnotation Ablehnungsanweisung für hinzu. Die Objektreplikation ist weiterhin erfolgreich; nur die Replikation von Anmerkungen ist blockiert.

Ereignismeldungen

Amazon S3 kann Ereignisbenachrichtigungen senden, wenn Anmerkungen erstellt, aktualisiert oder gelöscht werden. Sie können die folgenden Ereignistypen konfigurieren:

  • s3:ObjectAnnotation:Put— Wird gesendet, wenn eine Anmerkung erstellt oder aktualisiert wird.

  • s3:ObjectAnnotation:Delete— Wird gesendet, wenn eine Anmerkung gelöscht wird.

Weitere Informationen finden Sie unter Ereignis-Benachrichtigungstypen und -ziele.