描述请求响应特殊错误示例相关操作

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_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`	放入操作之前的属性值，仅当 `ReturnValues` 参数指定为请求的 `ALL_OLD`。类型：属性名称-值对映射。
`ConsumedCapacityUnits`	操作消耗的写入容量单位数。此值显示应用于预置吞吐量的数字。有关更多信息，请参阅管理 DynamoDB 预调配容量表的吞吐量设置。类型：数字

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
}