本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# UpdateItem
`UpdateItem` 請求映射文件可讓您指示 AWS AppSync DynamoDB 解析程式向 DynamoDB 提出`UpdateItem`請求，並可讓您指定下列項目：
+ DynamoDB 中項目的索引鍵
+ 描述如何在 DynamoDB 中更新項目的更新表達式
+ 操作成功的條件
`UpdateItem` 映射文件結構如下：
```
{
"version" : "2018-05-29",
"operation" : "UpdateItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"update" : {
"expression" : "someExpression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"condition" : {
...
},
"_version" : 1
}
```
欄位定義如下：
## UpdateItem 欄位
### UpdateItem 欄位清單
**`version`**
範本定義版本。目前支援 `2017-02-28` 和 `2018-05-29`。此值為必填。
**`operation`**
要執行的 DynamoDB 操作。若要執行 `UpdateItem` DynamoDB 操作，這必須設為 `UpdateItem`。此值為必填。
**`key`**
DynamoDB 中項目的索引鍵。DynamoDB 項目可能有單一雜湊索引鍵，或雜湊索引鍵和排序索引鍵，視資料表結構而定。如需指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。此值為必填。
**`update`**
`update` 本節可讓您指定更新表達式，說明如何在 DynamoDB 中更新項目。如需有關如何撰寫更新表達式的詳細資訊，請參閱 [DynamoDB UpdateExpressions 文件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此區段是必須的。
`update` 區段有三個元件：
** `expression` **
更新表達式。此值為必填。
** `expressionNames` **
表達式屬性 *name* 預留位置的替代，形式為鍵值組。金鑰對應至 中使用的名稱預留位置`expression`，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性名稱預留位置的替代。
** `expressionValues` **
表達式屬性 *value* 預留位置的替代，形式為鍵值組。鍵對應用於 `expression` 的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。此必須指定。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性值預留位置的替代。
**`condition`**
決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件，`UpdateItem` 要求會更新現有的資料項目，無論項目的目前狀態為何。如需條件的詳細資訊，請參閱[條件表達式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)。此值是選用的。
**`_version`**
代表項目之最新已知版本的數值。此值是選用的。此欄位用於*衝突偵測*，而且僅支援已建立版本的資料來源。
**`customPartitionKey`**
啟用時，此字串值會修改啟用版本控制時差異同步資料表所使用的 `ds_sk`和 `ds_pk` 記錄格式 （如需詳細資訊，請參閱 *AWS AppSync 開發人員指南*中的[衝突偵測和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html))。啟用時，也會啟用`populateIndexFields`項目的處理。此欄位為選用欄位。
**`populateIndexFields`**
布林值，當 **與 啟用`customPartitionKey`**時，會為差異同步資料表中的每個記錄建立新的項目，特別是在 `gsi_ds_pk`和 `gsi_ds_sk`欄中。如需詳細資訊，請參閱 *AWS AppSync 開發人員指南*中的[衝突偵測和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。此欄位為選用欄位。
DynamoDB 中更新的項目會自動轉換為 GraphQL 和 JSON 基本類型，並可在映射內容中使用 (`$context.result`)。
如需 DynamoDB 類型轉換的詳細資訊，請參閱[類型系統 （回應映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。
如需回應映射範本的詳細資訊，請參閱[解析程式映射範本概觀](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。
## 範例 1
下列範例是 GraphQL 變動 的映射範本`upvote(id: ID!)`。
在此範例中，DynamoDB 中的項目的 `upvotes`和 `version` 欄位增量為 1。
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"update" : {
"expression" : "ADD #votefield :plusOne, version :plusOne",
"expressionNames" : {
"#votefield" : "upvotes"
},
"expressionValues" : {
":plusOne" : { "N" : 1 }
}
}
}
```
## 範例 2
下列範例是 GraphQL 變動 的映射範本`updateItem(id: ID!, title: String, author: String, expectedVersion: Int!)`。
這個複雜的範例會檢查引數，並持續產生更新表達式，其只包含由用戶端提供的引數。例如，如果 `title` 和 `author` 遭到省略，則不會更新。如果指定 引數，但其值為 `null`，則該欄位會從 DynamoDB 中的物件中刪除。最後， 操作有一個條件，可驗證目前在 DynamoDB 中的項目是否將 `version` 欄位設定為 `expectedVersion`：
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
## Set up some space to keep track of things we're updating **
#set( $expNames = {} )
#set( $expValues = {} )
#set( $expSet = {} )
#set( $expAdd = {} )
#set( $expRemove = [] )
## Increment "version" by 1 **
$!{expAdd.put("version", ":newVersion")}
$!{expValues.put(":newVersion", { "N" : 1 })}
## Iterate through each argument, skipping "id" and "expectedVersion" **
#foreach( $entry in $context.arguments.entrySet() )
#if( $entry.key != "id" && $entry.key != "expectedVersion" )
#if( (!$entry.value) && ("$!{entry.value}" == "") )
## If the argument is set to "null", then remove that attribute from the item in DynamoDB **
#set( $discard = ${expRemove.add("#${entry.key}")} )
$!{expNames.put("#${entry.key}", "$entry.key")}
#else
## Otherwise set (or update) the attribute on the item in DynamoDB **
$!{expSet.put("#${entry.key}", ":${entry.key}")}
$!{expNames.put("#${entry.key}", "$entry.key")}
#if( $entry.key == "ups" || $entry.key == "downs" )
$!{expValues.put(":${entry.key}", { "N" : $entry.value })}
#else
$!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
#end
#end
#end
#end
## Start building the update expression, starting with attributes we're going to SET **
#set( $expression = "" )
#if( !${expSet.isEmpty()} )
#set( $expression = "SET" )
#foreach( $entry in $expSet.entrySet() )
#set( $expression = "${expression} ${entry.key} = ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to ADD **
#if( !${expAdd.isEmpty()} )
#set( $expression = "${expression} ADD" )
#foreach( $entry in $expAdd.entrySet() )
#set( $expression = "${expression} ${entry.key} ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to REMOVE **
#if( !${expRemove.isEmpty()} )
#set( $expression = "${expression} REMOVE" )
#foreach( $entry in $expRemove )
#set( $expression = "${expression} ${entry}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
"update" : {
"expression" : "${expression}"
#if( !${expNames.isEmpty()} )
,"expressionNames" : $utils.toJson($expNames)
#end
#if( !${expValues.isEmpty()} )
,"expressionValues" : $utils.toJson($expValues)
#end
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
}
}
}
```
如需 DynamoDB `UpdateItem` API 的詳細資訊，請參閱 [DynamoDB API 文件](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)。