BatchGetItem
重要
このセクションでは、API バージョン 2011-12-05 について言及しています。これは非推奨なので、新しいアプリケーションに使用しないでください。
現在の低レベルの API に関するドキュメントについては、Amazon DynamoDB API リファレンスを参照してください。
説明
BatchGetItem オペレーションは、プライマリキーを使用して、複数のテーブルの複数の項目の属性を返します。1 回のオペレーションで取得できる項目の最大数は 100 です。また、取得される項目の数は、1 MB のサイズ制限によって制限されます。テーブルのプロビジョニングされたスループットを超えたことや内部処理が失敗したことが原因でレスポンスサイズの制限を超えた場合または結果の一部だけが返された場合、DynamoDB は UnprocessedKeys 値を返すので、取得する次の項目からオペレーションを再試行できます。DynamoDB は、この制限を適用するために、ページごとに返される項目の数を自動的に調整します。例えば、100 個の項目を取得するようにリクエストしても、個々の項目のサイズが 50 KB の場合、返されるのは 20 個の項目だけなので、適切な UnprocessedKeys 値を設定して結果の次のページを取得できます。必要に応じて、アプリケーションに独自のロジックを組み込んで、結果のページを 1 つのセットにまとめることができます。
リクエストに含まれる各テーブルのプロビジョニングされたスループットが不十分だったことが原因で処理される項目がなかった場合、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
|
プライマリキーで取得するテーブル名および対応する項目のコンテナ。項目をリクエストしている間、各テーブル名はオペレーションごとに 1 回だけ呼び出すことができます。 型: 文字列 デフォルト: なし |
はい |
Table |
取得する項目を含んでいるテーブルの名前。エントリは、ラベルのない既存のテーブルを指定する文字列です。 型: 文字列 デフォルト: なし |
はい |
Table:Keys
|
指定されたテーブルの項目を定義するプライマリのキーバリュー。プライマリキーの詳細については、「プライマリキー」を参照してください。 型: キー |
はい |
Table:AttributesToGet
|
指定したテーブル内の属性名の配列。属性名が指定されていない場合、すべての属性が返されます。見つからなかった属性は結果に表示されません。 型: 配列 |
いいえ |
Table:ConsistentRead
|
型: ブール値 |
いいえ |
レスポンス
構文
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:
Table: Keys
|
項目と、項目に関連付けられた属性を定義するプライマリキー属性値。プライマリキーの詳細については、「プライマリキー」を参照してください。 型: 属性の名前と値のペアの配列。 |
UnprocessedKeys:
Table:
AttributesToGet
|
指定したテーブル内の属性名。属性名が指定されていない場合、すべての属性が返されます。見つからなかった属性は結果に表示されません。 型: 属性名の配列。 |
UnprocessedKeys:
Table:
ConsistentRead
|
型: ブール。 |
特殊なエラー
| エラー | 説明 |
|---|---|
ProvisionedThroughputExceededException
|
許可されているプロビジョニングスループットの最大値を超えました。 |
例
次の例は、BatchGetItem オペレーションを使用した HTTP POST リクエストとレスポンスを示しています。AWS SDK を使用した例については、「DynamoDB での項目と属性の操作」を参照してください。
リクエスト例
次の例では、2 つの異なるテーブルの属性をリクエストします。
// 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":{} }
