Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

PutItem

重要

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

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

説明

新しい項目を作成するか、古い項目を(すべての属性を含め)新しい項目で置き換えます。指定したテーブルに同じプライマリキーを持つ項目が存在する場合、既存の項目は新しい項目に完全に置き換えられます。条件付き入力(指定したプライマリキーを持つ項目が存在しない場合は新しい項目を挿入する)を実行するか、または、既存の項目に特定の属性値がある場合はその項目を置換できます。

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

注記

新しい項目によって既存の項目が置き換えられないようにするには、プライマリキー属性について Existsfalse に設定して条件付き入力オペレーションを使用します。

PutItem の使用の詳細については、「DynamoDB での項目の操作」を参照してください。

リクエスト

構文

// This header is abbreviated. // For a sample of a complete header, see DynamoDB 低レベル API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.PutItem content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Item":{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"N":"AttributeValue2"}, "AttributeName5":{"B":"dmFsdWU="} }, "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}}, "ReturnValues":"ReturnValuesConstant"}

名前 説明 必須
TableName

項目を格納するテーブルの名前。

型: 文字列

はい
Item

項目の属性のマップ。項目を定義するプライマリキー値を含んでいる必要があります。その他の属性名と値のペアを項目に対して指定できます。プライマリキーの詳細については、「プライマリキー」を参照してください。

型: 属性名と属性値のマップ

はい
Expected

条件付き入力の属性を指定します。Expected パラメータでは、属性名と、属性値がすでに存在するかどうか、または属性値を変更する前に属性値がすでに存在し、特定の値があるかどうかを DynamoDB がチェックする必要があるかどうかを指定できます。

型: 属性名と属性値のマップ、および存在するかどうか

いいえ
Expected:AttributeName

条件付き入力の属性の名前。

型: 文字列

いいえ
Expected:AttributeName: ExpectedAttributeValue このパラメータを使用して、属性名と値のペアに対して値がすでに存在するかどうかを指定します。

以下の JSON 表記は「Color」属性がそのアイテムにすでに存在していない場合に置き換えます。

"Expected" : {"Color":{"Exists":false}}

以下の JSON 表記では項目を置き換える前に「Color」属性に「Yellow」の値があるか確認します。

"Expected" : {"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}

デフォルトにより、Expected パラメータを使用して Value を提供すると、DynamoDB は属性が存在し現在の値を持つ更新が必要なものと見なします。暗黙的に示されているので、{"Exists":true} を指定する必要はありません。リクエストを短縮することができます。

"Expected" : {"Color":{"Value":{"S":"Yellow"}}}

注記

属性値を確認せずに {"Exists":true} を特定すると、DynamoDB はエラーを返します。

いいえ
ReturnValues

PutItem リクエストで更新される前に属性名と値のペアを取得する場合は、このパラメータを使用します。有効なパラメータ値は、NONE(デフォルト)または ALL_OLD です。ALL_OLD を指定し、PutItem が属性名と値のペアを上書きした場合、古い項目の内容が返されます。このパラメータを指定しなかった場合、または NONE に設定した場合、何も返されません。

型: 文字列

いいえ

レスポンス

構文

次の構文例では、リクエストで ReturnValues パラメータが ALL_OLD に指定されていると想定しています。それ以外の場合、レスポンスには ConsumedCapacityUnits 要素のみ格納されます。

HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 85 {"Attributes": {"AttributeName3":{"S":"AttributeValue3"}, "AttributeName2":{"SS":"AttributeValue2"}, "AttributeName1":{"SS":"AttributeValue1"}, }, "ConsumedCapacityUnits":1 }

名前 説明
Attributes

入力オペレーションの前の属性値。ただし、リクエストで、ReturnValues パラメータが ALL_OLD に指定されている場合のみ、返されます。

型: 属性名と値のペアのマップ

ConsumedCapacityUnits

オペレーションによって消費された書き込みキャパシティーユニットの数。この値は、プロビジョニングされたスループットに対して適用された数を示します。詳細については、「プロビジョニングされたテーブルでのスループット設定の管理」を参照してください。

型: 数値

特殊なエラー

エラー 説明
ConditionalCheckFailedException 条件チェックが失敗しました。予期される属性値が見つかりませんでした。
ResourceNotFoundException 指定した項目または属性が見つかりませんでした。

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.PutItem content-type: application/x-amz-json-1.0 {"TableName":"comp5", "Item": {"time":{"N":"300"}, "feeling":{"S":"not surprised"}, "user":{"S":"Riley"} }, "Expected": {"feeling":{"Value":{"S":"surprised"},"Exists":true}} "ReturnValues":"ALL_OLD" }

レスポンス例

HTTP/1.1 200 x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 84 {"Attributes": {"feeling":{"S":"surprised"}, "time":{"N":"300"}, "user":{"S":"Riley"}}, "ConsumedCapacityUnits":1 }