本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# BatchGetItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`BatchGetItem` 操作會使用多個資料表的主索引鍵從中傳回多個項目的屬性。單一操作最多可擷取的項目數為 100。此外，擷取的項目數受到 1 MB 大小限制。如果超過回應大小限制，或者因為超出資料表的佈建輸送量，或因為內部處理失敗而傳回部分結果，則 DynamoDB 會傳回 `UnprocessedKeys` 值，以便您重試從下一個要獲取的項目開始的操作。DynamoDB 會自動調整每個頁面傳回的項目數，以便強制執行此限制。例如，即使您要求擷取 100 個項目，但每一個別項目大小為 50 KB，系統也會傳回 20 個項目和適當的 `UnprocessedKeys` 值，以便您取得下一頁的結果。如有需要，應用程式可包含自身的邏輯，將結果頁面組合成一組。
如果因為請求中涉及的每個資料表上佈建輸送量不足而無法處理任何項目，則 DynamoDB 會傳回 `ProvisionedThroughputExceededException` 錯誤。
**注意**
根據預設，`BatchGetItem` 會對請求中每個資料表執行最終一致讀取。如果想改為一致性讀取，可以在每份資料表將 `ConsistentRead` 參數設定為 `true`。
`BatchGetItem` 會平行擷取項目，將回應延遲減至最低。
設計應用程式時，請注意 DynamoDB 不保證傳回的回應中的屬性順序。在 `AttributesToGet` 中包含請求中項目的主索引鍵值，以便協助按項目剖析回應。
如果請求項目不存在，則這些項目的回應中不會傳回任何內容。請求不存在項目會使用最小讀取容量單位，具體值根據讀取類型而定。如需更多詳細資訊，請參閱 [DynamoDB 項目大小和格式](CapacityUnitCalculations.md)。
## 請求
### 語法
```
// 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`，則會發送一致性讀取，反之則會使用最終一致性。 類型：布林值 | 否 |
## 回應
### 語法
```
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`，則指定資料表會使用一致性讀取，反之則會使用最終一致讀取。 類型：布林值。 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ProvisionedThroughputExceededException | 已超出允許的佈建輸送量上限。 |
## 範例
下列範例顯示使用 BatchGetItem 操作的 HTTP POST 請求和回應。如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
下列範例請求兩個不同資料表的屬性。
```
// 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":{}
}
```