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

BatchWriteItem

重要

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

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

说明

使用此操作,通过一次 调用即可在多个表中放置或删除多个项目。

要上传一个项目,可使用 PutItem;要删除一个项目,可使用 DeleteItem。但是,当您要上传或删除大量数据时 (如从 Amazon EMR (Amazon EMR) 上传大量数据或将其他数据库中的数据迁移到 DynamoDB),BatchWriteItem 提供高效的替代方案。

如果使用 Java 等语言,您可以使用线程并行上传项目。这增加了应用程序中处理线程的复杂性。其他语言不支持线程处理。例如,如果您使用的是 PHP,则必须一次上传或删除一个项目。在这两种情况下,BatchWriteItem 均提供并行处理指定的放置和删除操作的替代方案,从而向您提供线程池方法的强大功能而无需在应用程序中引入复杂性。

请注意,就占用的容量单位数而言,BatchWriteItem 操作中指定的每一单个放置和删除操作的花销是相同的。但是,由于 BatchWriteItem 并行执行指定的操作,因此会降低延迟。对不存在的项目执行删除操作占用 1 个写入容量单位。有关占用的容量单位数的更多信息,请参阅在 DynamoDB 中使用表

使用 BatchWriteItem 时,请注意以下限制:

  • 单个请求中的最大操作数 - 您总共最多可以指定 25 个放置或删除操作;但是,总请求大小不能超过 1 MB (HTTP 负载)。

  • 您只能将 BatchWriteItem 操作用来放置和删除项目。不能使用它更新现有项目。

  • 不是原子操作 - BatchWriteItem 中指定的单个操作是原子操作;但是,BatchWriteItem 作为一个整体是“最大努力”操作而不是原子操作。即,在 BatchWriteItem 请求中,一些操作可能会成功,其他操作可能会失败。失败的操作在响应的 UnprocessedItems 字段中返回。其中一些失败可能是由于您已超出为表配置的预置吞吐量,或者是由于暂时性故障 (如网络错误)。您可以进行调查并视情况重新发送请求。通常,您在一个循环中调用 BatchWriteItem,并在每次迭代中检查未处理的项目,然后使用这些未处理的项目提交一个新的 BatchWriteItem 请求。

  • 不返回任何项目 - BatchWriteItem 用于高效上传大量数据。它不提供 PutItemDeleteItem 提供的某些高级功能。例如,DeleteItem 支持在请求正文中提供 ReturnValues 字段,以请求在响应中返回已删除的项目。 BatchWriteItem 操作不在响应中返回任何项目。

  • PutItemDeleteItem 不同,BatchWriteItem 不允许在操作中对单个写入请求指定条件。

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

如果以下任一条件成立,则 DynamoDB 拒绝整个批量写入操作:

  • 如果 BatchWriteItem 请求中指定的一个或多个表不存在。

  • 如果在请求中为项目指定的主键属性与对应表的主键架构不匹配。

  • 如果您尝试在同一 BatchWriteItem 请求中对同一项目执行多个操作。例如,您不能在同一 BatchWriteItem 请求中放置并删除同一项目。

  • 如果总请求大小超过 1 MB 请求大小 (HTTP 负载) 限制。

  • 如果批中任何单个项目超过 64 KB 项目大小限制。

请求

语法

Copy
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems" : RequestItems } RequestItems { "TableName1" : [ Request, Request, ... ], "TableName2" : [ Request, Request, ... ], ... } Request ::= PutRequest | DeleteRequest PutRequest ::= { "PutRequest" : { "Item" : { "Attribute-Name1" : Attribute-Value, "Attribute-Name2" : Attribute-Value, ... } } } DeleteRequest ::= { "DeleteRequest" : { "Key" : PrimaryKey-Value } } PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK HashTypePK ::= { "HashKeyElement" : Attribute-Value } HashAndRangeTypePK { "HashKeyElement" : Attribute-Value, "RangeKeyElement" : Attribute-Value, } Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet Numeric ::= { "N": "Number" } String ::= { "S": "String" } Binary ::= { "B": "Base64 encoded binary data" } StringSet ::= { "SS": [ "String1", "String2", ... ] } NumberSet ::= { "NS": [ "Number1", "Number2", ... ] } BinarySet ::= { "BS": [ "Binary1", "Binary2", ... ] }

在请求正文中,RequestItems JSON 对象描述要执行的操作。操作按表进行分组。您可以使用 BatchWriteItem 更新或删除多个表中的多个项目。对于每个特定写入请求,您必须标识请求的类型 (PutItemDeleteItem),后跟有关该操作的详细信息。

  • 对于 PutRequest,请提供项目,即属性及其值的列表。

  • 对于 DeleteRequest,请提供主键名称和值。

响应

语法

以下是响应中返回的 JSON 正文的语法。

Copy
{ "Responses" : ConsumedCapacityUnitsByTable "UnprocessedItems" : RequestItems } ConsumedCapacityUnitsByTable { "TableName1" : { "ConsumedCapacityUnits", : NumericValue }, "TableName2" : { "ConsumedCapacityUnits", : NumericValue }, ... } RequestItems This syntax is identical to the one described in the JSON syntax in the request.

特殊错误

没有特定于此操作的错误。

示例

以下示例显示了 BatchWriteItem 操作的 HTTP POST 请求和响应。该请求对 Reply 和 Thread 表指定了以下操作:

  • 在 Reply 表中放置项目和删除项目

  • 将项目放入 Thread 表

有关使用 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.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems":{ "Reply":[ { "PutRequest":{ "Item":{ "ReplyDateTime":{ "S":"2012-04-03T11:04:47.034Z" }, "Id":{ "S":"DynamoDB#DynamoDB Thread 5" } } } }, { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ], "Thread":[ { "PutRequest":{ "Item":{ "ForumName":{ "S":"DynamoDB" }, "Subject":{ "S":"DynamoDB Thread 5" } } } } ] } }

示例响应

以下示例响应显示了对 Thread 和 Reply 表执行的放置操作已成功,而对 Reply 表执行的删除操作失败 (原因是由于超过了为该表预置的吞吐量导致的节流)。请注意 JSON 响应中的以下内容:

  • Responses 对象显示,由于对 ThreadReply 表成功进行放置操作,这两个表上已占用了一个容量单位。

  • UnprocessedItems 对象显示了对 Reply 表进行的不成功删除操作。然后,您可以发出一个新的 BatchWriteItem 调用来处理这些未处理的请求。

Copy
HTTP/1.1 200 OK x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG Content-Type: application/x-amz-json-1.0 Content-Length: 536 Date: Thu, 05 Apr 2012 18:22:09 GMT { "Responses":{ "Thread":{ "ConsumedCapacityUnits":1.0 }, "Reply":{ "ConsumedCapacityUnits":1.0 } }, "UnprocessedItems":{ "Reply":[ { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ] } }