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

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

BatchWriteItem

重要

本节介绍已经弃用的 API 版本 2011-12-05,不应用于新应用程序。

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

描述

此操作可以在一次调用中,放入或删除多个表中的多个项目。

要上传项目,可以使用 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 操作在响应中不返回任何项目。

  • 不像 PutItemDeleteItemBatchWriteItem 不允许为操作中的单个写入请求指定条件。

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

如果满足以下任一条件,DynamoDB 将拒绝整个批处理写入操作:

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

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

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

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

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

请求

语法

// 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 正文的语法如下。

{ "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.

特殊错误

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

示例

下面的示例显示 HTTP POST 请求和 BatchWriteItem 操作的响应。请求指定对回复和线程表执行以下操作:

  • 在回复表中放入一个项目并删除一个项目

  • 将线程表中放入一个项目

有关使用 Amazon SDK 的示例,请参阅 使用项目和属性

示例请求

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

示例响应

下面的示例响应显示对线程和回复表执行的放入操作成功,对回复表执行的删除操作失败(原因是超出表的预置吞吐量,导致节流)。注意 JSON 响应的以下内容:

  • Responses 对象显示由于在 ThreadReply 表的放入操作成功,这两个表各消耗一个容量单位。

  • UnprocessedItems 对象显示 Reply 表上删除操作失败。可以发出一个新的 BatchWriteItem 调用来处理这些未处理的请求。

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