メニュー
Amazon DynamoDB
開発者ガイド (API Version 2012-08-10)

BatchWriteItem

重要

このセクションは、廃止された API バージョン 2011-12-05 についての記述で、新しいアプリケーションで使用することはできません。

現在の低レベル API のドキュメントについては、Amazon DynamoDB API Referenceを参照してください。

説明

このオペレーションでは、1 回の コールで複数のテーブルにまたがる複数の項目を入力または削除できます。

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 オペレーションは、項目を入力および削除する場合にのみ使用できます。既存の項目を更新する場合は使用できません。

  • アトミックオペレーションではありませんBatchWriteItem に指定する各オペレーションはアトミックですが、BatchWriteItem 全体では、アトミックオペレーションではなく、"ベストエフォート" オペレーションです。つまり、BatchWriteItem リクエストでは、成功するオペレーションと失敗するオペレーションがあります。失敗したオペレーションは、レスポンスの UnprocessedItems フィールドで返されます。失敗の原因として、テーブルに対して設定されたプロビジョニングされたスループットを超過したか、ネットワークエラーなどの一時的なエラーが考えられます。調査して、必要に応じてリクエストを再送信できます。通常、ループで BatchWriteItem を呼び出し、各反復で、未処理の項目の有無を確認し、その未処理の項目を指定した新しい BatchWriteItem リクエストを送信します。

  • 項目を返しませんBatchWriteItem は、大量のデータを効率的にアップロードすることを目的に設計されています。これには、PutItemDeleteItem などによって提供される高度な機能の一部が備わっていません。 たとえば、DeleteItem では、レスポンスで削除された項目をリクエストするためにリクエストの本文に ReturnValues フィールドを指定することをサポートしています。 BatchWriteItem オペレーションでは、レスポンスで項目を返しません。

  • PutItemDeleteItem とは異なり、BatchWriteItem では、オペレーションの各書き込みリクエストに条件を指定できません。

  • 属性値を null にすることはできません。文字列型およびバイナリ型の属性の長さは、ゼロより大きくする必要があります。セット型属性を空白にすることはできません。空白の値があるリクエストは、ValidationException で拒否されます。

DynamoDB は、次の条件のいずれか 1 つでも当てはまる場合、バッチ書き込みオペレーション全体を拒否します。

  • BatchWriteItem リクエストに指定された 1 つ以上のテーブルが存在しない。

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

  • 同じ BatchWriteItem リクエストで、同じ項目に対して複数のオペレーションを実行しようとしている。たとえば、同じ BatchWriteItem リクエストで、同じ項目を入力および削除することはできません。

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

  • バッチの項目のいずれかが 64 KB 項目サイズ制限を超えている。

リクエスト

構文

Copy
// 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 の場合、プライマリキーの名前と値を指定します。

レスポンス

構文

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

Copy
{ "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.

特殊なエラー

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

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

  • Reply テーブルで項目を入力し、項目を削除する

  • Thread テーブルに項目を入力する

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

リクエスト例

Copy
// 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 コールを実行して、この未処理のリクエストに対応できます。

Copy
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" } } } } ] } }