# BatchGetItem
<a name="API_BatchGetItem_v20111205"></a>

**重要**  
***本节介绍已经弃用的 API 版本 2011-12-05，不应用于新应用程序。***  
 **有关当前低级别 API 的文档，请参阅 [Amazon DynamoDB API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**

## 描述
<a name="API_BatchGetItem_Description"></a>

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

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

**注意**  
默认情况下，`BatchGetItem` 对请求中的每个表执行最终一致性读取。如果需要一致性读取，可以对每个表将 `ConsistentRead` 参数设置为 `true`。  
`BatchGetItem` 并行获取项目，最大程度地减少响应延迟。  
设计应用程序时请记住，DynamoDB 无法保证返回响应中的属性排序方式。在 `AttributesToGet` 中加入请求项目的主键值，帮助按项目解析响应。  
如果请求的项目不存在，则这些项目的响应不会返回任何内容。如果请求的项目不存在，将根据读取类型，消耗最小读取容量单位。有关更多信息，请参阅 [DynamoDB 项目大小和格式](CapacityUnitCalculations.md)。

## 请求
<a name="API_BatchGetItem_RequestParameters"></a>

### 语法
<a name="API_BatchGetItem_RequestParameters.syntax"></a>

```
// 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  |  定义指定表中项目的主键值。有关主键的更多信息，请参阅 [主键](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。 类型：键   | 是 | 
| Table:AttributesToGet  |  指定表中的属性名称数组。如果没有指定属性名称，将返回所有属性。如果找不到某些属性，则不会出现在结果中。 类型：数组   | 否 | 
| Table:ConsistentRead  |  如果设置为 `true`，则发出一致性读取，否则将使用最终一致性。 类型：布尔值   | 否 | 

## 响应
<a name="API_BatchGetItem_ResponseElements"></a>

### 语法
<a name="API_BatchGetItem_ResponseElements.syntax"></a>

```
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 预置容量模式](provisioned-capacity-mode.md)。 类型：数字 | 
| UnprocessedKeys | 包含当前响应未处理的表数字及其相应键，可能因为达到响应大小限制。`UnprocessedKeys` 值的格式和 `RequestItems` 参数相同（因此可以为后续 `BatchGetItem` 操作直接提供值）。有关更多信息，请参见上面的 `RequestItems` 参数。类型：数组  | 
| UnprocessedKeys: Table: Keys  | 定义项目以及与项目关联的属性的主键属性值。有关主键的更多信息，请参阅 [主键](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。类型：属性名称-值对的数组。  | 
| UnprocessedKeys: Table: AttributesToGet  |  指定表内的属性名称。如果未指定属性名称，则返回所有属性。如果找不到某些属性，则不会出现在结果中。 类型：属性名称的数组。  | 
| UnprocessedKeys: Table: ConsistentRead  |  如果设置为 `true`，则对指定表使用一致性读取，否则使用最终一致性读取。 类型：布尔值。  | 

## 特殊错误
<a name="API_BatchGetItem_SpecialErrors"></a>


****  

|  错误  |  描述  | 
| --- | --- | 
| ProvisionedThroughputExceededException  | 超出允许的最大预置吞吐量。  | 

## 示例
<a name="API_BatchGetItem_Examples"></a>

以下示例显示使用 BatchGetItem 操作的 HTTP POST 请求和响应。有关使用 AWS SDK 的示例，请参阅 [使用 DynamoDB 中的项目和属性](WorkingWithItems.md)。

### 示例请求
<a name="API_BatchGetItem_Examples_Request"></a>

下面的示例请求两个不同表的属性。

```
// 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"]}
    }
}
```

### 示例响应
<a name="API_BatchGetItem_Examples_Response"></a>

下面的示例是响应。

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