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

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

BatchGetItem

重要

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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

Description

操作使用主键从多个表中返回多个项目的属性。BatchGetItem单个操作可以检索的最大项目数为 100。此外,检索的项目数受 1 MB 大小限制的约束。如果由于超过了响应大小限制或由于超过了表的预置吞吐量或由于内部处理失败而返回了部分结果,则 DynamoDB 将返回 UnprocessedKeys 值,以便您可以重试从下一个项目开始的操作来获取。DynamoDB 自动调整每页返回的项目数以强制实施此限制。例如,即使您要求 检索 100 个项目,但每个单独的项目的大小均为 50 KB,系统仍会返回 20 个项目和相应的 UnprocessedKeys 值,以便您可以获得下一页的结果。如果需要,您的应用程序可以包含自己的逻辑,将若干页结果汇编成一组。

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

注意

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

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

设计应用程序时,请记住,DynamoDB 不保证属性在返回的响应中是如何排序的。在 AttributesToGet 中为请求中的项目包含主键值,以帮助按项目解析响应。

如果请求的项目不存在,则这些项目的响应中不会返回任何内容。对不存在的项目的请求将根据读取类型消耗最小读取容量单位。有关更多信息,请参阅DynamoDB 项目大小和格式

Requests

Syntax

// 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,则将发出一致性读取,否则将使用最终一致性。

类型: Boolean

Responses

Syntax

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

已超过您允许的最大预置吞吐量。

Examples

以下示例显示了使用 BatchGetItem 操作的 HTTP POST 请求和响应。有关使用 AWS 开发工具包的示例,请参阅使用项目和属性

示例请求

以下示例请求来自两个不同的表的属性。

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