本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
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:AttributeName
|
条件放置的属性的名称。 类型: 字符串 |
否 |
Expected:AttributeName: ExpectedAttributeValue |
使用此参数可指定属性名称/值对是否已存在值。
如果该项目的“Color”属性不存在,则以下 JSON 表示法将替换该项目:
以下 JSON 表示法检查名为“Color”的属性在替换项目之前是否具有“Yellow”的现有值:
默认情况下,如果您使用
如果您指定 |
否 |
ReturnValues
|
如果要获取属性名称/值对,并且在使用 类型: 字符串 |
否 |
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 操作之前的属性值,但前提是在请求中将 类型: 属性名称/值对的映射。 |
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 }