PutItem - Amazon DynamoDB
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

PutItem

重要

本节介绍已经弃用的 API 版本 2011-12-05,不应用于新应用程序。

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

描述

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

属性值不能为空;字符串和二进制类型属性的长度必须大于零;设置类型属性不能为空。具有空值的请求将被拒绝,并显示 ValidationException

注意

要确保新项目不会替换现有项目,请使用 Exists 设置为 false(对于主键属性)的条件放入操作。

有关使用 PutItem 的更多信息,请参见 使用项目和属性

请求

语法

// 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,则不会返回任何内容。

类型:字符串

响应

语法

下面的语法示例假定请求指定 ALL_OLDReturnValues 参数;否则,响应只有 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

放入操作之前的属性值,仅当 ReturnValues 参数指定为请求的 ALL_OLD

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

ConsumedCapacityUnits

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

类型:数字

特殊错误

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

示例

有关使用 Amazon SDK 的示例,请参阅 使用项目和属性

示例请求

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