BatchWriteItem - Amazon DynamoDB

BatchWriteItem

重要

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

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

説明

このオペレーションでは、単一の呼び出しで、複数のテーブルの複数の項目を配置または削除できます。

1 つの項目をアップロードするには、PutItem を使用できます。1 つの項目を削除するには、DeleteItem を使用できます。ただし、Amazon EMR (Amazon EMR) から大量のデータをアップロードする場合や別のデータベースのデータを DynamoDB に移行する場合など、大量のデータをアップロードまたは削除する場合、BatchWriteItem では効率的な方法が用意されています。

Java などの言語を使用する場合は、スレッドを使用して項目を並列でアップロードできます。これにより、スレッドを処理するアプリケーションの複雑さが増します。他の言語はスレッドの使用をサポートしていません。例えば、PHP を使用している場合は、項目を 1 つずつアップロードまたは削除する必要があります。どちらの状況でも、BatchWriteItem は、指定されたアップロードおよび削除オペレーションを並列で処理する代替手段を提供し、アプリケーションを複雑にすることなくスレッドプールのアプローチの威力を発揮します。

BatchWriteItem オペレーションで指定された個々のアップロードと削除のコストは、消費される容量単位と同じです。ただし、指定したオペレーションが BatchWriteItem によって並列で実行されると、レイテンシーが小さくなります。存在しない項目に対する削除オペレーションは、書き込み容量ユニットを 1 つ消費します。消費される容量ユニットの詳細については、「DynamoDB でのテーブルとデータの操作」を参照してください。

BatchWriteItem を使用する場合、以下の制限に注意してください。

  • 1 つのリクエストにおける最大オペレーション数 - 最大 25 個のアップロードまたは削除オペレーションを指定できます。ただし、リクエストの合計サイズは 1 MB (HTTP ペイロード) を超えることはできません。

  • BatchWriteItem オペレーションは、項目のアップロードと削除行うためにのみ使用できます。既存の項目を更新するためには使用できません。

  • アトミック操作ではありません - 1 つの BatchWriteItem で指定されている個々の操作はアトミックです。ただし、BatchWriteItem 全体が「ベストエフォート」操作であり、アトミック操作ではありません。したがって、BatchWriteItem リクエストでは、一部のオペレーションは成功し、他のオペレーションは失敗する可能性があります。失敗したオペレーションは、レスポンスの UnprocessedItems フィールドに返されます。これらの失敗の原因としては、テーブルに設定されているプロビジョニングされたスループットを超えたか、ネットワークエラーなどの一時的な障害が考えられます。リクエストを調査し、必要に応じてリクエストを再送信できます。通常、ループ内で BatchWriteItem を呼び出し、各反復で未処理の項目をチェックして、未処理の項目とともに新しい BatchWriteItem リクエストを送信します。

  • 項目は返されません - BatchWriteItem は大量のデータを効率的にアップロードするように設計されています。PutItem および DeleteItem で提供されている高度な機能の一部は提供されていません。例えば、DeleteItem は、レスポンス内の削除済み項目をリクエストするためにリクエストボディ内の ReturnValues フィールドをサポートします。BatchWriteItem オペレーションはレスポンスで項目を返しません。

  • PutItemDeleteItem とは異なり、BatchWriteItem では、オペレーション内の個々の書き込みリクエストに対して条件を指定することはできません。

  • 属性値は NULL であってはなりません。文字列型およびバイナリ型属性の長さは 0 より大きくなければなりません。また、セット型属性は空であってはなりません。空の値を持つリクエストは、ValidationException で拒否されます。

DynamoDB は、次のいずれかが真である (true) 場合バッチ書き込みオペレーション全体を拒否します。

  • BatchWriteItem リクエスト内で指定したテーブルが存在しない。

  • リクエスト内の項目で指定されたプライマリキー属性が、対応するテーブルのプライマリキースキーマと一致しない。

  • 同じ BatchWriteItem リクエストで同じ項目に複数のオペレーションを実行する。例えば、同じ項目を同一の BatchWriteItem リクエストでアップロードおよび削除することはできません。

  • 合計リクエストサイズが 1 MB のリクエストサイズ (HTTP ペイロード) 制限を超過する。

  • バッチ内の個々の項目が 64 KB の項目のサイズ制限を超えている。

リクエスト

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" : RequestItems } RequestItems { "TableName1" : [ Request, Request, ... ], "TableName2" : [ Request, Request, ... ], ... } Request ::= PutRequest | DeleteRequest PutRequest ::= { "PutRequest" : { "Item" : { "Attribute-Name1" : Attribute-Value, "Attribute-Name2" : Attribute-Value, ... } } } DeleteRequest ::= { "DeleteRequest" : { "Key" : PrimaryKey-Value } } PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK HashTypePK ::= { "HashKeyElement" : Attribute-Value } HashAndRangeTypePK { "HashKeyElement" : Attribute-Value, "RangeKeyElement" : Attribute-Value, } Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet Numeric ::= { "N": "Number" } String ::= { "S": "String" } Binary ::= { "B": "Base64 encoded binary data" } StringSet ::= { "SS": [ "String1", "String2", ... ] } NumberSet ::= { "NS": [ "Number1", "Number2", ... ] } BinarySet ::= { "BS": [ "Binary1", "Binary2", ... ] }

リクエストボディでは、RequestItems JSON オブジェクトは、実行するオペレーションを記述します。オペレーションはテーブルごとにグループ化されます。BatchWriteItem を使用して、複数のテーブル間で複数の項目を更新または削除できます。書き込みリクエストごとに、リクエストのタイプ (PutItemDeleteItem) を指定した後にオペレーションに関する詳細情報を指定する必要があります。

  • PutRequest では、項目 (属性とその値のリスト) を指定します。

  • DeleteRequest では、プライマリキーの名前と値を指定します。

レスポンス

Syntax

レスポンスで返される JSON 本文の構文を以下に示します。

{ "Responses" : ConsumedCapacityUnitsByTable "UnprocessedItems" : RequestItems } ConsumedCapacityUnitsByTable { "TableName1" : { "ConsumedCapacityUnits", : NumericValue }, "TableName2" : { "ConsumedCapacityUnits", : NumericValue }, ... } RequestItems This syntax is identical to the one described in the JSON syntax in the request.

特殊なエラー

このオペレーションに固有のエラーはありません。

次の例は、HTTP POST リクエストと BatchWriteItem オペレーションのレスポンスを示しています。リクエストは、Reply テーブルと Thread テーブルに対して以下のオペレーションを指定します。

  • Reply テーブルに対して 1 つの項目の配置と削除を行う

  • Thread テーブルに項目を配置する

AWS SDK を使用した例については、「項目と属性の操作」を参照してください。

リクエスト例

// 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":{ "Reply":[ { "PutRequest":{ "Item":{ "ReplyDateTime":{ "S":"2012-04-03T11:04:47.034Z" }, "Id":{ "S":"DynamoDB#DynamoDB Thread 5" } } } }, { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ], "Thread":[ { "PutRequest":{ "Item":{ "ForumName":{ "S":"DynamoDB" }, "Subject":{ "S":"DynamoDB Thread 5" } } } } ] } }

レスポンス例

次のレスポンスの例は、Thread テーブルと Reply テーブルの両方に対する配置オペレーションが成功し、Reply テーブルに対する削除オペレーションが (テーブルでプロビジョニングされたスループットを超えた場合に発生するスロットリングなどの理由で) 失敗したことを示しています。JSON レスポンスでは、以下の点に注意してください。

  • Responses オブジェクトは、Thread テーブルと Reply テーブルのそれぞれで成功した配置オペレーションの結果として両方のテーブルで 1 つの容量ユニットが消費されます。

  • UnprocessedItems オブジェクトには、Reply テーブルで正常に完了しなかった削除オペレーションが示されます。その後、新しい BatchWriteItem 呼び出しを発行して、これらの未処理のリクエストに対処できます。

HTTP/1.1 200 OK x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG Content-Type: application/x-amz-json-1.0 Content-Length: 536 Date: Thu, 05 Apr 2012 18:22:09 GMT { "Responses":{ "Thread":{ "ConsumedCapacityUnits":1.0 }, "Reply":{ "ConsumedCapacityUnits":1.0 } }, "UnprocessedItems":{ "Reply":[ { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ] } }