BatchGetItem - Amazon DynamoDB
描述请求响应特殊错误示例

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 请求和响应。有关使用 AWS SDK 的示例，请参阅 使用 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 
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":{}
}