# PutItem
<a name="API_PutItem_v20111205"></a>

**重要**  
***本节介绍已经弃用的 API 版本 2011-12-05，不应用于新应用程序。***  
 **有关当前低级别 API 的文档，请参阅 [Amazon DynamoDB API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**

## 描述
<a name="API_PutItem_Description"></a>

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

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

**注意**  
要确保新项目不会替换现有项目，请使用 `Exists` 设置为 `false`（对于主键属性）的条件放入操作。

有关使用 `PutItem` 的更多信息，请参见 [使用 DynamoDB 中的项目和属性](WorkingWithItems.md)。

## 请求
<a name="API_PutItem_RequestParameters"></a>

### 语法
<a name="API_PutItem_RequestParameters.syntax"></a>

```
// 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  | 项目属性的映射，必须包括定义项目的主键值。可以为项目提供其他属性名称-值对。有关主键的更多信息，请参阅 [主键](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。类型：属性名称到属性值的映射。 | 是 | 
| Expected  | 指定条件放入的属性。`Expected` 参数用于提供属性名称，以及 DynamoDB 是否应在更改前检查属性值是否已存在；或者属性值是否已存在并且具有特定值。类型：属性名称到属性值的映射，以及是否存在。 | 否 | 
| Expected:AttributeName  | 条件放入的属性的名称。类型：字符串 | 否 | 
| Expected:AttributeName: ExpectedAttributeValue | 使用此参数指定属性名称-值对是否已经存在值。如果项目不存在 "Color" 属性，则下面的 JSON 表示将替换该项目：<pre>"Expected" :<br />	{"Color":{"Exists":false}}</pre>下面的 JSON 表示在替换项目前，检查 "Color" 名称的属性是否已有 "Yellow" 值：<pre>"Expected" : <br />	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}</pre>默认情况下，如果使用 `Expected` 参数并提供 `Value`，则 DynamoDB 假定属性存在，并且需要替换当前值。这样不必指定 `{"Exists":true}`，因为是暗含的。可以将请求缩短为：<pre>"Expected" : <br />	{"Color":{"Value":{"S":"Yellow"}}}</pre> 如果指定的 `{"Exists":true}` 没有要检查的属性值，DynamoDB 将返回错误。  | 否 | 
| ReturnValues  | 如果要在用 `PutItem` 更新属性名称-值对之前获取属性名称-值对，请使用此参数。可能的参数值包括 `NONE`（默认值）或 `ALL_OLD`。如果指定 `ALL_OLD`，并且 `PutItem` 覆盖属性名称-值对，则返回旧项目的内容。如果未提供此参数或者为 `NONE`，则不会返回任何内容。类型：字符串 | 否 | 

## 响应
<a name="API_PutItem_CommonResponseElements"></a>

### 语法
<a name="API_PutItem_CommonResponseElements.syntax"></a>

下面的语法示例假定请求指定 `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 预置容量模式](provisioned-capacity-mode.md)。 类型：数字 | 

## 特殊错误
<a name="API_PutItem_SpecialErrors"></a>


****  

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

## 示例
<a name="API_PutItem_Examples"></a>

有关使用 AWS SDK 的示例，请参阅 [使用 DynamoDB 中的项目和属性](WorkingWithItems.md)。

### 示例请求
<a name="API_PutItem_Examples_Request"></a>

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

### 示例响应
<a name="API_PutItem_Examples_Response"></a>

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

## 相关操作
<a name="API_PutItem_Related_Actions"></a>
+  [UpdateItem](API_UpdateItem_v20111205.md) 
+  [DeleteItem](API_DeleteItem_v20111205.md) 
+  [GetItem](API_GetItem_v20111205.md) 
+  [BatchGetItem](API_BatchGetItem_v20111205.md)