View a markdown version of this page

Format input Amazon S3 untuk item yang dimasukkan secara massal - Amazon DynamoDB

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.

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_JSON

DynamoDB menyusun JSON. Satu objek JSON per baris (Garis JSON format). Setiap baris berisi Item bidang dan bidang kondisi opsional.

ION

Format teks Amazon Ion. Setiap catatan adalah struktur Ion yang berisi Item bidang dan bidang kondisi opsional, dibatasi oleh baris baru.

Atur InputCompressionType bidang untuk menunjukkan bagaimana objek Amazon S3 Anda dikompresi.

Jenis kompresi Deskripsi

GZIP

Objek adalah GZIP-compressed.

ZSTD

Objek adalah Zstandard-compressed.

NONE

Objek tidak terkompresi.

DynamoDB Json

File dalam format DynamoDB JSON terdiri dari satu objek JSON per baris (Garis JSON format). Setiap baris berisi Item 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(pk) untuk mencegah penulisan ulang. Ganti 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 adalah format serialisasi data hierarkis yang diketik dengan kaya, menggambarkan diri sendiri. Saat Anda menggunakan format Ion untuk item put massal, tipe data Ion dipetakan ke tipe data DynamoDB di tabel target.

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

catatan

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

string

String (S)

bool

Boolean (BOOL)

decimal

Number (N)

blob

Binary (B)

list (dengan anotasi $dynamodb_SS, $dynamodb_NS, atau $dynamodb_BS)

Set (SS, NS, BS)

list

List (L)

struct

Map (M)

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.

catatan

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.

attribute_not_exists(pk)

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 #v = :expected. Ini memungkinkan migrasi lintas wilayah yang aman dan kasus penggunaan sinkronisasi inkremental. Untuk menulis item baru dan versi yang lebih baru, gunakan attribute_not_exists(#v) OR #v < :new.

Kondisi tidak terpenuhi

Item dilewati. DynamoDB melaporkan item yang dilewati hanya jika Anda meminta CONDITION_CHECK_FAILURE jenis keluaran. Untuk informasi selengkapnya, lihat Pelaporan kegagalan kondisi.

penting

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.