選取您的 Cookie 偏好設定

我們使用提供自身網站和服務所需的基本 Cookie 和類似工具。我們使用效能 Cookie 收集匿名統計資料,以便了解客戶如何使用我們的網站並進行改進。基本 Cookie 無法停用,但可以按一下「自訂」或「拒絕」以拒絕效能 Cookie。

如果您同意,AWS 與經核准的第三方也會使用 Cookie 提供實用的網站功能、記住您的偏好設定,並顯示相關內容,包括相關廣告。若要接受或拒絕所有非必要 Cookie,請按一下「接受」或「拒絕」。若要進行更詳細的選擇,請按一下「自訂」。

BatchGetItem

焦點模式
BatchGetItem - Amazon DynamoDB

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

重要

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

如需目前低階 的文件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

已超出允許的佈建輸送量上限。

範例

下列範例顯示使用 操作的HTTPPOST BatchGetItem請求和回應。如需使用 的範例 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":{} }
隱私權網站條款Cookie 偏好設定
© 2025, Amazon Web Services, Inc.或其附屬公司。保留所有權利。