本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
重要
This section refers to API version 2011-12-05,
which is deprecated and should not be used for new
applications.
如需目前低階 的文件API，請參閱 Amazon DynamoDB API參考。
描述
建立新項目，或以新項目取代舊項目 (包括全部屬性)。如果具有相同主索引鍵的指定資料表中已存在某項目，則新項目會完全取代現有項目。您可以執行條件式放置 (如果具有所指定主索引鍵的項目不存在，則插入新項目)，或者在現有項目具有某些屬性值時取代項目。
屬性值不得為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 ValidationException。
注意
若要確保新項目不會取代現有項目，請使用條件式放置操作，針對主索引鍵屬性或屬性將 Exists 設定為 false。
如需有關使用 PutItem 的詳細資訊，請參閱 在 DynamoDB 中使用項目和屬性。
請求
語法
// This header is abbreviated. // For a sample of a complete header, see DynamoDB 低階 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.PutItem content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Item":{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"N":"AttributeValue2"}, "AttributeName5":{"B":"dmFsdWU="} }, "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}}, "ReturnValues":"ReturnValuesConstant"}
| 名稱 | 描述 | 必要 |
|---|---|---|
TableName
|
要包含項目的資料表名稱。 類型：字串 |
是 |
Item
|
項目屬性映射，且必須包含定義項目的主索引鍵值。可提供其他屬性名稱值組給項目。如需主索引鍵的詳細資訊，請參閱 主索引鍵。 類型：屬性值的屬性名稱映射。 |
是 |
Expected
|
指定條件式放置的屬性。 類型：屬性值的屬性名稱映射，以及映射是否存在。 |
否 |
Expected:AttributeName
|
條件式放置的屬性的名稱。 類型：字串 |
否 |
Expected:AttributeName: ExpectedAttributeValue |
使用此參數來指定屬性名稱值組的值是否已經存在。 如果該項目的「顏色」屬性尚未存在，則下列JSON表示法會取代該項目： 下列JSON表示法會檢查名為 "Color" 的屬性是否具有 "Yellow" 的現有值，然後再取代項目： 根據預設，如果使用 注意如果指定 |
否 |
ReturnValues
|
如果想在以 類型：字串 |
否 |
回應
語法
下列語法範例假設請求指定 ALL_OLD 的 ReturnValues 參數，反之則回應只有 ConsumedCapacityUnits 元素。
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 85
{"Attributes":
{"AttributeName3":{"S":"AttributeValue3"},
"AttributeName2":{"SS":"AttributeValue2"},
"AttributeName1":{"SS":"AttributeValue1"},
},
"ConsumedCapacityUnits":1
}| 名稱 | 描述 |
|---|---|
Attributes
|
執行放置操作之前的屬性值，但僅限於請求中指定 類型：屬性名稱值組映射。 |
ConsumedCapacityUnits |
操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。如需詳細資訊，請參閱 DynamoDB 佈建容量模式。 類型：數字 |
特殊錯誤
| 錯誤 | 描述 |
|---|---|
ConditionalCheckFailedException
|
條件式檢查失敗。找不到預期的屬性值。 |
ResourceNotFoundException
|
找不到指定的項目或屬性。 |
範例
如需使用 的範例 AWS SDK，請參閱 在 DynamoDB 中使用項目和屬性。
請求範例
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.PutItem content-type: application/x-amz-json-1.0 {"TableName":"comp5", "Item": {"time":{"N":"300"}, "feeling":{"S":"not surprised"}, "user":{"S":"Riley"} }, "Expected": {"feeling":{"Value":{"S":"surprised"},"Exists":true}} "ReturnValues":"ALL_OLD" }
回應範例
HTTP/1.1 200
x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 84
{"Attributes":
{"feeling":{"S":"surprised"},
"time":{"N":"300"},
"user":{"S":"Riley"}},
"ConsumedCapacityUnits":1
}相關動作
