Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Bekerja dengan item dan atribut di DynamoDB Di Amazon DynamoDB, *item* adalah koleksi atribut. Setiap atribut mempunyai nama dan nilai. Nilai atribut dapat berupa skalar, himpunan, atau jenis dokumen. Untuk informasi selengkapnya, lihat [Amazon DynamoDB: Cara kerjanya](HowItWorks.md). DynamoDB menyediakan empat operasi untuk fungsionalitas dasar buat, baca, perbarui, dan hapus (CRUD). Semua operasi ini bersifat atom. + `PutItem` — Membuat item. + `GetItem` — Membaca item. + `UpdateItem` — Memperbarui item. + `DeleteItem` — Menghapus item. Setiap operasi ini mengharuskan Anda menentukan kunci primer item yang ingin Anda gunakan. Misalnya, untuk membaca item menggunakan `GetItem`, Anda harus menentukan kunci partisi dan kunci urutan (jika ada) untuk item tersebut. Selain empat operasi CRUD dasar, DynamoDB juga menyediakan hal berikut ini: + `BatchGetItem` — Membaca hingga 100 item dari satu tabel atau lebih. + `BatchWriteItem` — Membuat atau menghapus hingga 25 item dalam satu atau beberapa tabel. Operasi batch ini menggabungkan beberapa operasi CRUD ke dalam satu permintaan. Selain itu, operasi batch membaca dan menulis item secara paralel untuk meminimalkan latensi respons. Bagian ini menjelaskan cara menggunakan operasi ini dan mencakup topik terkait, seperti pembaruan bersyarat dan penghitung atom. Bagian ini juga mencakup contoh kode yang menggunakan file AWS SDKs. **Topics** + [Ukuran dan format item DynamoDB](CapacityUnitCalculations.md) + [Membaca item](#WorkingWithItems.ReadingData) + [Menulis item](#WorkingWithItems.WritingData) + [Nilai yang dikembalikan](#WorkingWithItems.ReturnValues) + [Operasi batch](#WorkingWithItems.BatchOperations) + [Penghitung atom](#WorkingWithItems.AtomicCounters) + [Penulisan bersyarat](#WorkingWithItems.ConditionalUpdate) + [Menggunakan ekspresi di DynamoDB](Expressions.md) + [Menggunakan time to live (TTL) di DynamoDB](TTL.md) + [Menanyakan tabel di DynamoDB](Query.md) + [Memindai tabel di DynamoDB](Scan.md) + [PartiQL - Bahasa kueri yang kompatibel dengan SQL untuk Amazon DynamoDB](ql-reference.md) + [Bekerja dengan item: Java](JavaDocumentAPIItemCRUD.md) + [Bekerja dengan item: .NET](LowLevelDotNetItemCRUD.md) ## Membaca item Untuk membaca item dari tabel DynamoDB, gunakan operasi `GetItem`. Anda harus memberikan nama tabel, beserta kunci primer item yang Anda inginkan. **Example** AWS CLI Contoh berikut menunjukkan cara membaca item dari `ProductCatalog` tabel. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' ``` **catatan** Dengan `GetItem`, Anda harus menentukan *seluruh* kunci primer, bukan hanya sebagian darinya. Misalnya, jika tabel memiliki kunci primer gabungan (kunci partisi dan kunci urutan), Anda harus menyediakan nilai untuk kunci partisi dan nilai untuk kunci urutan. Pada akhirnya, permintaan `GetItem` melakukan pembacaan konsisten secara default. Sebagai gantinya, Anda dapat menggunakan parameter `ConsistentRead` untuk meminta bacaan sangat konsisten. (Ini mengkonsumsi unit kapasitas baca tambahan, tetapi mengembalikan sebagian besar up-to-date versi item.) `GetItem` mengembalikan semua atribut item. Anda dapat menggunakan *ekspresi proyeksi* untuk mengembalikan sebagian atribut saja. Untuk informasi selengkapnya, lihat [Menggunakan ekspresi proyeksi di DynamoDB](Expressions.ProjectionExpressions.md). Untuk mengembalikan jumlah unit kapasitas baca yang dikonsumsi oleh `GetItem`, tetapkan parameter `ReturnConsumedCapacity` menjadi `TOTAL`. **Example** Berikut AWS Command Line Interface (AWS CLI) contoh menunjukkan beberapa `GetItem` parameter opsional. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL ``` ## Menulis item Untuk membuat, memperbarui, atau menghapus item dalam tabel DynamoDB, gunakan salah satu operasi berikut: + `PutItem` + `UpdateItem` + `DeleteItem` Untuk setiap operasi ini, Anda harus menentukan seluruh kunci primer, bukan hanya sebagian saja. Misalnya, jika tabel memiliki kunci primer gabungan (kunci partisi dan kunci urutan), Anda harus memberikan nilai untuk kunci partisi dan nilai untuk kunci urutan. Untuk mengembalikan jumlah unit kapasitas tulis yang digunakan oleh salah satu operasi ini, atur parameter `ReturnConsumedCapacity` ke salah satu dari berikut ini: + `TOTAL` — Mengembalikan jumlah total unit kapasitas tulis yang dikonsumsi. + `INDEXES` — Mengembalikan jumlah total unit kapasitas tulis yang digunakan, dengan subtotal untuk tabel dan indeks sekunder apa pun yang terpengaruh oleh operasi. + `NONE` — Tidak ada detail kapasitas tulis dikembalikan. (Ini adalah pengaturan default.) ### PutItem `PutItem` membuat item baru. Jika item dengan kunci yang sama sudah ada di tabel, item tersebut akan diganti dengan item baru. **Example** Tulis item baru ke tabel `Thread`. Kunci primer untuk `Thread` terdiri dari `ForumName` (kunci partisi) dan `Subject` (kunci urutan). ``` aws dynamodb put-item \ --table-name Thread \ --item file://item.json ``` Argumen untuk `--item` disimpan dalam file `item.json`. ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} } ``` ### UpdateItem Jika item dengan kunci tertentu tidak ada, `UpdateItem` akan membuat item baru. Jika tidak, ini akan mengubah atribut item yang sudah ada. Anda menggunakan *ekspresi pembaruan* untuk menentukan atribut yang ingin Anda ubah dan nilai barunya. Untuk informasi selengkapnya, lihat [Menggunakan ekspresi pembaruan di DynamoDB](Expressions.UpdateExpressions.md). Dalam ekspresi pembaruan, Anda menggunakan nilai atribut ekspresi sebagai pengganti nilai aktual. Untuk informasi selengkapnya, lihat [Menggunakan nilai atribut ekspresi di DynamoDB](Expressions.ExpressionAttributeValues.md). **Example** Modifikasi berbagai atribut dalam item `Thread`. Parameter `ReturnValues` opsional menunjukkan item seperti yang muncul setelah pembaruan. Untuk informasi selengkapnya, lihat [Nilai yang dikembalikan](#WorkingWithItems.ReturnValues). ``` aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW ``` Argumen untuk `--key` disimpan dalam file `key.json`. ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} } ``` Argumen untuk `--expression-attribute-values` disimpan dalam file `expression-attribute-values.json`. ``` { ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} } ``` ### DeleteItem `DeleteItem` menghapus item dengan kunci tertentu. **Example** AWS CLI Contoh berikut menunjukkan cara menghapus `Thread` item. ``` aws dynamodb delete-item \ --table-name Thread \ --key file://key.json ``` ## Nilai yang dikembalikan Dalam beberapa kasus, Anda mungkin ingin DynamoDB mengembalikan nilai-nilai atribut tertentu seperti nilai yang muncul sebelum atau setelah Anda memodifikasi mereka. Operasi `PutItem`, `UpdateItem`, dan `DeleteItem` memiliki parameter `ReturnValues` yang dapat Anda gunakan untuk mengembalikan nilai atribut sebelum atau setelah dimodifikasi. Nilai default untuk `ReturnValues` adalah `NONE`, yang berarti DynamoDB tidak mengembalikan informasi apa pun tentang atribut yang dimodifikasi. Berikut ini adalah pengaturan valid lainnya untuk `ReturnValues`, yang diatur oleh operasi DynamoDB API. ### PutItem + `ReturnValues`: `ALL_OLD` + Jika Anda menimpa item yang ada, `ALL_OLD` akan mengembalikan seluruh item seperti item yang muncul sebelum penimpaan. + Jika Anda menulis item yang tidak ada, `ALL_OLD` tidak akan berpengaruh. ### UpdateItem Penggunaan yang paling umum untuk `UpdateItem` adalah untuk memperbarui item yang ada. Namun, `UpdateItem` benar-benar melakukan *upsert*, yang berarti bahwa ini secara otomatis membuat item jika sudah tidak ada. + `ReturnValues`: `ALL_OLD` + Jika Anda memperbarui item yang ada, `ALL_OLD` akan mengembalikan seluruh item seperti item yang muncul sebelum pembaruan. + Jika Anda memperbarui item yang tidak ada (upsert), `ALL_OLD` tidak akan berpengaruh. + `ReturnValues`: `ALL_NEW` + Jika Anda memperbarui item yang ada, `ALL_NEW` menampilkan seluruh item seperti item yang muncul setelah pembaruan. + Jika Anda memperbarui item tidak ada (upsert), `ALL_NEW` akan mengembalikan seluruh item. + `ReturnValues`: `UPDATED_OLD` + Jika Anda memperbarui item yang ada, `UPDATED_OLD` hanya mengembalikan atribut yang diperbarui seperti atribut yang muncul sebelum pembaruan. + Jika Anda memperbarui item yang tidak ada (upsert), `UPDATED_OLD` tidak akan berpengaruh. + `ReturnValues`: `UPDATED_NEW` + Jika Anda memperbarui item yang ada, `UPDATED_NEW` hanya menampilkan atribut yang terpengaruh, seperti yang muncul setelah pembaruan. + Jika Anda memperbarui item tidak ada (upsert), `UPDATED_NEW` hanya mengembalikan atribut diperbarui, seperti yang muncul setelah pembaruan. ### DeleteItem + `ReturnValues`: `ALL_OLD` + Jika Anda menghapus item yang ada, `ALL_OLD` akan mengembalikan seluruh item seperti yang muncul sebelum Anda menghapusnya. + Jika Anda menghapus item yang tidak ada, `ALL_OLD` tidak akan menampilkan data apa pun. ## Operasi batch Untuk aplikasi yang memerlukan membaca atau menulis beberapa item, DynamoDB menyediakan operasi `BatchGetItem` dan `BatchWriteItem`. Dengan menggunakan operasi ini, Anda dapat mengurangi jumlah perjalanan bolak-balik jaringan dari aplikasi Anda ke DynamoDB. Selain itu, DynamoDB melakukan operasi baca atau tulis individu secara paralel. Aplikasi Anda mendapatkan keuntungan dari paralelisme ini tanpa perlu mengelola konkurensi atau threading. Operasi batch pada dasarnya merupakan pembungkus di sekitar beberapa permintaan baca atau tulis. Misalnya, jika permintaan `BatchGetItem` berisi lima item, DynamoDB melakukan lima operasi `GetItem` atas nama Anda. Demikian pula, jika permintaan `BatchWriteItem` berisi dua permintaan put dan empat permintaan penghapusan, DynamoDB akan melakukan dua permintaan `PutItem` dan empat `DeleteItem`. Secara umum, operasi batch tidak gagal kecuali *semua* permintaan dalam batch mengalami kegagalan. Misalnya, bayangkan Anda melakukan operasi `BatchGetItem`, tetapi salah satu permintaan `GetItem` individu dalam batch mengalami kegagalan. Dalam kasus ini, `BatchGetItem` mengembalikan kunci dan data dari permintaan `GetItem` yang gagal. Permintaan `GetItem` lainnya dalam batch tidak akan terpengaruh. ### BatchGetItem Satu operasi `BatchGetItem` dapat berisi hingga 100 permintaan `GetItem` individu dapat mengambil data hingga 16 MB. Selain itu, operasi `BatchGetItem` dapat mengambil item dari beberapa tabel. **Example** Ambil dua item dari tabel `Thread`, menggunakan ekspresi proyeksi untuk mengembalikan beberapa atribut saja. ``` aws dynamodb batch-get-item \ --request-items file://request-items.json ``` Argumen untuk `--request-items` disimpan dalam file `request-items.json`. ``` { "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } } ``` ### BatchWriteItem Operasi `BatchWriteItem` dapat berisi hingga 25 permintaan `PutItem` dan `DeleteItem` individu, serta dapat menulis data hingga 16 MB. (Ukuran maksimum item individu adalah sebesar 400 KB.) Selain itu, operasi `BatchWriteItem` dapat menempatkan atau menghapus item dalam beberapa tabel. **catatan** `BatchWriteItem` tidak mendukung permintaan `UpdateItem`. **Example** Tulis dua item ke tabel `ProductCatalog`. ``` aws dynamodb batch-write-item \ --request-items file://request-items.json ``` Argumen untuk `--request-items` disimpan dalam file `request-items.json`. ``` { "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] } ``` ## Penghitung atom Anda dapat menggunakan operasi `UpdateItem` untuk mengimplementasikan *penghitung atom*—atribut numerik yang bertambah, tanpa syarat, tanpa mengganggu permintaan tulis lainnya. (Semua permintaan tulis diterapkan sesuai urutan penerimaannya.) Dengan penghitung atom, pembaruan tidak idempotent. Dengan kata lain, nilai numerik bertambah atau berkurang setiap kali Anda menelepon. `UpdateItem` Jika nilai kenaikan yang digunakan untuk memperbarui penghitung atom positif, maka itu dapat menyebabkan penghitungan berlebihan. Jika nilai kenaikan negatif, maka dapat menyebabkan kekurangan perhitungan. Anda dapat menggunakan penghitung atom untuk melacak jumlah pengunjung ke situs web. Dalam hal ini, aplikasi Anda akan menaikkan nilai numerik, terlepas dari nilai saat ini. Jika operasi `UpdateItem` gagal, aplikasi hanya dapat mencoba ulang operasi. Tindakan ini akan berisiko memperbarui penghitung dua kali, tetapi Anda mungkin bisa menoleransi sedikit kelebihan penghitungan atau kekurangan penghitungan dari pengunjung situs web. Penghitung atom tidak akan cocok ketika kelebihan penghitungan atau kekurangan penghitungan tidak dapat ditoleransi (misalnya, dalam aplikasi perbankan). Dalam kasus ini, lebih aman menggunakan pembaruan bersyarat, bukannya penghitung atom. Untuk informasi selengkapnya, lihat [Menambahkan dan mengurangi atribut numerik](Expressions.UpdateExpressions.md#Expressions.UpdateExpressions.SET.IncrementAndDecrement). **Example** AWS CLI Contoh berikut menambah produk `Price` sebesar 5. Untuk contoh ini, item diketahui ada sebelum penghitung diperbarui. Karena `UpdateItem` tidak idempotent, `Price` meningkat setiap kali Anda menjalankan kode ini. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW ``` ## Penulisan bersyarat *Secara default, operasi penulisan DynamoDB `PutItem` (`DeleteItem`,) tidak bersyarat: Setiap operasi menimpa item yang ada yang memiliki kunci primer yang ditentukan.* DynamoDB secara opsional mendukung penulisan bersyarat untuk operasi ini. Penulisan bersyarat akan berhasil hanya jika atribut item memenuhi satu atau beberapa kondisi yang diharapkan. Jika tidak, operasi ini akan mengembalikan kesalahan. Penulisan bersyarat memeriksa kondisinya terhadap versi item yang terbaru diperbarui. Perhatikan bahwa jika item sebelumnya tidak ada atau jika operasi sukses terbaru terhadap item tersebut adalah penghapusan, maka penulisan bersyarat tidak akan menemukan item sebelumnya. Penulisan bersyarat sangat membantu dalam banyak situasi. Misalnya, Anda mungkin ingin operasi `PutItem` bisa berhasil hanya jika sudah tidak ada item dengan kunci primer yang sama. Atau Anda dapat mencegah operasi `UpdateItem` memodifikasi item jika salah satu atributnya memiliki nilai tertentu. Penulisan bersyarat berguna jika beberapa pengguna mencoba mengubah item yang sama. Perhatikan diagram berikut, di mana dua pengguna (Alice dan Bob) bekerja dengan item yang sama dari tabel DynamoDB. ![Pengguna Alice dan Bob mencoba memodifikasi item dengan Id 1, menunjukkan perlunya penulisan bersyarat.](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/update-no-condition.png) Misalkan Alice menggunakan AWS CLI untuk memperbarui `Price` atribut ke 8. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json ``` Argumen untuk `--expression-attribute-values` disimpan dalam file `expression-attribute-values.json`: ``` { ":newval":{"N":"8"} } ``` Sekarang anggaplah Bob mengeluarkan permintaan `UpdateItem` yang serupa kemudian, tetapi mengubah `Price` menjadi 12. Untuk Bob, parameter `--expression-attribute-values` akan terlihat seperti berikut ini. ``` { ":newval":{"N":"12"} } ``` Permintaan Bob berhasil, tetapi pembaruan Alice sebelumnya hilang. Untuk meminta `PutItem`, `DeleteItem`, atau `UpdateItem` bersyarat, Andalah yang menentukan ekspresi kondisi. *Ekspresi kondisi* adalah string yang berisi nama atribut, operator bersyarat, dan fungsi bawaan. Seluruh ekspresi harus bernilai benar. Jika tidak, operasi gagal. Sekarang pertimbangkan diagram berikut yang menunjukkan bagaimana penulisan bersyarat akan mencegah pembaruan Alice ditimpa. ![Penulisan bersyarat mencegah pembaruan pengguna Bob menimpa perubahan pengguna Alice ke item yang sama.](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/update-yes-condition.png) Alice mencoba pertama kali untuk memperbarui `Price` menjadi 8, tetapi hanya jika `Price` saat ini adalah 10. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json ``` Argumen untuk `--expression-attribute-values` disimpan dalam file `expression-attribute-values.json`. ``` { ":newval":{"N":"8"}, ":currval":{"N":"10"} } ``` Pembaruan Alice berhasil karena kondisi bernilai benar. Berikutnya, Bob mencoba memperbarui `Price` menjadi 12, tetapi hanya jika `Price` saat ini adalah 10. Untuk Bob, parameter `--expression-attribute-values` akan terlihat seperti berikut ini. ``` { ":newval":{"N":"12"}, ":currval":{"N":"10"} } ``` Karena Alice sebelumnya telah mengubah `Price` ke 8, ekspresi kondisi bernilai SALAH, dan pembaruan Bob mengalami kegagalan. Untuk informasi selengkapnya, lihat [Contoh CLI ekspresi kondisi DynamoDB](Expressions.ConditionExpressions.md). ### Idempotensi penulisan bersyarat Penulisan bersyarat dapat menjadi *idempotent* jika pemeriksaan bersyarat berada pada atribut yang sama dan sedang diperbarui. Ini berarti bahwa DynamoDB melakukan permintaan tulis yang diberikan hanya jika nilai atribut tertentu dalam item cocok dengan tempat mereka berada pada saat permintaan sesuai harapan Anda. Misalnya, misalnya Anda mengeluarkan permintaan `UpdateItem` untuk meningkatkan `Price` dari item sebesar 3, tetapi hanya jika `Price` saat ini adalah 20. Setelah Anda mengirimkan permintaan, tetapi sebelum Anda mendapatkan hasil kembali, terjadi kesalahan jaringan, dan Anda tidak tahu apakah permintaan tersebut berhasil. Karena penulisan bersyarat ini idempotent, Anda dapat mencoba kembali permintaan `UpdateItem` yang sama, dan DynamoDB memperbarui item hanya jika `Price` saat ini adalah 20. ### Unit kapasitas yang digunakan oleh penulisan bersyarat Jika `ConditionExpression` bernilai false selama penulisan bersyarat, DynamoDB masih menggunakan kapasitas tulis dari tabel. Jumlah yang dikonsumsi tergantung dari besar kecilnya barang yang ada (atau minimal 1). Misalnya, jika item yang ada berukuran 300kb dan item baru yang Anda coba buat atau perbarui berukuran 310kb, unit kapasitas tulis yang digunakan akan menjadi 300 jika kondisi gagal, dan 310 jika kondisi berhasil. Jika ini adalah item baru (belum ada item yang ada), maka unit kapasitas tulis yang digunakan adalah 1 jika kondisi gagal dan 310 jika kondisi berhasil. **catatan** Operasi tulis hanya mengonsumsi unit kapasitas *tulis*. Operasi tersebut tidak pernah mengonsumsi unit kapasitas *baca*. Penulisan bersyarat yang gagal akan menampilkan `ConditionalCheckFailedException`. Ketika ini terjadi, Anda tidak menerima informasi apa pun dalam tanggapan tentang kapasitas tulis yang dikonsumsi. Untuk mengembalikan jumlah unit kapasitas tulis yang dikonsumsi selama penulisan bersyarat, Anda menggunakan parameter `ReturnConsumedCapacity`: + `TOTAL` — Mengembalikan jumlah total unit kapasitas tulis yang dikonsumsi. + `INDEXES` — Mengembalikan jumlah total unit kapasitas tulis yang digunakan, dengan subtotal untuk tabel dan indeks sekunder apa pun yang terpengaruh oleh operasi. + `NONE` — Tidak ada detail kapasitas tulis dikembalikan. (Ini menjadi opsi default.) **catatan** Tidak seperti indeks sekunder global, indeks sekunder lokal berbagi kapasitas throughput yang disediakan dengan tabelnya. Aktivitas baca dan tulis pada indeks sekunder lokal mengonsumsi kapasitas throughput yang disediakan dari tabel.