# UpdateItem
<a name="API_UpdateItem_v20111205"></a>

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

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

编辑现有项目的属性。您可以执行条件更新（如果不存在，则插入新的属性名称-值对；如果现有名称-值对具有某些预期属性值，则替换它）。

**注意**  
无法使用 UpdateItem 更新主键属性。而应删除项目，使用 PutItem 创建具有新属性的新项目。

UpdateItem 操作包括 `Action` 参数，定义如何执行更新。您可以放入、删除或添加属性值。

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

如果现有项目具有指定的主键：
+ **PUT—** 添加指定的属性。如果属性存在，则将替换为新值。
+ **DDELETE —** 如果未指定值，则删除属性及其值。如果指定了一组值，则将从旧集中删除指定集中的值。因此，如果属性值包含 [a,b,c] 并且删除操作包含 [a,c]，则最终属性值为 [b]。指定值的类型必须与现有值类型匹配。指定空集无效。
+ **ADD —** 仅对数字或者目标属性是集合（包括字符串集）时，使用 add 操作。如果目标属性是单个字符串值或标量二进制值，ADD 将不起作用。指定的值将添加到数值中（递增或递减现有数值），或作为字符串集中的附加值添加。如果指定一组值，则这些值将添加到现有集合。例如，如果原始集合是 [1,2]，提供的值为 [3]，则在 add 操作后，集合为 [1,2,3]，而不是 [4,5]。如果为集合属性指定 Add 操作，并且指定的属性类型与现有集合类型不匹配，则会出错。

  如果对不存在的属性使用 ADD，则将该属性及其值添加到项目。

如果没有项目匹配指定的主键：
+ **PUT—** 使用指定主键创建新项目。然后添加指定属性。
+ **DELETE—** 什么都不会发生。
+ **ADD—** 为属性值创建一个具有提供的主键和数字（或一组数字）的项目。对字符串或二进制类型无效。

**注意**  
如果使用 `ADD` 为更新前不存在的项目递增或递减数值，则 DynamoDB 使用 `0` 作为初始值。如果使用 `ADD` 为更新前不存在的属性递增或递减数值（但项目存在），则 DynamoDB 使用 `0` 作为初始值。例如，可以使用 `ADD` 将 `+3` 添加到更新之前不存在的属性。DynamoDB 对初始值使用 `0`，更新后的值为 `3`。

有关使用此操作的更多信息，请参阅 [使用 DynamoDB 中的项目和属性](WorkingWithItems.md)。

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

### 语法
<a name="API_UpdateItem_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.UpdateItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},
        "RangeKeyElement":{"N":"AttributeValue2"}},
    "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
    "ReturnValues":"ReturnValuesConstant"
}
```


****  

|  名称  |  描述  |  必填 | 
| --- | --- | --- | 
|  TableName  |  包含要更新项目的表的名称。 类型：字符串  |  是  | 
|  Key  | 定义项目的主键。有关主键的更多信息，请参阅 [主键](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。类型：`HashKeyElement` 到其值以及 `RangeKeyElement` 到其值的映射。 | 是 | 
| AttributeUpdates | 属性名称到新值和更新操作的映射。属性名称指定要修改的属性，不能包含任何主键属性。类型：属性名称、值和属性更新操作的映射。 |  | 
| AttributeUpdates:Action | 指定如何执行更新。可能的值：`PUT`（默认）、`ADD` 或 `DELETE`。UpdateItem 说明中解释语义类型：字符串默认：`PUT` | 否 | 
| 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  | 如果要在用 `UpdateItem` 更新属性名称-值对之前获取属性名称-值对，请使用此参数。可能的参数值包括 `NONE`（默认）或 `ALL_OLD`、`UPDATED_OLD`、`ALL_NEW` 或 `UPDATED_NEW`。如果指定 `ALL_OLD`，并且 `UpdateItem` 覆盖属性名称-值对，则返回旧项目的内容。如果未提供此参数或者为 `NONE`，则不会返回任何内容。如果指定 `ALL_NEW`，则返回项目新版本的所有属性。如果指定 `UPDATED_NEW`，则仅返回更新属性的新版本。类型：字符串 | 否 | 

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

### 语法
<a name="API_UpdateItem_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: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}
```


****  

|  名称  |  描述  | 
| --- | --- | 
|  Attributes  | 属性名称-值对的映射，但仅当 `ReturnValues` 参数在请求中指定为 `NONE` 以外的内容。类型：属性名称-值对映射。 | 
| ConsumedCapacityUnits | 操作消耗的写入容量单位数。此值显示应用于预置吞吐量的数字。有关更多信息，请参阅[DynamoDB 预置容量模式](provisioned-capacity-mode.md)。 类型：数字 | 

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


****  

|  错误  |  描述  | 
| --- | --- | 
|  ConditionalCheckFailedException  | 条件检查失败。属性（“\$1 名称 \$1”）值是（“\$1 值 \$1”），但是预期值（“\$1 expValue \$1”）  | 
| ResourceNotFoundExceptions  | 找不到指定项目或属性。 | 

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

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

### 示例请求
<a name="API_UpdateItem_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.UpdateItem
content-type: application/x-amz-json-1.0 

{"TableName":"comp5",
    "Key":
        {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
    "AttributeUpdates":
        {"status":{"Value":{"S":"online"},
        "Action":"PUT"}},
    "Expected":{"status":{"Value":{"S":"offline"}}},
    "ReturnValues":"ALL_NEW"
}
```

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

```
HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT

{"Attributes":
    {"friends":{"SS":["Lynda, Aaron"]},
    "status":{"S":"online"},
    "time":{"N":"1307654350"},
    "user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}
```

## 相关操作
<a name="API_UpdateItem_Related_Actions"></a>
+  [PutItem](API_PutItem_v20111205.md) 
+  [DeleteItem](API_DeleteItem_v20111205.md)