Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

PutItem

重要

本节引用 API 版本 2011-12-05,此版本已被弃用且不应该用于新应用程序。

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

说明

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

属性值不能为 null;字符串和二进制类型属性的长度必须大于零;集合类型属性不能为空。将使用 ValidationException 拒绝包含空值的请求。

注意

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

有关使用 PutItem 的更多信息,请参阅在 DynamoDB 中处理项目

请求

语法

Copy
// 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 表示法将替换该项目:

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

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

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

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

Copy
"Expected" : {"Color":{"Value":{"S":"Yellow"}}}

注意

如果您指定 {"Exists":true} 时未指定要检查的属性值,则 DynamoDB 将返回错误。

ReturnValues

如果要在使用 PutItem 请求更新属性名称/值对之前获取属性名称/值对,请使用此参数。可能的参数值为 NONE(默认值)或 ALL_OLD。如果指定了 ALL_OLD 并且 PutItem 覆盖了属性名称/值对,则将返回旧项目的内容。如果未提供此参数或此参数为 NONE,则不返回任何内容。

类型:字符串

响应

语法

以下语法示例假设请求已将 ReturnValues 参数指定为 ALL_OLD;否则,响应将仅包含 ConsumedCapacityUnits 元素。

Copy
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

执行放置操作前的属性值,但仅当请求中已将 ReturnValues 参数指定为 ALL_OLD 时适用。

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

ConsumedCapacityUnits

操作占用的写入容量单位数。此值显示根据预配置吞吐量应用的数量。有关更多信息,请参阅 读取和写入的吞吐量设置

类型:数字

特殊错误

错误 说明
ConditionalCheckFailedException 条件检查失败。未找到所需的属性值。
ResourceNotFoundException 未找到指定的项目或属性。

示例

有关使用 AWS 开发工具包的示例,请参阅 在 DynamoDB 中处理项目

示例请求

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

示例响应

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