BatchGetItem - Amazon DynamoDB

BatchGetItem

重要

このセクションでは、API バージョン 2011-12-05 について言及しています。これは非推奨なので、新しいアプリケーションに使用しないでください。

現在の低レベルの API に関するドキュメントについては、Amazon DynamoDB API リファレンスを参照してください。

Description

BatchGetItem オペレーションは、プライマリキーを使用して、複数のテーブルの複数の項目の属性を返します。1 回のオペレーションで取得できる項目の最大数は 100 です。また、取得される項目の数は、1 MB のサイズ制限によって制限されます。テーブルのプロビジョニングされたスループットを超えたことや内部処理が失敗したことが原因でレスポンスサイズの制限を超えた場合または結果の一部だけが返された場合、DynamoDB は UnprocessedKeys 値を返すので、取得する次の項目からオペレーションを再試行できます。DynamoDB は、この制限を適用するために、ページごとに返される項目の数を自動的に調整します。例えば、100 個の項目を取得するようにリクエストしても、個々の項目のサイズが 50 KB の場合、返されるのは 20 個の項目だけなので、適切な UnprocessedKeys 値を設定して結果の次のページを取得できます。必要に応じて、アプリケーションに独自のロジックを組み込んで、結果のページを 1 つのセットにまとめることができます。

リクエストに含まれる各テーブルのプロビジョニングされたスループットが不十分だったことが原因で処理される項目がなかった場合、DynamoDB は ProvisionedThroughputExceededException エラーを返します。

注記

デフォルトでは、BatchGetItem は、リクエスト内の各テーブルに対して結果整合性のある読み込みを実行します。整合性のある読み込みが必要な場合は、テーブルごとに ConsistentRead パラメータを true に設定できます。

BatchGetItem は、レスポンスのレイテンシーを最小限に抑えるために項目を並列で取得します。

アプリケーションを設計する際は、DynamoDB では、返されるレスポンスで属性の順序が保証されないことに注意してください。リクエスト内の項目の AttributesToGet にプライマリキーバリューを含めると、項目ごとにレスポンスを解析するのに役立ちます。

リクエストされた項目が存在しない場合、その項目のレスポンスでは何も返されません。存在しない項目に対するリクエストは、読み込みのタイプに応じた最小読み込み容量ユニットを消費します。詳細については、「DynamoDB 項目のサイズと形式」を参照してください。

Requests

Syntax

// 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

true に設定されている場合、整合性のある読み込みが発行されます。それ以外の場合、結果整合性が使用されます。

型: ブール値

いいえ

Responses

Syntax

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

許可されているプロビジョニングスループットの最大値を超えました。

Examples

次の例は、BatchGetItem オペレーションを使用した HTTP POST リクエストとレスポンスを示しています。AWS SDK を使用した例については、「項目と属性を操作する」を参照してください。

リクエスト例

次の例では、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":{} }