Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Format input Amazon S3 untuk item yang dimasukkan secara massal
Item input massal DynamoDB membaca data input dari Amazon S3 dalam dua format: DynamoDB JSON dan Amazon Ion. Anda dapat menyediakan satu objek Amazon S3 atau beberapa objek di bawah objek yang sama Awalan kunci Amazon S3.
Setiap file input dapat secara opsional berisi ekspresi kondisi per item yang mengontrol apakah item ditulis ke tabel. Bagian berikut menjelaskan format yang didukung, opsi kompresi, dan model ekspresi kondisi.
Topik
Format dan kompresi yang didukung
Tentukan format input saat Anda menelepon StartBulkPutItems dengan mengatur InputFormat bidang di Inputs3Konfigurasi, parameter permintaan yang menjelaskan di mana input Anda disimpan di Amazon S3 dan bagaimana input diformatnya. Untuk semua parameter permintaan, lihat Memulai operasi item menempatkan massal.
| Format | Deskripsi |
|---|---|
|
DynamoDB menyusun JSON. Satu objek JSON per baris (Garis JSON |
|
Format teks Amazon Ion. Setiap catatan adalah struktur Ion yang berisi |
Atur InputCompressionType bidang untuk menunjukkan bagaimana objek Amazon S3 Anda dikompresi.
| Jenis kompresi | Deskripsi |
|---|---|
|
Objek adalah GZIP-compressed. |
|
Objek adalah Zstandard-compressed. |
|
Objek tidak terkompresi. |
DynamoDB Json
File dalam format DynamoDB JSON terdiri dari satu objek JSON per baris (Garis JSONItem bidang di DynamoDB menyusun JSON dan bidang kondisi opsional. Jangan gunakan baris baru dalam satu catatan. Untuk cara kerja bidang kondisi, lihat Per-item ekspresi kondisi.
Penempatan tanpa syarat (perilaku default)
Saat Anda menghilangkan bidang kondisi, setiap item mengganti item yang ada dengan kunci utama yang sama:
{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}}} {"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}}} {"Item":{"id":{"S":"item-3"},"name":{"S":"Widget C"},"price":{"N":"4.99"}}}
Kondisi sederhana - sisipkan saja
Tambah attribute_not_exists( untuk mencegah penulisan ulang. Ganti pk)pk dengan nama atribut kunci partisi Anda:
{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}},"ConditionExpression":"attribute_not_exists(id)"}
Ekspresi bernama dengan token substitusi
Gunakan ExpressionAttributeNames dan ExpressionAttributeValues ketika kondisi Anda mereferensikan kata-kata yang dicadangkan atau mengganti nilai atribut:
{"Item":{"id":{"S":"item-2"},"status":{"S":"ACTIVE"},"version":{"N":"3"}},"ConditionExpression":"#s = :v","ExpressionAttributeNames":{"#s":"status"},"ExpressionAttributeValues":{":v":{"S":"ACTIVE"}}} {"Item":{"id":{"S":"item-5"},"status":{"S":"PENDING"},"version":{"N":"2"}},"ConditionExpression":"#ver < :newver","ExpressionAttributeNames":{"#ver":"version"},"ExpressionAttributeValues":{":newver":{"N":"2"}}}
Dalam catatan pertama, item ditulis hanya jika item yang ada status atribut sama ACTIVE. Dalam catatan kedua, item ditulis hanya jika item yang ada version kurang dari 2.
Kondisi campuran dalam satu file
Catatan yang berbeda dalam file yang sama dapat membawa kondisi yang berbeda, atau tidak ada kondisi sama sekali:
{"Item":{"id":{"S":"new-1"},"data":{"S":"hello"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"existing-1"},"data":{"S":"updated"}},"ConditionExpression":"#v = :expected","ExpressionAttributeNames":{"#v":"version"},"ExpressionAttributeValues":{":expected":{"N":"5"}}} {"Item":{"id":{"S":"overwrite-1"},"data":{"S":"replaced"}}}
Dalam contoh ini, catatan pertama menggunakan semantik sisipkan saja. Catatan kedua menggunakan versi guard. Catatan ketiga diganti tanpa syarat karena tidak memiliki kondisi.
Amazon Ion
Amazon Ion
Setiap catatan adalah struktur Ion yang berisi Item bidang dan bidang kondisi opsional, dibatasi oleh baris baru. Setiap baris dimulai dengan penanda versi Ion.
Taruh tanpa syarat
Dalam contoh berikut, item diformat pada beberapa baris untuk meningkatkan keterbacaan. Dalam file input aktual, setiap catatan berada pada satu baris.
$ion_1_0 { Item:{ id:"order-001", amount:99.95, status:"PENDING" } } $ion_1_0 { Item:{ id:"order-002", amount:149.00, status:"SHIPPED" } }
Dengan ekspresi kondisi per item
$ion_1_0 { Item:{ id:"order-001", amount:99.95, status:"PENDING" }, ConditionExpression:"attribute_not_exists(id)" } $ion_1_0 { Item:{ id:"order-002", amount:149.00, status:"SHIPPED" }, ConditionExpression:"#s = :v", ExpressionAttributeNames:{"#s":"status"}, ExpressionAttributeValues:{":v":"ACTIVE"} }
Tabel berikut menunjukkan bagaimana tipe data Ion dipetakan ke tipe data DynamoDB.
| Jenis data ion | Representasi DynamoDB |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tata letak data sumber di Amazon S3
Anda dapat memberikan masukan sebagai objek Amazon S3 tunggal atau sebagai beberapa objek yang disimpan di bawah awalan kunci S3 yang sama. Saat Anda mengatur S3KeyPrefix bidang di InputS3Configuration, DynamoDB membaca semua objek di bawah awalan kunci S3 itu. Untuk panduan tentang cara membagi masukan Anda, lihat Praktik terbaik untuk menempatkan item massal di DynamoDB.
Semua objek di bawah awalan kunci S3 yang ditentukan harus menggunakan format yang sama dan jenis kompresi yang sama. Anda tidak dapat mencampur objek DynamoDB JSON dan Ion, atau mencampur objek terkompresi dan tidak terkompresi, dalam operasi item put massal tunggal.
Per-item ekspresi kondisi
Ekspresi kondisi untuk item put massal ditentukan per item, di dalam file input. Mereka menggunakan sintaks yang sama dengan ekspresi kondisi untuk PutItem operasi. Untuk sintaks lengkapnya, lihat Contoh CLI ekspresi kondisi DynamoDB. Untuk operator dan fungsi yang didukung, lihat Kondisi dan filter ekspresi, operator, dan fungsi di DynamoDB.
Setiap catatan dalam file input Anda berisi bidang berikut:
Item(wajib) — Item yang akan ditulis, dalam format JSON atau Ion yang disusun DynamoDB.ConditionExpression(opsional) — Ekspresi kondisi yang harus dievaluasi menjadi true untuk item yang akan ditulis.ExpressionAttributeNames(opsional) — Peta token substitusi untuk nama atribut dalam ekspresi kondisi.ExpressionAttributeValues(opsional) — Peta token substitusi untuk nilai atribut dalam ekspresi kondisi.
Perilaku evaluasi kondisi
Tabel berikut menjelaskan bagaimana DynamoDB mengevaluasi ekspresi kondisi selama operasi item put massal.
| Skenario | Perilaku |
|---|---|
Tidak ada syarat pada catatan |
Item ditulis tanpa syarat, mengganti item yang ada dengan kunci utama yang sama. |
|
Insert-only Semantik untuk catatan tersebut. Item ditulis hanya jika tidak ada item dengan kunci primer yang sama yang sudah ada di tabel. |
Per-item penjaga versi |
Anda dapat menentukan kondisi yang memeriksa atribut versi, misalnya |
Kondisi tidak terpenuhi |
Item dilewati. DynamoDB melaporkan item yang dilewati hanya jika Anda meminta |
Item yang gagal dalam pemeriksaan kondisi masih ditagih. Lihat perinciannya di Penagihan untuk laporan dan item yang gagal.
Untuk mencapai semantik memasukkan item baru saja
Karena kondisi adalah per item, Anda harus menyertakan ConditionExpression pada setiap catatan jika Anda ingin perilaku put-if-not-exist di seluruh file. Contoh berikut menunjukkan file input DynamoDB JSON di mana setiap catatan membawa attribute_not_exists(id) untuk mencegah penulisan ulang:
{"Item":{"id":{"S":"order-001"},"amount":{"N":"99.95"},"status":{"S":"PENDING"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"order-002"},"amount":{"N":"149.00"},"status":{"S":"SHIPPED"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"order-003"},"amount":{"N":"25.50"},"status":{"S":"DELIVERED"}},"ConditionExpression":"attribute_not_exists(id)"}
Jika Anda menghasilkan file input dari pipeline ETL, tambahkan ConditionExpression bidang ke templat catatan Anda. Jika Anda memiliki file yang ada tanpa kondisi, proses ulang untuk menyuntikkan kondisi sebelum Anda memulai operasi.
Pelaporan kegagalan kondisi
Saat Anda mengonfigurasi lokasi keluaran Amazon S3 Anda, sertakan CONDITION_CHECK_FAILURE di OutputType daftar. DynamoDB mengeluarkan catatan untuk item yang tidak memenuhi ekspresi kondisinya ke bucket Amazon S3 keluaran Anda. Anda dapat mengurai file keluaran ini untuk mengidentifikasi item mana yang dilewati dan mengambil tindakan korektif. Saat input Anda menggunakan ekspresi kondisi, minta CONDITION_CHECK_FAILURE jadi item yang dilewati dilaporkan, karena tanpanya DynamoDB tidak menyimpan catatan atau menghitungnya.
Operasi yang dicoba ulang atau dilanjutkan dapat melaporkan konflik pemeriksaan kondisi untuk item yang ditulis operasi itu sendiri sebelumnya. Untuk membedakan ini dari konflik dengan data yang sudah ada sebelumnya, bandingkan gambar yang ada dalam laporan dengan item yang Anda berikan. Jika mereka sama, operasi menulis item itu dan konflik diharapkan.
Item yang dilaporkan di sini tidak ditulis pada upaya yang menghasilkan catatan. Mereka masih ditagih. Untuk informasi selengkapnya, lihat Penagihan untuk laporan dan item yang gagal. Untuk merekonsiliasi hasil operasi item put massal, gunakan file keluaran Amazon S3 bersama dengan DescribeBulkOperation menghitung. Untuk alur kerja lengkap, lihat Rekonsiliasi hasil.
Kesalahan validasi yang menghentikan objek
Beberapa kesalahan mencegah DynamoDB menemukan batas rekaman berikutnya. Kesalahan ini termasuk JSON atau Ion yang salah bentuk atau terpotong, struktur catatan yang tidak valid, hilang atau duplikat Item bidang, bidang tingkat atas yang tidak diketahui, nilai DynamoDB tidak valid, tidak valid UTF-8, input yang mencapai batas bersarang parser, catatan yang melebihi batas baca parser, kesalahan dekompresi, ketidakcocokan kompresi, dan beberapa kesalahan pembacaan objek Amazon S3. Catatan hanya dapat berisi bidang tingkat atas ini: Item, ConditionExpression, ExpressionAttributeNames, dan ExpressionAttributeValues.
Ketika salah satu kesalahan ini terjadi, DynamoDB menghasilkan satu hasil kesalahan dan berhenti membaca objek Amazon S3 itu. Objek input lainnya dapat berlanjut. Jika Anda meminta ERROR output, baris laporan berisi itemLocation.inputSourceArn dan errorMessages, tetapi tidak mengandung itemLocation.itemIndex. Kesalahan validasi yang berlaku untuk satu catatan lengkap termasuk itemIndex dan tidak menghentikan sisa objek.
Manifes penyelesaian menandai objek PARTIALLY_PROCESSED dan mencantumkan catatan lengkap di processedRanges. Jika DynamoDB tidak dapat mengonfirmasi bahwa ia membaca semua byte input yang disimpan, operasi berakhir FAILED dengan kode kegagalan ValidationException. Jika DynamoDB membaca semua byte yang disimpan sebelum mendeteksi kesalahan, operasi dapat berakhir COMPLETED_WITH_ERRORS bersama ProcessedInputBytes sama dengan TotalInputBytes. Gunakan status akhir, ERROR laporan, dan penyelesaian manifes bersama-sama untuk mengidentifikasi catatan untuk diperbaiki atau dikirim kembali. DynamoDB tidak menagih catatan yang ditolak validasi saat menulis tabel. Lihat informasi yang lebih lengkap di Penagihan untuk laporan dan item yang gagal.