DynoTable
Pemula4 menit baca

DynamoDB JSON & Marshalling

Pertama kali Anda membaca data mentah dari API DynamoDB, ia tak terlihat seperti JSON yang Anda masukkan. Objek biasa seperti {"status": "open", "priority": 3} kembali sebagai {"status": {"S": "open"}, "priority": {"N": "3"}}. Setiap nilai dibungkus dalam objek satu-key yang menamai tipenya. Pembungkusan itu adalah DynamoDB JSON, dan mengonversi ke dan darinya disebut marshalling.

Itu bukan derau — itu cara DynamoDB menjaga tipe tetap tak ambigu di kabel. Tetapi ia menjegal siapa pun yang mengharapkan JSON biasa, dan menulisnya dengan tangan rawan kesalahan.

Apa itu DynamoDB JSON?

DynamoDB JSON adalah format kabel bertag tipe yang digunakan DynamoDB, di mana setiap nilai dibungkus dalam objek satu-key yang menamai tipenya — {"S": "open"} untuk string, {"N": "3"} untuk angka. Proses mengonversi JSON biasa ke format ini (dan sebaliknya) disebut marshalling. Format ini menjaga tipe tetap tak ambigu, karena JSON biasa tidak bisa mengekspresikan set, binary, maupun perbedaan antara "3" dan 3.

  • DynamoDB JSON menandai tiap nilai dengan tipenya — {"S": "..."} untuk string, {"N": "..."} untuk angka, dan seterusnya.
  • Marshalling = JSON biasa → DynamoDB JSON. Unmarshalling = kebalikannya.
  • Angka adalah string di kabel — {"N": "3"}, bukan {"N": 3} — untuk menjaga presisi.
  • Tag tipe itu adalah sistem tipe-data yang sudah Anda modelkan: S, N, B, BOOL, NULL, L, M, SS, NS, BS.
  • Jangan menulisnya dengan tangan. Document client SDK (atau sebuah konverter) me-marshal untuk Anda; lakukan manual hanya saat debugging atau membangun expression.

Masalahnya: JSON biasa tidak cukup

JSON punya persis tiga jenis skalar — string, angka, boolean — ditambah null, array, dan objek. DynamoDB punya lebih: binary, dan tiga tipe set (string set, number set, binary set) yang sama sekali tak bisa diekspresikan JSON. JSON juga tak bisa membedakan string "3" dari angka 3, atau list dari set.

Jadi DynamoDB tak bisa begitu saja menyimpan JSON Anda apa adanya — ia perlu tipe pasti tiap nilai dinyatakan eksplisit. Deskriptor tipe itulah caranya melakukannya, tanpa kehilangan, pada setiap request dan response.

Cara kerja enkode

Setiap nilai atribut menjadi objek satu-key yang key-nya adalah deskriptor tipe:

DeskriptorTipeContoh
SString{"S": "open"}
NNumber (sebagai string){"N": "3"}
BBinary{"B": "dGV4dA=="}
BOOLBoolean{"BOOL": true}
NULLNull{"NULL": true}
LList{"L": [{"S": "a"}, {"N": "1"}]}
MMap{"M": {"k": {"S": "v"}}}
SS / NS / BSString / Number / Binary set{"SS": ["a", "b"]}

List dan map menyarangkan deskriptor yang sama sampai ke dasar, jadi Item berstruktur dalam menjadi terbungkus dalam. Angka melaju di kabel sebagai string dengan sengaja — itu memungkinkan DynamoDB menjaga presisi arbitrer yang akan diam-diam dibulatkan oleh angka JSON (sebuah double IEEE-754). Ini adalah tipe data yang sama yang Anda modelkan; DynamoDB JSON hanyalah bentuk eksplisit-di-kabel-nya, didefinisikan dalam referensi API low-level AWS.

Contoh terkerjakan: entri audit-log

JSON biasa yang akan Anda tulis di app Anda:

{
  "actor": "u-204",
  "action": "ticket.close",
  "ticketId": 8842,
  "tags": ["billing", "urgent"],
  "redacted": false
}

Di-marshal ke DynamoDB JSON untuk API:

{
  "actor": {"S": "u-204"},
  "action": {"S": "ticket.close"},
  "ticketId": {"N": "8842"},
  "tags": {"SS": ["billing", "urgent"]},
  "redacted": {"BOOL": false}
}

Perhatikan pilihan yang dibuat marshaller: ticketId menjadi N dengan nilai string; tags menjadi string set (SS), bukan list — keputusan disengaja, karena set men-dedupe dan tak terurut. Apakah tags seharusnya SS atau L adalah keputusan pemodelan yang tak bisa diambil konverter untuk Anda, yang justru menjadi alasan memahami enkode-nya itu penting.

Mengonversi di DynoTable

Anda jarang perlu membaca atau menulis ini dengan tangan. Tempel JSON biasa ke dalam konverter DynamoDB JSON untuk me-marshal-nya (dan kembali), dan saat Anda merakit sebuah request, expression builder DynamoDB memancarkan map attribute-value yang ter-marshal dengan benar bersama expression-nya. Di app itu sendiri, DynoTable menampilkan Item sebagai nilai biasa yang mudah dibaca dan me-marshal-nya untuk Anda saat penulisan.

DynoTable menampilkan sebuah Item sebagai nilai biasa, dengan DynamoDB JSON mentah tersedia.
DynoTable menampilkan sebuah Item sebagai nilai biasa, dengan DynamoDB JSON mentah tersedia.

Jebakan dan langkah berikutnya

  • Angka adalah string dalam DynamoDB JSON — {"N": "3"}. Tanda kutip penting; jangan memancarkan angka telanjang.
  • Set vs list adalah keputusan pemodelan yang dibuat tampak oleh enkode-nya — pilih dengan sengaja (lihat tipe data).
  • Utamakan document client SDK ketimbang marshalling-tangan di kode app; cadangkan DynamoDB JSON manual untuk debugging dan expression.
  • String kosong diizinkan dalam Item tetapi secara historis menjegal perkakas — validasi kasus tepi.

Ingin menjelajahi Item sebagai nilai biasa alih-alih membaca tag tipe dengan mata? Unduh DynoTable dan bekerja dengan data Anda secara langsung.

Diperbarui