UpdateItem - Amazon DynamoDB
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

UpdateItem

重要

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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

Description

编辑现有项目的属性。您可以执行有条件更新(如果不存在,则插入新的属性名称/值对;如果具有某些预期属性值,则替换现有名称/值对)。

注意

您无法使用 UpdateItem 更新主键属性。 而是应删除项目并使用 PutItem 创建具有新属性的新项目。

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

属性值不得为 null;字符串和二进制类型属性的长度必须大于零;并且集类型属性不得为空。具有空值的请求将被拒绝,并显示 ValidationException

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

  • PUT— 添加指定属性。如果该属性存在,它会被替换为新值。

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

  • ADD— 仅使用用于数字的添加操作或目标属性为集合 (包括字符串集)。如果目标属性是单个字符串值或标量二进制值,则 ADD 不起作用。指定的值将添加到数字值(增加或减少现有数值)中,或作为字符串集中的附加值添加。如果指定了一组值,则将向现有集中添加这些值。例如,如果原始集为 [1,2] 且提供的值为 [3],则在添加操作后,该集合为 [1,2,3],而不是“5”。如果为集合属性指定了添加操作并且指定的属性类型与现有集合类型不匹配,则会出现错误。

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

如果没有任何项目与指定的主键匹配:

  • PUT— 创建具有指定主键的新项目。然后添加指定属性。

  • DELETE— 不会发生任何操作。

  • ADD— 为属性值创建具有提供的主键和数字(或数字集)的项目。对字符串或二进制类型无效。

注意

如果您使用 ADD 增加或减少在更新之前不存在的项目的数字值,则 DynamoDB 使用 0 作为初始值。此外,如果您使用 ADD 更新项目以递增或递减在更新之前不存在的属性(但有项目存在)的数字值,则 DynamoDB 将使用 0 作为初始值。例如,您使用 ADD+3 添加到更新前不存在的属性。DynamoDB 将 0 用于初始值,更新后的值为 3

有关使用此操作的更多信息,请参阅使用项目和属性

Requests

Syntax

// 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 表示法将更新该项目:

"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

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

类型: 字符串

Responses

Syntax

以下语法示例假定请求指定了 ReturnValuesALL_OLD 参数,否则,响应仅具有 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 预置容量表的设置

类型: 数字

特殊错误

错误 描述
ConditionalCheckFailedException 条件检查失败。属性 (“+ name +”值是 (“+ value +”) 但为预期值 (“+ expValue +”)
ResourceNotFoundExceptions 找不到指定的项目或属性。

Examples

有关使用 AWS 开发工具包的示例,请参阅使用项目和属性

示例请求

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

示例响应

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 }