# AttributeUpdates（遗留）
<a name="LegacyConditionalParameters.AttributeUpdates"></a>

**注意**  
我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *UpdateExpression*。](#UpdateExpression.instead)。

在 `UpdateItem` 操作中，遗留条件参数 `AttributeUpdates` 包含要修改的属性的名称、要对每个属性执行的操作，以及每个属性的新值。如果要更新的属性是该表上任何索引的索引键属性，则属性类型必须与 `AttributesDefinition` 表说明中定义的索引键类型匹配。可以使用 `UpdateItem` 更新任何非键属性。

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

每个 `AttributeUpdates` 元素包含要修改的属性名称以及以下内容：
+  `Value` - 此属性的新值（如果适用）。
+  `Action` - 指定如何执行更新的值。此操作仅对数据类型为 Number 或集合的现有属性有效；不要将 `ADD` 用于其他数据类型。

  如果在表中找到具有指定主键的项目，则以下值执行以下操作：
  +  `PUT` - 将指定的属性添加到项目。如果属性已存在，则将替换为新值。
  +  `DELETE` - 如果没有为 指定值，则删除属性及其值。`DELETE`指定值的数据类型必须匹配现有值的数据类型。

    如果指定了一组值，则将从旧集中减去这些值。例如，如果属性值是集合 `[a,b,c]`，`DELETE` 操作指定 `[a,c]`，则最终属性值为`[b]`。指定空集是错误。
  +  `ADD` - 如果属性尚不存在，则将指定值添加到项目。如果属性已存在，则 `ADD` 的行为取决于属性的数据类型：
    + 如果现有属性是数字，并且 `Value` 也是数字，则将 `Value` 与现有属性数学相加。如果 `Value` 为负数，则从现有属性减去该值。
**注意**  
如果使用 `ADD` 为更新前不存在的项目递增或递减数值，则 DynamoDB 使用 0 作为初始值。  
同样，如果使用 `ADD` 为现有项目递增或递减更新前不存在的属性值，则 DynamoDB 使用 `0` 作为初始值。例如，假设要更新的项目没有名为 *itemcount* 的属性，仍决定将数字 `3` `ADD`到该属性。DynamoDB 将创建 *itemcount* 属性，将初始值设置为 `0`，最后加上 `3`。结果将是一个新的 *itemcount* 属性，值为 `3`。
    + 如果现有数据类型为集合，并且 `Value` 也是集合，则将 `Value` 附加到现有集合。例如，如果属性值是集合 `[1,2]`，`ADD` 操作指定 `[3]`，则最终属性值为 `[1,2,3]`。如果为集合属性指定 `ADD` 操作，并且指定的属性类型与现有集类型不匹配，则出错。

      两个集合必须具有相同的基元数据类型。例如，如果现有数据类型是一组字符串，`Value` 也必须是一组字符串。

  如果在表中找不到具有指定键的项目，则以下值将执行以下操作：
  +  `PUT` - 使 DynamoDB 创建具有指定主键的新项目，然后添加属性。
  +  `DELETE` - 不进行任何操作，因为无法从不存在的项目删除属性。操作成功，但 DynamoDB 不创建新项目。
  +  `ADD` - 使 DynamoDB 创建具有提供的主键和属性值数字（或数字集合）的项目。唯一允许的数据类型是 Number 和 Number Set。

如果提供属于索引键的任何属性，则这些属性的数据类型必须与表属性定义中的架构数据类型匹配。

## 改用 *UpdateExpression* – 示例
<a name="UpdateExpression.instead"></a>

假设要修改 *Music* 表中的项目。可以使用 `UpdateItem` 请求和 `AttributeUpdates` 参数，如这个 AWS CLI 示例：

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "SongTitle": {"S":"Call Me Today"}, 
        "Artist": {"S":"No One You Know"}
    }' \
    --attribute-updates '{
        "Genre": {
            "Action": "PUT", 
            "Value": {"S":"Rock"}
        }   
    }'
```

您可以改用 `UpdateExpression`：

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "SongTitle": {"S":"Call Me Today"}, 
        "Artist": {"S":"No One You Know"}
    }' \
    --update-expression 'SET Genre = :g' \ 
    --expression-attribute-values '{
        ":g": {"S":"Rock"}
    }'
```