BatchWriteItem
说明
使用此操作,通过一次 调用即可在多个表中放置或删除多个项目。
要上传一个项目,可使用 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
用于高效上传大量数据。它不提供PutItem
和DeleteItem
提供的某些高级功能。例如,DeleteItem
支持在请求正文中提供ReturnValues
字段,以请求在响应中返回已删除的项目。BatchWriteItem
操作不在响应中返回任何项目。 -
与
PutItem
和DeleteItem
不同,BatchWriteItem
不允许在操作中对单个写入请求指定条件。 -
属性值不能为 null;字符串和二进制类型属性的长度必须大于零;集类型属性不能为空。将使用
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
更新或删除多个表中的多个项目。对于每个特定写入请求,您必须标识请求的类型 (PutItem
、DeleteItem
),后跟有关该操作的详细信息。
-
对于
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.
特殊错误
没有特定于此操作的错误。
示例
以下示例显示了 BatchWriteItem
操作的 HTTP POST 请求和响应。该请求对 Reply 和 Thread 表指定了以下操作:
-
在 Reply 表中放置项目和删除项目
-
将项目放入 Thread 表
有关使用 AWS 开发工具包的示例,请参阅 在 DynamoDB 中处理项目。
示例请求
// 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
对象显示,由于在Thread
和Reply
表上成功进行放置操作,这两个表上已占用了一个容量单位。 -
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" } } } } ] } }