DynamoDB TransactWriteItems dengan AWS CLI

Seluruh transaksi masuk ke aws dynamodb transact-write-items sebagai satu array JSON --transact-items, jadi bagian menariknya adalah sisi-sisi tajam CLI-nya: di mana quoting patah, apa arti kode keluarnya, dan fakta bahwa keluaran error default membuang field yang Anda butuhkan untuk men-debug sebuah pembatalan. Apa yang Anda dapat dari sebuah transaksi sama di setiap SDK.

Kode

aws dynamodb transact-write-items \
  --transact-items '[
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        "UpdateExpression": "SET #upd0 = #upd0 - :one",
        "ConditionExpression": "#upd0 >= :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}}
      }
    },
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        "UpdateExpression": "SET #upd0 = if_not_exists(#upd0, :zero) + :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}, ":zero": {"N": "0"}}
      }
    }
  ]'

Transaksi yang berhasil di-commit mencetak tidak apa-apa dan keluar dengan 0. Tidak ada body respons untuk diperiksa, jadi di dalam skrip kode keluar itulah hasilnya.

Penjelasan

--transact-items — hingga 100 aksi Put / Update / Delete / ConditionCheck, total 4 MB, nilai dalam DynamoDB JSON. Aksi bisa merentang beberapa tabel di akun dan Region yang sama, dan tidak boleh ada dua di antaranya yang menyasar item yang sama.
Tiga kode keluar, tiga kegagalan berbeda. 0 berhasil di-commit. 252 berarti validasi parameter milik CLI sendiri menolak permintaannya dan tidak ada apa pun yang dikirim. 254 berarti DynamoDB menjawab dan menolak. Perbedaan itu layak dijadikan percabangan: 252 adalah bug di JSON Anda, 254 bisa jadi kondisi yang memang Anda harapkan gagal.

Format error default membuang alasan per-aksinya. aws-cli v2 mencetak ringkasannya lalu memberi tahu Anda bahwa ia menahan detailnya:

aws: [ERROR]: An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

Jalankan ulang perintah yang sama dengan --cli-error-format json dan strukturnya datang utuh, satu entri per aksi, dalam urutan --transact-items:

{
    "Message": "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]",
    "Code": "TransactionCanceledException",
    "CancellationReasons": [
        {
            "Code": "ConditionalCheckFailed",
            "Message": "The conditional request failed"
        },
        {
            "Code": "None"
        }
    ]
}

Di sini kondisi Awards >= 1 pada update pertama gagal; None menandai aksi kedua sebagai tak bersalah, dan perhatikan bahwa ia sama sekali tidak membawa field Message. Setiap kode lainnya diuraikan di halaman TransactionCanceledException.

Menyasar satu item dua kali bukanlah sebuah pembatalan. Itu gagal validasi sebelum apa pun dicoba, itulah sebabnya tidak ada alasan yang bisa dicetak:

aws: [ERROR]: An error occurred (ValidationException) when calling the TransactWriteItems operation: Transaction request cannot include multiple operations on one item

ConditionCheck — menegaskan sebuah kondisi pada item yang tidak diubah transaksi itu, dan memveto seluruh transaksi kalau kondisinya gagal.
--client-request-token — token tetap membuat penjalanan ulang bersifat idempoten selama 10 menit. Pakai ulang token yang sama dengan parameter apa pun yang berubah dan DynamoDB mengembalikan IdempotentParameterMismatch alih-alih diam-diam menerapkan payload baru.
Simpan array-nya dalam sebuah file. --transact-items file://transaction.json sepenuhnya menghindari quoting shell, dan file-nya bisa di-diff.

Lipat dua itu bisa diukur dari shell

Jalankan update satu-item yang sama dua kali, sekali di dalam transaksi dan sekali di luarnya, keduanya dengan --return-consumed-capacity TOTAL. DynamoDB Local melaporkan 2.0 unit kapasitas untuk penulisan transaksional dan 1.0 untuk yang biasa: tahap prepare dan tahap commit masing-masing menagih.

Itulah keseluruhan argumen menentang penggunaan transaksi sebagai default. Untuk atomisitas pada satu item Anda sudah punya alat yang lebih murah berupa penulisan bersyarat, yang menagih sekali. Untuk menghitung biaya beban kerja yang melakukan ini jutaan kali, kalkulator harga DynamoDB menerima jumlah penulisan yang sudah dilipatduakan itu secara langsung. Kalau merakit DynamoDB JSON di shell adalah bagian yang ingin Anda tinggalkan, DynoTable menyunting item terhadap tabel sungguhan dan menunjukkan expression yang dihasilkannya.

Contoh terkait

DynamoDB TransactWriteItems di Node.js — transaksi yang sama dengan AWS SDK v3.
DynamoDB TransactWriteItems di Python — transaksi yang sama dengan boto3.
DynamoDB BatchWriteItem dengan AWS CLI — penulisan massal saat Anda tidak butuh atomisitas.
Transaksi DynamoDB — isolasi, idempotensi, dan kapan transaksi sepadan.
DynamoDB TransactionCanceledException — setiap kode cancellation reason, diuraikan.
"Too many actions in a TransactWriteItems call" — batas 100 aksi dan 4 MB per transaksi.
"Transaction request cannot include multiple operations on one item" — satu aksi per item, per transaksi.

Referensi

Terakhir diverifikasi 2026-07-28 terhadap dokumentasi resmi AWS yang ditautkan di atas.