PutItem - Amazon DynamoDB
DescriptionRequestsResponses特殊错误Examples相关操作
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

PutItem

重要

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

有关当前低级别 API 的文档，请参阅 Amazon DynamoDB API Reference。

Description

创建新项目，或将旧项目替换为新项目（包括所有属性）。如果指定表中已存在具有相同主键的项目，则新项目将完全替换现有项目。您可以执行有条件放置（如果具有指定主键的项目不存在，则插入新项目），如果现有项目具有特定属性值，则替换现有项目。

属性值不得为 null；字符串和二进制类型属性的长度必须大于零；并且集类型属性不得为空。具有空值的请求将被拒绝，并显示 ValidationException。

注意

要确保新项目不会替换现有项目，请使用条件放置操作，并将主键属性或属性的 Exists 设置为 false。

有关使用 PutItem 的更多信息，请参阅使用项目和属性。

Requests

Syntax

// 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 参数，您可以提供属性名称，以及 DynamoDB 是否应检查该属性值是否已存在；或者该属性值是否存在并且在更改它之前具有特定值。

类型: 属性名称映射到属性值及其是否存在。

 否
Expected:AttributeName

条件放置的属性的名称。

类型: 字符串

 否
Expected:AttributeName: ExpectedAttributeValue 使用此参数可指定属性名称/值对是否已存在值。

如果该项目的“Color”属性不存在，则以下 JSON 表示法将替换该项目：

"Expected" :
	{"Color":{"Exists":false}}

以下 JSON 表示法检查名为“Color”的属性在替换项目之前是否具有“Yellow”的现有值：

"Expected" : 
	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}

默认情况下，如果您使用 Expected 参数并提供 Value，则 DynamoDB 假定该属性存在并具有要替换的当前值。因此，您不必指定 {"Exists":true}，因为它是隐含的。您可以将请求缩短到： 

"Expected" : 
	{"Color":{"Value":{"S":"Yellow"}}}
注意

如果您指定 {"Exists":true} 而没有要检查的属性值，则 DynamoDB 将返回错误。

否
ReturnValues

如果要获取属性名称/值对，并且在使用 PutItem 请求进行更新之前，请使用此参数。可能的参数值为 NONE（默认值）或 ALL_OLD。 如果指定了 ALL_OLD，并且 PutItem 重写了属性名称/值对，则返回旧项目的内容。如果未提供此参数或该参数为 NONE，则不返回任何内容。

类型: 字符串

 否

Responses

Syntax

以下语法示例假定请求指定了 ReturnValues 的 ALL_OLD 参数，否则，响应仅具有 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

put 操作之前的属性值，但前提是在请求中将 ReturnValues 参数指定为 ALL_OLD。

类型: 属性名称/值对的映射。
ConsumedCapacityUnits

操作占用的写入容量单位数。此值显示应用于预置吞吐量的数量。有关更多信息，请参阅 管理 DynamoDB 预置容量表的设置。

类型: 数字

特殊错误

错误 描述
ConditionalCheckFailedException 条件检查失败。找不到预期的属性值。
ResourceNotFoundException 找不到指定的项目或属性。

Examples

有关使用 AWS 开发工具包的示例，请参阅使用项目和属性。

示例请求

// 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
}