UpdateItem - AWS AppSync

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

UpdateItem

UpdateItem請求對應文件可讓您告知 AWS AppSync DynamoDB 解析程式向 DynamoDB 發出UpdateItem請求,並可讓您指定下列項目:

  • 項目在動態支援中的索引鍵

  • 說明如何在 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 欄位

version

範本定義版本。目前支援 2017-02-282018-05-29。此值為必填。

operation

要執行 DynamoDB 支援作業。若要執行 UpdateItem DynamoDB 操作,這必須設為 UpdateItem。此值為必填。

key

項目在 DynamoDB 支援中的索引鍵。DynamoDB 項目可能具有單一雜湊鍵,或是雜湊鍵和排序索引鍵,具體取決於資料表結構。如需有關指定「類型值」的詳細資訊,請參閱型別系統 (要求對應)。此值為必填。

update

update節可讓您指定更新運算式,說明如何更新 DynamoDB 中的項目。如需如何撰寫更新運算式的詳細資訊,請參閱 DynamoDB UpdateExpressions 文件。此區段是必須的。

update 區段有三個元件:

expression

更新表達式。此值為必填。

expressionNames

表達式屬性 name 預留位置的替代,形式為鍵值組。該鍵對應於中使用的名稱預留位置expression,而且值必須是對應至 DynamoDB 中項目的屬性名稱的字串。此欄位為選用的,應只能填入用於 expression 中表達式屬性名稱預留位置的替代。

expressionValues

表達式屬性 value 預留位置的替代,形式為鍵值組。鍵對應用於 expression 的值預留位置,值必須是類型值。如需如何指定「類型值」的詳細資訊,請參閱型別系統 (請求對應)。此必須指定。此欄位為選用的,應只能填入用於 expression 中表達式屬性值預留位置的替代。

condition

決定要求是否成功的條件,可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件,UpdateItem 要求會更新現有的資料項目,無論項目的目前狀態為何。如需有關條件的詳細資訊,請參閱條件運算式。此值是選用的。

_version

代表項目之最新已知版本的數值。此值是選用的。此欄位用於衝突偵測,而且僅支援已建立版本的資料來源。

customPartitionKey

啟用後,此字串值會在啟用版本控制時修改 delta 同步表所使用的ds_skds_pk記錄的格式 (如需詳細資訊,請參閱AWS AppSync 開發人員指南中的衝突偵測與同步處理)。啟用時,也會啟用populateIndexFields項目的處理。此欄位為選用欄位。

populateIndexFields

布林值,當啟用時,會為差異同步表中的每筆記錄建立新項目,特別是在gsi_ds_pkgsi_ds_sk欄中。customPartitionKey如需詳細資訊,請參閱AWS AppSync 開發人員指南中的衝突偵測與同步處理。此欄位為選用欄位。

DynamoDB 中更新的項目會自動轉換為 GraphQL 和JSON原始類型,並可在對應內容 () 中使用。$context.result

如需 DynamoDB 類型轉換的詳細資訊,請參閱類型系統 (回應對映)。

如需有關回應對映範本的詳細資訊,請參閱解析器對映範本概觀。

範例 1

下列範例是 GraphQL 突變upvote(id: ID!)的對應範本。

在此範例中,DynamoDB 中的項目upvotesversion欄位會以 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!)的對應範本。

這個複雜的範例會檢查引數,並持續產生更新表達式,其只包含由用戶端提供的引數。例如,如果 titleauthor 遭到省略,則不會更新。如果指定了引數,但其值為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 的詳細資訊 UpdateItemAPI,請參閱 DynamoDB API 文件。