UpdateItem

重要

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

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

説明

既存の項目の属性を編集します。条件付き更新を実行できます (属性名と値のペアが存在しない場合は新しい属性名と値のペアを挿入し、予期される属性値が存在する場合は既存の名前と値のペアを置き換えます)。

注記

UpdateItem を使用してプライマリキー属性を更新することはできません。その場合、項目を削除し、PutItem を使用して新しい属性で新しい項目を作成します。

UpdateItem オペレーションには、更新の実行方法を定義する Action パラメータが含まれます。属性値を配置、削除、または追加できます。

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

指定したプライマリキーが既存の項目に存在する場合:

• PUT - 指定した属性を追加します。属性が存在する場合は、新しい値で置き換えられます。

• DELETE - 値を指定しない場合、属性とその値が削除されます。値のセットが指定されている場合、指定されたセット内の値が古いセットから削除されます。したがって、属性値に [a,b,c] が含まれ、削除アクションに [a,c] が含まれる場合、最終的な属性値は [b] です。指定した値の型は、既存の値の型と一致する必要があります。空のセットの指定は無効です。

• ADD — 数値の追加アクションの場合、またはターゲット属性がセット (文字列セットを含む) の場合にのみ使用します。ターゲット属性が単一の文字列値またはスカラーバイナリ値の場合、ADD は機能しません。指定された値は、数値に追加されるか (既存の数値のインクリメントまたはデクリメント)、文字列セット内の追加値として追加されます。値のセットが指定されている場合、値は既存のセットに追加されます。例えば、元のセットが [1,2] で、指定された値が [3] の場合、追加オペレーション後のセットは [4,5] ではなく [1,2,3] になります。セット属性に対して Add アクションが指定されていて、指定した属性の型が既存のセットの型と一致しない場合、エラーが発生します。

  存在しない属性に対して ADD を使用すると、属性とその値が項目に追加されます。

指定したプライマリキーに一致する項目がない場合:

• PUT - 指定されたプライマリキーで新しい項目を作成します。その後、指定された属性を追加します。

• DELETE - 何の処理も行われません。

• ADD — 属性値に対して指定されたプライマリキーと数値 (または数値のセット) で項目を作成します。文字列またはバイナリ型の場合は無効です。

注記

ADD を使用して、更新の前に存在しない項目の数値をインクリメントまたはデクリメントした場合、DynamoDB は初期値として 0 を使用します。また、ADD を使用して項目を更新し、更新の前に (項目は存在しても) 存在しない属性の数値をインクリメントまたはデクリメントした場合、DynamoDB は初期値として 0 を使用します。例えば、ADD を使用して、更新の前に存在しなかった属性に +3 を追加するとします。DynamoDB は初期値に 0 を使用します。更新後の値は 3 です。

このオペレーションの使用に関する詳細については、項目と属性の操作 を参照してください。

リクエスト

構文

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低レベル API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},
        "RangeKeyElement":{"N":"AttributeValue2"}},
    "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
    "ReturnValues":"ReturnValuesConstant"
}

名前	説明	必須
TableName	更新する項目を含めるテーブルの名前。 型: 文字列	はい
Key	項目を定義するプライマリキー。プライマリキーの詳細については、「プライマリキー」を参照してください。 型: HashKeyElement の値に対するマップと RangeKeyElement の値に対するマップ。	はい
AttributeUpdates	更新のための値、およびアクションに対する属性名マップ。属性名は変更する属性を指定します。プライマリキー属性を含めることはできません。 型: 属性更新のための属性名、値、およびアクション。
AttributeUpdates:Action	更新の実行方法を指定します。使用できる値: PUT (デフォルト)、ADD、または DELETE。セマンティクスについては、UpdateItem の説明を参照してください。 型: 文字列 デフォルト: PUT	いいえ
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	UpdateItem リクエストで属性名と値のペアを更新する前に属性名と値のペアを取得する場合、このパラメータを使用します。使用できるパラメータの値は、NONE (デフォルト) または ALL_OLD、UPDATED_OLD、ALL_NEW、または UPDATED_NEW です。ALL_OLD を指定し、UpdateItem によって属性名と値のペアが上書きされた場合、古い項目の内容が返されます。このパラメータを指定しない場合、または NONE の場合、何も返されません。ALL_NEW が指定されている場合、新しいバージョンの項目のすべての属性が返されます。UPDATED_NEW が指定されている場合、更新された属性の新しいバージョンのみが返されます。 型: 文字列	いいえ

レスポンス

構文

次の構文例では、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: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}

名前	説明
Attributes	属性名と値のペアのマップ (ReturnValues パラメータがリクエストの NONE 以外のものとして指定されている場合)。 型: 属性の名前と値のペアのマップ。
ConsumedCapacityUnits	オペレーションによって消費される書き込み容量ユニットの数。この値は、プロビジョニングされたスループットに適用される数を示します。詳細については、「DynamoDB のプロビジョンされた容量テーブルの設定の管理」を参照してください。 型: 数値

特殊なエラー

エラー	説明
ConditionalCheckFailedException	条件チェックに失敗しました。属性 ("+ name +") の値は ("+ name +") ですが、("+ expValue +") が予期されていました。
ResourceNotFoundExceptions	指定された項目または属性が見つかりませんでした。

例

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.UpdateItem
content-type: application/x-amz-json-1.0 

{"TableName":"comp5",
    "Key":
        {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
    "AttributeUpdates":
        {"status":{"Value":{"S":"online"},
        "Action":"PUT"}},
    "Expected":{"status":{"Value":{"S":"offline"}}},
    "ReturnValues":"ALL_NEW"
}

レスポンス例

HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT

{"Attributes":
    {"friends":{"SS":["Lynda, Aaron"]},
    "status":{"S":"online"},
    "time":{"N":"1307654350"},
    "user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}

関連アクション

• PutItem

• DeleteItem