Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Menganotasi objek Anda
Gunakan anotasi untuk melampirkan muatan data bernama ke objek Amazon S3 Anda. Setiap anotasi adalah payload metadata kustom antara 1 byte dan 1 MiB dalam ukuran yang dapat Anda buat, ambil, daftar, dan hapus tanpa memodifikasi objek itu sendiri.
Anda dapat mengaitkan hingga 1.000 anotasi dengan versi objek. Setiap anotasi memiliki nama unik dan dapat menyimpan data terstruktur seperti AI-generated label, konteks dokumen, hasil pemrosesan, atau catatan kepatuhan.
Kasus penggunaan umum termasuk menyimpan hasil inferensi pembelajaran mesin, AI-generated penyematan, label moderasi konten, keluaran klasifikasi dokumen, garis keturunan data dan jejak audit, label kepatuhan seperti bendera PII atau kebijakan retensi, metadata pencitraan medis, informasi hak aset digital, dan status pipa ETL di samping objek sumber.
Anda mengelola anotasi menggunakan operasi API khusus, sehingga Anda tidak perlu mengunggah ulang objek untuk menambah atau memperbarui metadata.
Anda dapat mengaktifkan tabel anotasi sebagai bagian dari konfigurasi Metadata S3 untuk menanyakan data anotasi dalam skala besar menggunakan Athena dan layanan analitik lainnya. Metadata S3 menyimpan data anotasi dalam tabel yang dikelola sepenuhnya yang Apache Iceberg diperbarui secara otomatis Amazon S3. Untuk informasi selengkapnya, lihat Menemukan data Anda dengan tabel Metadata S3.
Anotasi tersedia di semua AWS Wilayah komersial dan Wilayah Tiongkok (Beijing dan Ningxia). Anotasi tidak tersedia di Wilayah Timur Tengah (UEA) dan Timur Tengah (Bahrain). Tabel anotasi Metadata S3 tersedia di semua Wilayah di mana Metadata S3 tersedia.
Kapan menggunakan anotasi vs. tag objek
Gunakan perbandingan berikut untuk menentukan apakah anotasi atau tag objek paling cocok untuk kasus penggunaan Anda.
| Karakteristik | Tanda objek | Anotasi |
|---|---|---|
| Maksimum per objek | 10 per versi objek | 1.000 per versi objek |
| Ukuran maksimum | 128 karakter (kunci) +256 karakter (nilai) | 512 byte (nama) +1 MiB (muatan) |
| Format data | Key-value pasangan tali | UTF-8 Teks apa pun (JSON, XHTML, YAMAL, dll.) |
| Mutabilitas | Ya (PutObjectTagging) | Ya (PutObjectAnnotation) |
| Setel saat mengunggah | Ya (PutObject, POST) | Tidak (PutObjectAnnotation hanya, setelah diunggah) |
Pilih anotasi saat Anda perlu menyimpan data terstruktur (seperti JSON atau XHTML), muatan yang lebih besar dari 256 karakter, atau lebih dari 10 entri metadata per objek. Pilih tag objek saat Anda memerlukan integrasi kebijakan IAM, pemfilteran aturan Siklus Hidup Amazon S3, atau pelaporan alokasi biaya.
Operasi API untuk anotasi
Amazon S3 mendukung operasi API berikut untuk bekerja dengan anotasi:
-
PutObjectAnnotation— Membuat atau menimpa anotasi pada objek. Anda menentukan nama anotasi dan payload dalam permintaan.
-
GetObjectAnnotation— Mengembalikan payload dari anotasi tertentu dengan nama.
-
ListObjectAnnotations— Mengembalikan daftar anotasi pada objek. Respons mencakup setiap nama anotasi, ukuran, ETag, dan tanggal modifikasi terakhir.
-
DeleteObjectAnnotation— Menghapus anotasi tertentu dengan nama.
Amazon S3 juga mendukung anotasi dalam operasi API berikut:
-
CopyObject— Menyalin anotasi dari objek sumber secara default. Anda dapat menentukan
x-amz-annotation-directiveheader untuk mengontrol apakah anotasi disalin (COPY) atau dikecualikan (EXCLUDE). -
UpdateBucketMetadataAnnotationTableConfiguration— Mengaktifkan atau menonaktifkan tabel anotasi dalam konfigurasi Metadata S3 Anda.
-
CreateBucketMetadataConfiguration— Menerima
AnnotationTableConfigurationparameter baru untuk mengaktifkan tabel anotasi saat Anda membuat konfigurasi Metadata S3. -
GetBucketMetadataConfiguration— Pengembalian
AnnotationTableConfigurationResultdalam respons, yang menunjukkan status tabel anotasi saat ini.
Batas anotasi
Setiap versi objek mendukung hingga 1.000 anotasi. Anotasi yang terkait dengan versi objek harus memiliki nama anotasi yang unik. Batasan berikut berlaku:
-
Nama anotasi dapat memiliki panjang hingga 512 byte (UTF-8), tunduk pada aturan penamaan di bawah ini.
-
Payload anotasi harus berukuran antara 1 byte dan 1 MiB.
-
Total penyimpanan anotasi per objek dapat mencapai 1 GiB (1.000 anotasi masing-masing 1 MiB).
-
Algoritma checksum yang didukung: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Aturan penamaan anotasi
Nama anotasi harus memenuhi persyaratan berikut:
-
Panjangnya harus antara 1 dan 512 byte.
-
Hanya dapat berisi karakter berikut: huruf (bahasa apa pun), digit (0-9), garis bawah (), periode (
_), dan tanda hubung (.).- -
Tidak dapat memulai dengan
awsataus3(case-insensitive). Misalnya,,aws,AWSs3, dan semuanyaS3merupakan awalan yang dicadangkan. -
Tidak boleh kosong atau hanya terdiri dari spasi.
Enkripsi
Anotasi secara otomatis dienkripsi saat istirahat menggunakan konfigurasi enkripsi yang sama dengan objek induk. Jenis enkripsi diwarisi dari objek induk, bukan bucket default.
-
SSE-S3— Jika objek induk menggunakan enkripsi sisi server dengan kunci terkelola Amazon S3 (SSE-S3), anotasi dienkripsi dengan. SSE-S3 Jika objek induk tidak memiliki enkripsi sisi server yang dikonfigurasi, anotasi dienkripsi secara default. SSE-S3
-
SSE-KMS— Jika objek induk menggunakan enkripsi sisi server dengan AWS KMS kunci (SSE-KMS), anotasi dienkripsi dengan kunci KMS yang sama. Ini berlaku untuk kunci yang dikelola pelanggan dan kunci AWS terkelola. Tombol Bucket S3 didukung.
-
DSSE-KMS— Jika objek induk menggunakan enkripsi sisi server dual-layer dengan AWS KMS keys (DSSE-KMS), anotasi dienkripsi dengan menggunakan kunci yang sama. DSSE-KMS
-
SSE-C— Server-side enkripsi dengan kunci yang disediakan pelanggan (SSE-C) tidak didukung untuk anotasi. Jika Anda mencoba menambahkan anotasi ke objek yang dienkripsi, Amazon SSE-C S3 mengembalikan kesalahan.
Checksum
Saat mengunggah anotasi menggunakanPutObjectAnnotation, Anda dapat memberikan checksum untuk memverifikasi integritas data. Algoritma checksum untuk anotasi independen dari algoritma checksum objek induk.
Saat Anda menyalin objek menggunakanCopyObject, Amazon S3 mempertahankan nilai checksum anotasi dari sumbernya. Jika Anda menentukan algoritma checksum yang berbeda dalam permintaan salinan, algoritme baru berlaku untuk objek dan anotasinya.
Algoritma yang didukung: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Jika anotasi tidak memiliki algoritme checksum atau nilai checksum yang ditentukan, Amazon S3 menggunakan CRC-64/NVME algoritme untuk menghitung nilai checksum untuk anotasi.
Perilaku pembuatan versi
Anotasi dilampirkan ke versi objek tertentu.
Anotasi dari satu versi objek tidak tergantung pada anotasi pada versi lain dari objek yang sama. Membuat versi baru tidak menyalin anotasi dari versi sebelumnya. Menghapus atau menambahkan anotasi pada satu versi tidak memengaruhi anotasi pada versi lain. Menimpa objek menggantikan anotasinya dengan anotasi apa pun yang dimiliki versi baru (jika tidak ada, hapus secara efektif).
Menambahkan, memperbarui, atau menghapus anotasi tidak mengubah ETag objek induk.
Dalam bucket yang tidak berversi, jika Anda menghapus atau menimpa objek, anotasi akan dihapus dengannya.
Dalam bucket berversi, perilaku berikut berlaku:
-
Permintaan DELETE sederhana (tanpa menentukan ID versi) membuat penanda hapus tetapi mempertahankan anotasi pada versi yang mendasarinya.
-
Menghapus ID versi tertentu akan menghapus versi tersebut dan semua anotasi terkait.
-
Anotasi tidak berversi independen. Saat Anda menimpa anotasi dengan nama yang sama, Amazon S3 menggantikan nilai sebelumnya tanpa membuat versi objek baru.
penting
Penghapusan anotasi bersifat permanen dan tidak dapat diubah, bahkan dalam ember berversi. Tidak seperti objek dalam bucket berversi, anotasi tidak memiliki penanda hapus atau riwayat versi. Setelah Anda menghapus anotasi, anotasi tidak dapat dipulihkan.
Salin perilaku dan konsistensi
Saat Anda menyalin objek menggunakan CopyObject API (untuk objek yang lebih kecil dari 5 GiB), Amazon S3 menyalin anotasi bersama dengan objek dalam satu operasi.
Ketika Anda menyalin objek menggunakan unggahan multipart (misalnya, ketika AWS CLI atau AWS SDK menggunakan Transfer Manager untuk objek yang lebih besar dari sekitar 8 MB), anotasi tidak disalin secara default. Untuk menyertakan anotasi, tentukan --copy-props all dalam AWS CLI atau konfigurasi SDK yang setara. Dengan keikutsertaan ini, SDK membaca anotasi sumber, menyelesaikan unggahan multibagian, dan kemudian menulis setiap anotasi ke tujuan. Antara penyelesaian unggahan dan penulisan anotasi terakhir, objek tujuan ada tanpa semua anotasinya.
Pertimbangan-pertimbangan
-
Anda tidak dapat menambahkan anotasi sebagai bagian dari permintaan unggahan
PutObjectatau multibagian. Untuk menambahkan anotasi ke objek, panggilPutObjectAnnotationsetelah objek diunggah. Untuk menyalin objek yang ada dengan anotasi ke lokasi baru, gunakanCopyObjectdengan direktif anotasi default. -
Untuk menambahkan atau memperbarui anotasi di banyak objek secara massal, gunakan Operasi Batch untuk memanggil fungsi Lambda yang memanggil
PutObjectAnnotationsetiap objek. Untuk informasi selengkapnya, lihat Panggil AWS Lambda Fungsi. -
Anotasi tidak didukung oleh fitur-fitur berikut: Laporan Inventaris S3, API Gateway, Lensa Penyimpanan S3, Gateway File Amazon S3, Amazon FSx, S3 di Outposts, S3 Express One Zone (bucket direktori), dan File Amazon S3.
-
Untuk memastikan Anda menulis anotasi ke versi objek saat ini dan bukan yang telah ditimpa, gunakan header
x-amz-object-if-matchbersyarat dengan atau.PutObjectAnnotationDeleteObjectAnnotationHeader ini memvalidasi ETag objek induk untuk mengonfirmasi bahwa objek belum ditimpa sejak pemanggil terakhir membacanya. Menambahkan tag atau anotasi tidak mengubah ETag. -
Anda tidak dapat menambahkan anotasi secara kondisional pada ada atau tidak adanya anotasi lain.
x-amz-object-if-matchHeader memvalidasi ETag objek induk saja, bukan status anotasi. -
Muatan anotasi harus berupa teks yang UTF-8 disandikan yang valid. Untuk menyimpan data biner, encode data dengan Base64 sebelum menulis anotasi.
-
Anda dapat memanggil operasi API anotasi (
PutObjectAnnotation,,GetObjectAnnotationListObjectAnnotations,DeleteObjectAnnotation) pada objek di kelas penyimpanan apa pun, termasuk S3 Glacier dan S3 Glacier Deep Archive, tanpa memulihkan objek terlebih dahulu.
Konfigurasi tambahan
Bagian ini menjelaskan bagaimana anotasi berhubungan dengan konfigurasi lain.
Replikasi
Jika Replikasi S3 dikonfigurasi di bucket, Amazon S3 akan mereplikasi anotasi secara otomatis. Setiap anotasi bereplikasi secara independen. Untuk informasi selengkapnya, lihat Apa yang direplikasi Amazon S3?.
Untuk mereplikasi anotasi, tambahkan s3:GetObjectVersionAnnotationForReplication izin bucket sumber di peran IAM replikasi Anda. Untuk informasi selengkapnya, lihat Menyiapkan izin untuk replikasi langsung.
Untuk mencegah replikasi anotasi sambil mengizinkan replikasi objek, tambahkan pernyataan penolakan untuk s3:ReplicateObjectAnnotation dalam kebijakan peran replikasi. Replikasi objek terus berhasil; hanya replikasi anotasi yang diblokir.
Notifikasi peristiwa
Amazon S3 dapat mengirim pemberitahuan acara saat anotasi dibuat, diperbarui, atau dihapus. Anda dapat mengonfigurasi jenis acara berikut:
-
s3:ObjectAnnotation:Put— Dikirim saat anotasi dibuat atau diperbarui. -
s3:ObjectAnnotation:Delete— Dikirim saat anotasi dihapus.
Untuk informasi selengkapnya, lihat Jenis dan tujuan pemberitahuan peristiwa.
