Node.js（AWS SDK v3）中的 DynamoDB GetItem

AWS SDK v3 提供兩種讀取單一項目的方式：DynamoDBClient 上的 GetItemCommand，它說的是傳輸格式（{S: '...'}）；或 DynamoDBDocumentClient 上的 GetCommand，它收發的是純 JavaScript。

這個範例用的是低階 client。那些包裝正是屬性值編碼在線路上的真實樣貌，也是錯誤訊息回頭引用給你看的東西。無論走哪一條路，請求都需要完整的主索引鍵。

程式碼

import {DynamoDBClient, GetItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const command = new GetItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  ProjectionExpression: '#proj0, #proj1, #proj2, #proj3',
  ExpressionAttributeNames: {
    '#proj0': 'Artist',
    '#proj1': 'SongTitle',
    '#proj2': 'AlbumTitle',
    '#proj3': 'Year'
  }
});

const response = await client.send(command);

if (!response.Item) {
  console.log('Item not found');
} else {
  console.log(response.Item);
}

說明

是 send(command)，不是 client.getItem() — DynamoDBClient 只公開 send。如果你想要 SDK v2 風格的呼叫，同一個套件裡的彙總 DynamoDB 類別確實帶有 getItem 方法，代價是把每一個 command 都拉進你的 bundle。
沒命中是 undefined，不是錯誤 — response.Item 就只是不存在，而呼叫仍然正常完成。response.$metadata 永遠都在，所以對回應本身做真值判斷等於什麼都沒告訴你。
unmarshall 依數值大小挑型別 — 落在安全整數範圍內的 {N: …} 會以 number 回來，超出範圍的以 BigInt 回來，而很大的非整數會丟出 can't be converted to BigInt。從 @aws-sdk/util-dynamodb 呼叫 unmarshall 時傳入 {wrapNumbers: true}，每一個數字就會改以 NumberValue 抵達，轉換由你決定。
那些 #proj 別名是有承重作用的 — Year 在 AWS 的保留字清單上，所以直接寫出它的 ProjectionExpression 會被回絕。像上面那樣把每一個名稱都別名化，是安全的預設做法。它修剪的是回應，不是讀取成本（原因）。
ConsumedCapacity 要主動開啟 — 加上 ReturnConsumedCapacity: 'TOTAL'，回應就會回報這次讀取實際的花費：讀取一個 4 KB 以下的項目，最終一致讀取是 0.5 個容量單位，一旦加上 ConsistentRead: true 就是 1.0（這個取捨）。
把 client 提到外層 — 在模組層級只建構一次 DynamoDBClient。每個請求建一個，或在 Lambda handler 裡面建，等於每次呼叫都丟掉連線池與已解析的憑證。

改用視覺化操作

DynoTable 把項目顯示成一般的資料列，而不是屬性值對應表，並且能把網格背後的查詢匯出成一支可執行的 SDK v3 程式。下載 DynoTable。

參考資料

最後驗證於 2026-07-28，對照上方連結的 AWS 官方文件。

Node.js（AWS SDK v3）中的 DynamoDB GetItem

程式碼

說明

改用視覺化操作

相關指南

參考資料