Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

BatchGetItem

重要

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

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

说明

BatchGetItem 操作使用主键从多个表中返回多个项目的属性。单个操作可以检索的最大项目数为 100。另外,检索的项目数受到 1 MB 大小限制约束。如果超过了响应大小限制,或者因超出表的预配置吞吐量或因内部处理故障而返回部分结果,则 DynamoDB 返回 UnprocessedKeys 值,以便您能够从要获取的下一个项目开始再次尝试执行此操作。DynamoDB 自动调整每页返回的项目数以强制执行该限制。例如,即使您请求检索 100 个项目,但每个项目大小为 50 KB,系统会返回 20 个项目和相应的 UnprocessedKeys 值,以便您可以获取下一页的结果。如果需要,您的应用程序可以包含自己的逻辑,将结果页收集到一个集合中。

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

注意

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

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

设计应用程序时,请注意,DynamoDB 不保证返回响应中的属性排序方式。在请求的项目的 AttributesToGet 中包括主键值可帮助按项目解析响应。

如果请求的项目不存在,则在这些项目的响应中不返回任何内容。请求不存在的项目将占用最小数量的读取容量单位,具体取决于读取类型。有关更多信息,请参阅 项目大小和容量单位消耗

请求

语法

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": {"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,则使用一致性读取,否则使用最终一致性。

类型:布尔值

响应

语法

Copy
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

每个表占用的读取容量单位数。此值显示根据预配置吞吐量应用的数量。请求不存在的项目将占用最小数量的读取容量单位,具体取决于读取类型。有关更多信息,请参阅 读取和写入的吞吐量设置

类型:数字

UnprocessedKeys

包含可能由于达到响应大小限制而未使用当前响应处理的表及其各个键的数组。 UnprocessedKeys 值采用与 RequestItems 参数相同的格式(以便该值可以直接提供给后续 BatchGetItem 操作)。有关更多信息,请参阅上述 RequestItems 参数。

类型:数组

UnprocessedKeys: Table: Keys

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

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

UnprocessedKeys: Table: AttributesToGet

指定的表中的属性名称。如果未指定属性名称,则将返回所有属性。如果未找到某些属性,则不会在结果中显示这些属性。

类型:属性名称数组。

UnprocessedKeys: Table: ConsistentRead

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

类型:布尔值.

特殊错误

错误 说明
ProvisionedThroughputExceededException

已超出允许的预配置吞吐量上限。

示例

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

示例响应

以下示例为响应。

Copy
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": {"comp2": {"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":{} }