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 khusus antara ukuran 1 byte dan 1 MiB 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, penyematan, AI-generated label moderasi konten, keluaran klasifikasi dokumen, garis keturunan data dan jejak audit, label kepatuhan seperti tanda PII atau kebijakan retensi, metadata pencitraan medis, informasi hak aset digital, dan status pipeline 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. S3 Metadata menyimpan data anotasi dalam Apache Iceberg tabel yang dikelola sepenuhnya yang diperbarui secara otomatis oleh Amazon S3. Untuk informasi selengkapnya, lihat Menemukan data Anda dengan tabel Metadata S3.
Anotasi tersedia di semua Wilayah komersial dan AWS Wilayah China (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 (payload) |
| Format data | Key-value pasangan string | UTF-8 Teks apa pun (JSON, XML, YAML, dll.) |
| Mutabilitas | Ya (PutObjectTagging) | Ya (PutObjectAnnotation) |
| Tetapkan saat mengunggah | Ya (PutObject, POST) | Tidak (PutObjectAnnotation hanya, setelah diunggah) |
Pilih anotasi saat Anda perlu menyimpan data terstruktur (seperti JSON atau XML), 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 mengganti anotasi pada objek. Anda menentukan nama anotasi dan payload dalam permintaan.
-
GetObjectAnnotation— Mengembalikan payload dari anotasi tertentu berdasarkan nama.
-
ListObjectAnnotations— Mengembalikan daftar anotasi pada objek. Tanggapan mencakup nama, ukuran, ETag, dan tanggal modifikasi terakhir setiap anotasi.
-
DeleteObjectAnnotation— Menghapus anotasi tertentu berdasarkan 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— Meng
AnnotationTableConfigurationResultembalikan dalam 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. Batas berikut berlaku:
-
Nama anotasi dapat memiliki panjang hingga 512 byte (UTF-8), tunduk pada aturan penamaan di bawah ini.
-
Muatan anotasi harus berukuran antara 1 byte dan 1 MiB.
-
Total penyimpanan anotasi per objek dapat mencapai 1 GiB (1.000 anotasi pada 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:
-
Harus antara 1 dan 512 byte panjangnya.
-
Hanya dapat berisi karakter berikut: huruf (bahasa apa pun), digit (0-9), garis bawah (
_), titik (.), dan tanda hubung ().- -
Tidak dapat memulai dengan
awsataus3(tidak peka huruf besar/kecil). Misalnya,,,awsAWSs3, dan semuanya awS3alan yang dicadangkan. -
Tidak boleh kosong atau hanya terdiri dari spasi putih.
Enkripsi
Anotasi secara otomatis dienkripsi saat diam menggunakan konfigurasi enkripsi yang sama dengan objek induk. Jenis enkripsi diwarisi dari objek induk, bukan default bucket.
-
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. S3 Bucket Keys didukung.
-
DSSE-KMSJika objek induk menggunakan enkripsi sisi server dual-layer dengan AWS KMS kunci (DSSE-KMS), anotasi dienkripsi dengan DSSE-KMS menggunakan kunci yang sama.
-
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 dengan SSE-C, Amazon S3 mengembalikan kesalahan.
Checksum
Saat Anda 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 salin, algoritma baru berlaku untuk objek dan anotasinya.
Algoritma yang didukung: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.
Jika anotasi tidak memiliki algoritma checksum atau nilai checksum yang ditentukan, Amazon S3 menggunakan CRC-64/NVME algoritma 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 mempengaruhi anotasi pada versi lain. Mengganti objek menggantikan anotasinya dengan anotasi apa pun yang dimiliki versi baru (jika tidak ada, secara efektif menghapusnya).
Menambahkan, memperbarui, atau menghapus anotasi tidak mengubah ETag objek induk.
Dalam bucket tanpa versi, jika Anda menghapus atau mengganti 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 memiliki versi independen. Saat Anda mengganti 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 bucket berversi. Tidak seperti objek dalam bucket berversi, anotasi tidak memiliki penanda hapus atau riwayat versi. Setelah Anda menghapus anotasi, itu tidak dapat dipulihkan.
Menyalin 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.
Saat Anda menyalin objek menggunakan unggahan multibagian (misalnya, ketika AWS SDK AWS CLI atau menggunakan Transfer Manager untuk objek yang lebih besar dari sekitar 8 MB), anotasi tidak disalin secara default. Untuk menyertakan anotasi, tent --copy-props all ukan dalam AWS CLI atau konfigurasi SDK yang setara. Dengan opt-in ini, SDK membaca anotasi sumber, menyelesaikan unggahan multipart, 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 upload
PutObjectatau beberapa bagian. Untuk menambahkan anotasi ke objek, panggilPutObjectAnnotationsetelah objek diunggah. Untuk menyalin objek yang ada dengan anotasinya ke lokasi baru, gunakanCopyObjectdengan direktif anotasi default. -
Untuk menambah atau memperbarui anotasi di banyak objek secara massal, gunakan Batch Operations untuk memanggil fungsi Lambda yang memang
PutObjectAnnotationgil setiap objek. Untuk informasi selengkapnya, lihat Panggil AWS Lambda Fungsi. -
Anotasi tidak didukung oleh fitur-fitur berikut: Laporan Inventaris S3, Gateway API, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on 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 diganti, gunakan header
x-amz-object-if-matchbersyarat denganPutObjectAnnotationatau.DeleteObjectAnnotationHeader ini memvalidasi ETag objek induk untuk mengonfirmasi bahwa objek belum diganti 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 dikodekan yang valid. Untuk menyimpan data biner, enkode data dengan Base64 sebelum menulis anotasi.
-
Anda dapat memanggil operasi API anotasi (
PutObjectAnnotationGetObjectAnnotation,,ListObjectAnnotations,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 mereplikasi 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 tol s3:ReplicateObjectAnnotation ak untuk 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.
