PutItem - Amazon DynamoDB
説明リクエストレスポンス特殊なエラー例関連アクション

PutItem

重要

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

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

説明

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

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

注記

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

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 の場合、何も返されません。

型: 文字列

 不可

レスポンス

構文

次の構文例では、ALL_OLD の ReturnValues パラメータが指定されたリクエストを引き受けます。指定されていない場合、レスポンスには 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

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

型: 数値

特殊なエラー

エラー 説明
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
}