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

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

BatchGetItem

重要

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

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

描述

BatchGetItem 操作使用主键返回多个表的多个项目的属性。单个操作可检索的最大项目数为 100。此外,检索到的项目数受到 1 MB 大小的限制。如果超出响应大小限制,或者因超出表的预置吞吐量或内部处理失败而返回部分结果,DynamoDB 将返回 UnprocessedKeys 值,以便您可以从要获取的下一个项目开始重试操作。DynamoDB 自动调整每页返回的项数以强制执行此限制。例如,即使您要求检索 100 个项目,但每个项目的大小为 50 KB,系统也会返回 20 个项目和相应 UnprocessedKeys 值,这样您可以获取下一页结果。如果需要,应用程序可以加入自己的逻辑,将结果页汇编为一组。

如果由于请求涉及的每个表的预置吞吐量不足而无法处理任何项目,DynamoDB 将返回 ProvisionedThroughputExceededException 错误。

注意

默认情况下,BatchGetItem 对请求中的每个表执行最终一致性读取。如果需要一致性读取,可以对每个表将 ConsistentRead 参数设置为 true

BatchGetItem 并行获取项目,最大程度地减少响应延迟。

设计应用程序时请记住,DynamoDB 无法保证返回响应中的属性排序方式。在 AttributesToGet 中加入请求项目的主键值,帮助按项目解析响应。

如果请求的项目不存在,则这些项目的响应不会返回任何内容。如果请求的项目不存在,将根据读取类型,消耗最小读取容量单位。有关更多信息,请参阅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": {"Table1": {"Keys": [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}}, {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}], "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, "Table2": {"Keys": [{"HashKeyElement": {"S":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}}], "AttributesToGet": ["AttributeName4", "AttributeName5", "AttributeName6"] } } }
名称 描述 必填
RequestItems

保存表名称和按主键获取的相应项目的容器。请求项目时,每个操作只能调用一次每个表名称。

类型:字符串

默认值:无

Table

包含要获取的项目的表名称。该条目是一个字符串,指定没有标签的现有表。

类型:字符串

默认值:无

Table:Keys

定义指定表中项目的主键值。有关主键的更多信息,请参阅 主键

类型:键

Table:AttributesToGet

指定表中的属性名称数组。如果没有指定属性名称,将返回所有属性。如果找不到某些属性,则不会出现在结果中。

类型:数组

Table:ConsistentRead

如果设置为 true,则发出一致性读取,否则将使用最终一致性。

类型:布尔值

响应

语法

HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 855 {"Responses": {"Table1": {"Items": [{"AttributeName1": {"S":"AttributeValue"}, "AttributeName2": {"N":"AttributeValue"}, "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]} }, {"AttributeName1": {"S": "AttributeValue"}, "AttributeName2": {"S": "AttributeValue"}, "AttributeName3": {"NS": ["AttributeValue", "AttributeValue", "AttributeValue"]} }], "ConsumedCapacityUnits":1}, "Table2": {"Items": [{"AttributeName1": {"S":"AttributeValue"}, "AttributeName2": {"N":"AttributeValue"}, "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]} }, {"AttributeName1": {"S": "AttributeValue"}, "AttributeName2": {"S": "AttributeValue"}, "AttributeName3": {"NS": ["AttributeValue", "AttributeValue","AttributeValue"]} }], "ConsumedCapacityUnits":1} }, "UnprocessedKeys": {"Table3": {"Keys": [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}}, {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}], "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]} } }
名称 描述
Responses

表名称和表中的相应项目属性。

类型:映射

Table

包含项目的表名称。该条目只是一个字符串,指定没有标签的表。

类型:字符串

Items

保存符合操作参数的属性名称和值的容器。

类型:属性名称映射及其数据类型和值。

ConsumedCapacityUnits

每个表消耗的读取容量单位数。此值显示应用于预置吞吐量的数字。如果请求的项目不存在,将根据读取类型,消耗最小读取容量单位。有关更多信息,请参阅 管理 DynamoDB 预调配容量表的吞吐量设置

类型:数字

UnprocessedKeys

包含当前响应未处理的表数字及其相应键,可能因为达到响应大小限制。UnprocessedKeys 值的格式和 RequestItems 参数相同(因此可以为后续 BatchGetItem 操作直接提供值)。有关更多信息,请参见上面的 RequestItems 参数。

类型:数组

UnprocessedKeys: Table: Keys

定义项目以及与项目关联的属性的主键属性值。有关主键的更多信息,请参阅 主键

类型:属性名称-值对的数组。

UnprocessedKeys: Table: AttributesToGet

指定表内的属性名称。如果未指定属性名称,则返回所有属性。如果找不到某些属性,则不会出现在结果中。

类型:属性名称的数组。

UnprocessedKeys: Table: ConsistentRead

如果设置为 true,则对指定表使用一致性读取,否则使用最终一致性读取。

类型:布尔值。

特殊错误

错误 描述
ProvisionedThroughputExceededException

超出允许的最大预置吞吐量。

示例

以下示例显示使用 BatchGetItem 操作的 HTTP POST 请求和响应。有关使用 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 content-length: 409 {"RequestItems": {"comp1": {"Keys": [{"HashKeyElement":{"S":"Casey"},"RangeKeyElement":{"N":"1319509152"}}, {"HashKeyElement":{"S":"Dave"},"RangeKeyElement":{"N":"1319509155"}}, {"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"1319509158"}}], "AttributesToGet":["user","status"]}, "comp2": {"Keys": [{"HashKeyElement":{"S":"Julie"}},{"HashKeyElement":{"S":"Mingus"}}], "AttributesToGet":["user","friends"]} } }

示例响应

下面的示例是响应。

HTTP/1.1 200 OK x-amzn-RequestId: GTPQVRM4VJS792J1UFJTKUBVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 373 Date: Fri, 02 Sep 2011 23:07:39 GMT {"Responses": {"comp1": {"Items": [{"status":{"S":"online"},"user":{"S":"Casey"}}, {"status":{"S":"working"},"user":{"S":"Riley"}}, {"status":{"S":"running"},"user":{"S":"Dave"}}], "ConsumedCapacityUnits":1.5}, "comp2": {"Items": [{"friends":{"SS":["Elisabeth", "Peter"]},"user":{"S":"Mingus"}}, {"friends":{"SS":["Dave", "Peter"]},"user":{"S":"Julie"}}], "ConsumedCapacityUnits":1} }, "UnprocessedKeys":{} }