Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

UpdateItem

重要

本节引用 API 版本 2011-12-05,此版本已被弃用且不应该用于新应用程序。

有关当前低级 API 的文档,请参阅 Amazon DynamoDB API Reference

说明

编辑现有项目的属性。您可以执行有条件更新 (插入新的属性名称/值对 (如果它不存在),或者替换现有名称/值对 (如果它具有所需的特定属性值) )。

注意

不能使用 UpdateItem 更新主键属性。而是应删除该项目,然后使用 PutItem 创建带新属性的新项目。

UpdateItem 操作包含一个 Action 参数,该参数定义如何执行更新。您可以放置、删除或添加属性值。

属性值不能为 null;字符串和二进制类型属性的长度必须大于零;集合类型属性不能为空。将使用 ValidationException 拒绝包含空值的请求。

如果现有项目具有指定的主键:

  • PUT - 添加指定的属性。如果该属性存在,它将替换为新值。

  • DELETE - 如果未指定值,则此操作删除该属性及其值。如果指定了值的集合,则会从旧集合中删除指定集合中的值。因此,如果属性值包含 [a,b,c] 并且 Delete 操作包含 [a,c],则最终属性值为 [b]。指定值的类型必须与现有值类型匹配。指定空集是无效的。

  • ADD - 仅对数字使用 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 中处理项目

请求

语法

Copy
// 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

用于定义项目的主键。有关主键的更多信息,请参阅 主键

类型:HashKeyElement 到其值以及 RangeKeyElement 到其值的映射。

AttributeUpdates

属性名称到用于更新的新值和操作的映射。属性名称指定要修改的属性,但不能包含任何主键属性。

类型:用于属性更新的属性名称、值和操作的映射。

AttributeUpdates:Action

指定如何执行更新。可能的值:PUT (默认值) 、ADDDELETE。语义在 UpdateItem 说明中进行说明。

类型:字符串

默认值:PUT

Expected

指定有条件更新的属性。使用 Expected 参数可以提供属性名称,并指定 DynamoDB 是否应在更改属性值之前检查属性值是否已存在,或者属性值是否已存在且具有特定值。

类型:属性名称的映射。

Expected:AttributeName 有条件放置的属性名称。

类型:字符串

Expected:AttributeName: ExpectedAttributeValue 使用此参数可以指定属性名称/值对的值是否已存在。

如果该项目的“Color”属性尚未存在,则以下 JSON 表示法将更新该项目:

Copy
"Expected" : {"Color":{"Exists":false}}

以下 JSON 表示法在更新项目之前将检查名为“Color”的属性是否具有现有值“Yellow”:

Copy
"Expected" : {"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}

默认情况下,如果您使用 Expected 参数并提供 Value,则 DynamoDB 认为该属性存在并具有要替换的当前值。因此无需指定 {"Exists":true},因为它已被隐含。您可以将请求缩短为:

Copy
"Expected" : {"Color":{"Value":{"S":"Yellow"}}}

注意

如果您指定 {"Exists":true} 时未指定要检查的属性值,则 DynamoDB 将返回错误。

ReturnValues

如果要在使用 UpdateItem 请求更新属性名称/值对之前获取属性名称/值对,请使用此参数。可能的参数值为 NONE (默认值) 或 ALL_OLDUPDATED_OLDALL_NEWUPDATED_NEW。如果指定了 ALL_OLD 并且 UpdateItem 覆盖了属性名称/值对,则将返回旧项目的内容。如果未提供此参数或此参数为 NONE,则不返回任何内容。如果指定了 ALL_NEW,则将返回该项目的新版本的所有属性。如果指定了 UPDATED_NEW,则仅返回更新后的属性的新版本。

类型:字符串

响应

语法

以下语法示例假设请求已将 ReturnValues 参数指定为 ALL_OLD;否则,响应将仅包含 ConsumedCapacityUnits 元素。

Copy
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

操作占用的写入容量单位数。此值显示根据预置吞吐量应用的数量。有关更多信息,请参阅 读取和写入的吞吐量设置

类型:数字

特殊错误

错误 说明
ConditionalCheckFailedException 条件检查失败。属性 ("+ name +") 值为 ("+ value +"),但应为 ("+ expValue +")
ResourceNotFoundExceptions 未找到指定的项目或属性。

示例

有关使用 AWS 开发工具包的示例,请参阅 在 DynamoDB 中处理项目

示例请求

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

示例响应

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