GetItem PutItem UpdateItem DeleteItem Query スキャン Sync BatchGetItem BatchDeleteItem BatchPutItem TransactGetItems TransactWriteItems 型システム (リクエストマッピング)型システム (レスポンスマッピング)フィルタ条件式トランザクション条件式

DynamoDB のリゾルバーのマッピングテンプレートリファレンス

AWS AppSync DynamoDB のリゾルバーにより、GraphQL を使用してアカウントの既存の Amazon DynamoDB テーブルにデータを保存したり、既存のテーブルからデータを取得したりできます。このリゾルバーにより、受信した GraphQL リクエストを DynamoDB の呼び出しにマッピングし、その後 DynamoDB のレスポンスを GraphQL にマッピングすることができます。このセクションでは、サポートされる DynamoDB の処理のマッピングテンプレートについて説明します。

トピック

GetItem
PutItem
UpdateItem
DeleteItem
Query
スキャン
Sync
BatchGetItem
BatchDeleteItem
BatchPutItem
TransactGetItems
TransactWriteItems
型システム (リクエストマッピング)
型システム (レスポンスマッピング)
フィルタ
条件式
トランザクション条件式

GetItem

GetItem リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への GetItem リクエストで、以下のように指定できます。

DynamoDB の項目のキー
整合性のある読み込みを使用するかどうか

GetItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

各フィールドの定義は以下のようになります。

version: テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。GetItem DynamoDB の処理を実行するには、これを GetItem に設定する必要があります。この値は必須です。
key: DynamoDB の項目のキーです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
consistentRead: DynamoDB で強力な整合性のある読み込みを実行するかどうかを示します。これはオプションであり、デフォルトは false です。

DynamoDB から返された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

例

以下は、GraphQL クエリ getThing(foo: String!, bar: String!) のマッピングテンプレートです。


{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "consistentRead" : true
}

DynamoDB GetItem API の詳細については、DynamoDB API のドキュメントを参照してください。

PutItem

PutItem リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への PutItem リクエストで、以下のように指定できます。

DynamoDB の項目のキー
項目の完全なコンテンツ (key および attributeValues で構成されます)
処理が成功する条件

PutItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    },
    "_version" : 1
}

各フィールドの定義は以下のようになります。

version: テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。PutItem DynamoDB の処理を実行するには、これを PutItem に設定する必要があります。この値は必須です。
key: DynamoDB の項目のキーです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
attributeValues: DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、PutItem リクエストはその項目の既存のエントリを上書きします。条件の詳細については、「条件式」を参照してください。この値はオプションです。
_version: 項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは競合の検出に使用され、バージョン管理されたデータソースでのみサポートされます。

DynamoDB に書き込まれた項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

例 1

以下は、GraphQL ミューテーション updateThing(foo: String!, bar: String!, name: String!, version: Int!) のマッピングテンプレートです。

指定したキーに対応する項目がない場合は、作成されます。指定したキーに対応する項目がすでにある場合は、上書きされます。


{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
    }
}

例 2

以下は、GraphQL ミューテーション updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!) のマッピングテンプレートです。

この例では、DynamoDB に現在ある項目の version フィールドに expectedVersion が設定されていることを確認します。


{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        #set( $newVersion = $context.arguments.expectedVersion + 1 )
        "version" : $util.dynamodb.toDynamoDBJson($newVersion)
    },
    "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

DynamoDB PutItem API の詳細については、DynamoDB API のドキュメントを参照してください。

UpdateItem

UpdateItem リクエストマッピングドキュメントでは、AWS AppSync DynamoDB のリゾルバーから DynamoDB への UpdateItem リクエストを定義し、以下のように指定できます。

DynamoDB の項目のキー
DynamoDB の項目を更新する方法を示す更新式
処理が成功する条件

UpdateItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "UpdateItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "update" : {
        "expression" : "someExpression"
        "expressionNames" : {
           "#foo" : "foo"
       },
       "expressionValues" : {
           ":bar" : ... typed value
       }
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

各フィールドの定義は以下のようになります。

version

テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。UpdateItem DynamoDB の処理を実行するには、これを UpdateItem に設定する必要があります。この値は必須です。

key

DynamoDB の項目のキーです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。

update

update セクションには、DynamoDB の項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、DynamoDB UpdateExpressions のドキュメントを参照してください。このセクションは必須です。

update セクションには次の 3 つのコンポーネントがあります。

expression: 更新式です。この値は必須です。
expressionNames: 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、expression で使用される式の属性名のプレースホルダーのみを入力します。
expressionValues: 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。

condition

DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、UpdateItem リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件の詳細については、「条件式」を参照してください。この値はオプションです。

_version

項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは競合の検出に使用され、バージョン管理されたデータソースでのみサポートされます。

DynamoDB の更新された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

例 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 のドキュメントを参照してください。

DeleteItem

DeleteItem リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への DeleteItem リクエストで、以下のように指定できます。

DynamoDB の項目のキー
処理が成功する条件

DeleteItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "DeleteItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

各フィールドの定義は以下のようになります。

version: テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。DeleteItem DynamoDB の処理を実行するには、これを DeleteItem に設定する必要があります。この値は必須です。
key: DynamoDB の項目のキーです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、DeleteItem リクエストによって、現在の状態にかかわらず、項目が削除されます。条件の詳細については、「条件式」を参照してください。この値はオプションです。
_version: 項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは競合の検出に使用され、バージョン管理されたデータソースでのみサポートされます。

DynamoDB から削除された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

例 1

以下は、GraphQL ミューテーション deleteItem(id: ID!) のマッピングテンプレートです。この ID に対応する項目がある場合は、削除されます。


{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

例 2

以下は、GraphQL ミューテーション deleteItem(id: ID!, expectedVersion: Int!) のマッピングテンプレートです。この ID に対応する項目がある場合は、その version フィールドに expectedVersion が設定されているときにのみ削除されます。


{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "condition" : {
        "expression"       : "attribute_not_exists(id) OR version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

DynamoDB DeleteItem API の詳細については、DynamoDB API のドキュメントを参照してください。

Query

Query リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への Query リクエストで、以下のように指定できます。

キー式
使用するインデックス
任意の追加フィルタ
返す項目の数
整合性のある読み込みを使用するかどうか
クエリの方向 (前方または後方)
ページ分割トークン

Query マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "some expression",
        "expressionNames" : {
            "#foo" : "foo"
        },
        "expressionValues" : {
            ":bar" : ... typed value
        }
    }
    "index" : "fooIndex",
    "nextToken" : "a pagination token",
    "limit" : 10,
    "scanIndexForward" : true,
    "consistentRead" : false,
    "select" : "ALL_ATTRIBUTES",
    "filter" : {
        ...
    }
}

各フィールドの定義は以下のようになります。

version

テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。Query DynamoDB の処理を実行するには、これを Query に設定する必要があります。この値は必須です。

query

query セクションには、DynamoDB から取得する項目を指示するキー条件式を指定することができます。キー条件式の記述方法の詳細については、DynamoDB KeyConditions のドキュメントを参照してください。このセクションの指定は必須です。

expression: クエリ式です。このフィールドの指定は必須です。
expressionNames: 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、expression で使用される式の属性名のプレースホルダーのみを入力します。
expressionValues: 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。

filter

DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用する追加フィルタです。フィルタの詳細については、「フィルタ」を参照してください。このフィールドはオプションです。

index

クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。

nextToken

前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。

limit

評価する項目の最大数（一致する項目の数であるとは限りません）。このフィールドはオプションです。

scanIndexForward

クエリを前方と後方のどちらに実行するかを示すブール値です。このフィールドはオプションであり、デフォルトは true です。

consistentRead

DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは false です。

select

デフォルトでは、AWS AppSync DynamoDB のリゾルバーはインデックスに射影されるすべての属性のみを返します。より多くの属性が必要な場合に、このフィールドを設定できます。このフィールドはオプションです。サポートされている値には以下があります。

ALL_ATTRIBUTES: 指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。
ALL_PROJECTED_ATTRIBUTES: インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は ALL_ATTRIBUTES を指定した場合と同等になります。

DynamoDB からの結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

結果は以下の構造を持ちます。


{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

各フィールドの定義は以下のようになります。

items: DynamoDB クエリで返された項目を含むリストです。
nextToken: さらに結果がある場合、nextToken には別のリクエストで使用できるページ分割トークンが含まれています。AWS AppSync は、DynamoDB から返されたページ分割トークンを暗号化および難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは、異なるリゾルバー間では使用できないことにも注意してください。
scannedCount: フィルタ式 (ある場合) が適用される前に、クエリの条件式に一致した項目の数です。

例

以下は、GraphQL クエリ getPosts(owner: ID!) のマッピングテンプレートです。

この例では、テーブルのグローバルセカンダリインデックスにクエリが実行され、指定した ID が所有するすべての投稿が返されます。


{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "ownerId = :ownerId",
        "expressionValues" : {
            ":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
        }
    }
    "index" : "owner-index"
}

DynamoDB Query API の詳細については、DynamoDB API のドキュメントを参照してください。

スキャン

Scan リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への Scan リクエストで、以下のように指定できます。

結果を除外するフィルタ
使用するインデックス
返す項目の数
整合性のある読み込みを使用するかどうか
ページ分割トークン
並列スキャン

Scan マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "index" : "fooIndex",
    "limit" : 10,
    "consistentRead" : false,
    "nextToken" : "aPaginationToken",
    "totalSegments" : 10,
    "segment" : 1,
    "filter" : {
        ...
    }
}

各フィールドの定義は以下のようになります。

version

テンプレート定義バージョン 2017-02-28 と 2018-05-29 は現在サポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。Scan DynamoDB の処理を実行するには、これを Scan に設定する必要があります。この値は必須です。

filter

DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「フィルタ」を参照してください。このフィールドはオプションです。

index

limit

一度に評価する項目の最大数です。このフィールドはオプションです。

consistentRead

nextToken

前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。

select

デフォルトでは、AWS AppSync DynamoDB のリゾルバーはインデックスに射影されるすべての属性のみを返します。より多くの属性が必要な場合にこのフィールドを設定します。このフィールドはオプションです。サポートされている値には以下があります。

ALL_ATTRIBUTES: 指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。
ALL_PROJECTED_ATTRIBUTES: インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は ALL_ATTRIBUTES を指定した場合と同等になります。

totalSegments

並列スキャンが実行されるまでにテーブルを分割するセグメントの数です。このフィールドはオプションですが、segment を指定した場合には指定する必要があります。

segment

並列スキャンの実行時のこの処理でのテーブルセグメントです。このフィールドはオプションですが、totalSegments を指定した場合には指定する必要があります。

DynamoDB スキャンにより返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

結果は以下の構造を持ちます。


{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

各フィールドの定義は以下のようになります。

items: DynamoDB スキャンにより返された項目を含むリストです。
nextToken: さらに結果がある場合、nextToken には別のリクエストで使用できるページ分割トークンが含まれています。AWS AppSync は、DynamoDB から返されたページ分割トークンを暗号化および難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なるリゾルバー間では使用できません。
scannedCount: フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。

例 1

以下は、GraphQL クエリ allPosts のマッピングテンプレートです。

この例では、テーブル内のすべてのエントリが返されます。


{
    "version" : "2017-02-28",
    "operation" : "Scan"
}

例 2

以下は、GraphQL クエリ postsMatching(title: String!) のマッピングテンプレートです。

この例では、タイトルが title 引数で始まるテーブル内のすべてのエントリが返されます。


{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "filter" : {
        "expression" : "begins_with(title, :title)",
        "expressionValues" : {
            ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
        },
    }
}

DynamoDB Scan API の詳細については、DynamoDB API のドキュメントを参照してください。

Sync

Sync リクエストマッピングドキュメントを使用すると、DynamoDB テーブルからすべての結果を取得し、最後のクエリ (差分更新) 以降に変更されたデータのみを受け取ることができます。Sync リクエストは、バージョン管理された DynamoDB データソースに対してのみ実行できます。以下を指定することができます。

結果を除外するフィルタ
返す項目の数
ページ分割トークン
最後の Sync オペレーションが開始された日時

Sync マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}

各フィールドの定義は以下のようになります。

version: テンプレート定義のバージョンです。現在、2018-05-29 のみがサポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。Sync の処理を実行するには、これは Sync に指定する必要があります。この値は必須です。
filter: DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「フィルタ」を参照してください。このフィールドはオプションです。
limit: 一度に評価する項目の最大数です。このフィールドはオプションです。省略した場合、デフォルトの制限は 100 項目に設定されます。このフィールドの最大値は 1000 項目です。
nextToken: 前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。
lastSync: 最後に成功した Sync オペレーションが開始されたエポックミリ秒単位の時刻。指定すると、lastSync 以降に変更された項目のみが返されます。このフィールドはオプションです。最初の Sync オペレーションからすべてのページを取得した後にのみ入力する必要があります。省略した場合は、ベーステーブルの結果が返されます。それ以外の場合は、差分テーブルの結果が返されます。

DynamoDB 同期により返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result) で参照できます。

DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。

レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

結果は以下の構造を持ちます。


{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10,
    startedAt = 1550000000000
}

各フィールドの定義は以下のようになります。

items: 同期により返された項目を含むリストです。
nextToken: さらに結果がある場合、nextToken には別のリクエストで使用できるページ分割トークンが含まれています。AWS AppSync は、DynamoDB から返されたページ分割トークンを暗号化および難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なるリゾルバー間では使用できません。
scannedCount: フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。
startedAt: エポックミリ秒単位の時刻ですが、同期オペレーションが開始されれば、ローカルに保存して別のリクエストで lastSync の引数として使用することができます。ページ分割トークンがリクエストに含まれている場合、この値は、結果の最初のページのリクエストによって返されたものと同じになります。

例 1

以下は、GraphQL クエリ syncPosts(nextToken: String, lastSync: AWSTimestamp) のマッピングテンプレートです。

この例では、lastSync を省略すると、ベーステーブルのすべてのエントリが返されます。lastSync が指定されている場合は、lastSync 以降に変更された差分同期テーブルのエントリのみが返されます。


{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit": 100,
    "nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
    "lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}

BatchGetItem

BatchGetItem リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB リゾルバーから DynamoDB への BatchGetItem リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。

項目を取得するテーブルの名前
各テーブルから取得する項目のキー

DynamoDB BatchGetItem の制限が適用されるため、条件式を指定することはできません。

BatchGetItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "BatchGetItem",
    "tables" : {
        "table1": {
           "keys": [
              ## Item to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item2 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        },
        "table2": {
           "keys": [
              ## Item3 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item4 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        }
    }
}

各フィールドの定義は以下のようになります。

version

テンプレート定義のバージョンです。2018-05-29 のみサポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。BatchGetItem DynamoDB の処理を実行するには、これに BatchGetItem を設定する必要があります。この値は必須です。

tables

項目を取得する DynamoDB テーブル。値は、キーとしてテーブル名が指定されているマップです。1 つ以上のテーブルを指定する必要があります。この tables の値は必須です。

keys: 取得する項目のプライマリキーを表す DynamoDB キーのリスト。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。
consistentRead: GetItem 処理の実行時に整合性のある読み込みを使用するかどうか。この値はオプションであり、デフォルトは false です。

覚えておくべきポイント:

項目がテーブルから取得されなかった場合は、そのテーブルの data ブロックに null 要素があります。
呼び出し結果は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
BatchGetItem 内の各 get コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは unprocessedKeys ブロック内に呼び出し結果の一部として返されます。
BatchGetItem は 100 キーに制限されています。

以下に示しているのは、リクエストマッピングテンプレートの例です。


{
  "version": "2018-05-29",
  "operation": "BatchGetItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

$ctx.result で使用可能な呼び出し結果は以下のとおりです。


{
   "data": {
     "authors": [null],
     "posts": [
        # Was retrieved
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title",
          "post_description": "description",
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error にエラーに関する詳細が含まれています。data キー、unprocessedKeys キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は data ブロックにあります。処理されなかった項目は、data ブロック内で null としてマークされ、unprocessedKeys ブロックに挿入されます。

より完全な例については、AppSync の DynamoDB Batch の「チュートリアル: DynamoDB Batch リゾルバー」を参照してください。

BatchDeleteItem

BatchDeleteItem リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB リゾルバーから DynamoDB への BatchWriteItem リクエストで、複数のテーブルから複数の項目を削除するように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。

項目を削除するテーブルの名前
各テーブルから削除する項目のキー

DynamoDB BatchWriteItem の制限が適用されるため、条件式を指定することはできません。

BatchDeleteItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "BatchDeleteItem",
    "tables" : {
        "table1": [
        ## Item to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

各フィールドの定義は以下のようになります。

version: テンプレート定義のバージョンです。2018-05-29 のみサポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。BatchDeleteItem DynamoDB の処理を実行するには、これを BatchDeleteItem に設定する必要があります。この値は必須です。
tables: 項目を削除する DynamoDB テーブル。各テーブルは、削除する項目のプライマリキーを表す DynamoDB キーのリストです。DynamoDB の項目には、テーブル構造に応じて、1 つのハッシュキーを含めるか、ハッシュキーとソートキーを含めることができます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。1 つ以上のテーブルを指定する必要があります。この tables の値は必須です。

覚えておくべきポイント:

DeleteItem オペレーションとは対照的に、完全に削除された項目はレスポンスで返されません。渡されたキーのみが返されます。
項目がテーブルから削除されなかった場合は、そのテーブルの data ブロックに null 要素があります。
呼び出し結果は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
BatchDeleteItem 内部の各 delete コマンドはアトミックです。ただし、バッチは部分的に処理できます。エラーのためにバッチが部分的に処理された場合、未処理のキーは unprocessedKeys ブロック内に呼び出し結果の一部として返されます。
BatchDeleteItem は 25 キーに制限されています。

以下に示しているのは、リクエストマッピングテンプレートの例です。


{
  "version": "2018-05-29",
  "operation": "BatchDeleteItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

$ctx.result で使用可能な呼び出し結果は以下のとおりです。


{
   "data": {
     "authors": [null],
     "posts": [
        # Was deleted
        {
          "author_id": "a1",
          "post_id": "p2"
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This key was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error にエラーに関する詳細が含まれています。data キー、unprocessedKeys キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は data ブロックにあります。処理されなかった項目は、data ブロック内で null としてマークされ、unprocessedKeys ブロックに挿入されます。

より完全な例については、AppSync の DynamoDB Batch の「チュートリアル: DynamoDB Batch リゾルバー」を参照してください。

BatchPutItem

BatchPutItem リクエストマッピングドキュメントをしようすると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への BatchWriteItem リクエストで、複数のテーブルに複数の項目を挿入するように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。

項目を挿入するテーブルの名前
各テーブルに挿入するすべての項目

DynamoDB BatchWriteItem の制限が適用されるため、条件式を指定することはできません。

BatchPutItem マッピングドキュメントの構造は次のとおりです。


{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        "table1": [
        ## Item to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

各フィールドの定義は以下のようになります。

version: テンプレート定義のバージョンです。2018-05-29 のみサポートされています。この値は必須です。
operation: 実行する DynamoDB の処理です。BatchPutItem DynamoDB の処理を実行するには、これを BatchPutItem に設定する必要があります。この値は必須です。
tables: 項目を挿入する DynamoDB テーブル。各テーブルエントリは、この特定のテーブルに挿入する DynamoDB 項目のリストを表します。1 つ以上のテーブルを指定する必要があります。この値は必須です。

覚えておくべきポイント:

完全に挿入された項目がレスポンスに返されます (正常に挿入された場合)。
項目がテーブルに挿入されなかった場合は、そのテーブルの data ブロックに null 要素があります。
挿入された項目は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
BatchPutItem 内の各 put コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは unprocessedKeys ブロック内に呼び出し結果の一部として返されます。
BatchPutItem は 25 項目に制限されています。

以下に示しているのは、リクエストマッピングテンプレートの例です。


{
  "version": "2018-05-29",
  "operation": "BatchPutItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          },
          "author_name": {
            "S": "a1_name"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          },
          "post_title": {
            "S": "title"
          }
        }
    ],
  }
}

$ctx.result で使用可能な呼び出し結果は以下のとおりです。


{
   "data": {
     "authors": [
         null
     ],
     "posts": [
        # Was inserted
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title"
        }
     ]
   },
   "unprocessedItems": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1",
          "author_name": "a1_name"
        }
      ],
     "posts": []
   }
}

$ctx.error にエラーに関する詳細が含まれています。data キー、The keys data, unprocessedItems キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。挿入された項目は data ブロックにあります。処理されなかった項目は、data ブロック内で null としてマークされ、unprocessedItems ブロックに挿入されます。

より完全な例については、AppSync の DynamoDB Batch の「チュートリアル: DynamoDB Batch リゾルバー」を参照してください。

TransactGetItems

TransactGetItems リクエストマッピングドキュメントを使用すると、AWS AppSync DynamoDB リゾルバーから DynamoDB への TransactGetItems リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。

項目の取得元となる各リクエスト項目のテーブル名
各テーブルから取得する各リクエスト項目のキー

DynamoDB の TransactGetItems 制限が適用されるため、条件式を指定することはできません。

TransactGetItems マッピングドキュメントの構造は次のとおりです。


{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "table1",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       },
       ## Second request item
       {
           "table": "table2",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       }
    ]
}

各フィールドの定義は以下のようになります。

version

テンプレート定義のバージョンです。2018-05-29 のみサポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。TransactGetItems DynamoDB の処理を実行するには、これを TransactGetItems に設定する必要があります。この値は必須です。

transactItems

含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この transactItems の値は必須です。

table: 項目の取得元となる DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
key: 取得する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。

覚えておくべきポイント:

トランザクションが成功すると、items ブロック内で取得された項目の順序はリクエスト項目の順序と同じになります。
トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。
リクエスト項目を取得できなくても、エラーではありません。代わりに、対応する位置の items ブロックに null 要素が表示されます。
トランザクションのエラーが TransactionCanceledException である場合、cancellationReasons ブロックに入力されます。cancellationReasons ブロック内のキャンセル理由の順序は、リクエスト項目の順序と同じになります。
TransactGetItems のリクエスト項目数は 25 個に制限されています。

以下に示しているのは、リクエストマッピングテンプレートの例です。


{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "posts",
           "key": {
               "post_id": {
                 "S": "p1"
               }
           }
       },
       ## Second request item
       {
           "table": "authors",
           "key": {
               "author_id": {
                 "S": a1
               }
           }
       }
    ]
}

トランザクションが成功し、最初にリクエストされた項目だけが取得された場合、$ctx.result で使用できる呼び出し結果は次のようになります。


{
    "items": [
       {
           // Attributes of the first requested item
           "post_id": "p1",
           "post_title": "title",
           "post_description": "description"
       },
       // Could not retrieve the second requested item
       null,
    ],
    "cancellationReasons": null
}

最初のリクエスト項目によって発生した TransactionCanceledException が原因でトランザクションが失敗した場合、$ctx.result で使用可能な呼び出し結果は次のようになります。


{
    "items": null,
    "cancellationReasons": [
       {
           "type":"Sample error type",
           "message":"Sample error message"
       },
       {
           "type":"None",
           "message":"None"
       }
    ]
}

$ctx.error にエラーに関する詳細が含まれています。キー items と cancellationReasons は、$ctx.result にあることが保証されています。

より完全な例については、AppSync を使用した DynamoDB トランザクションのチュートリアル「チュートリアル: DynamoDB Transaction リゾルバー」を参照してください。

TransactWriteItems

TransactWriteItems リクエストマッピングドキュメントをしようすると、AWS AppSync DynamoDB のリゾルバーから DynamoDB への TransactWriteItems リクエストで、複数のテーブルに複数の項目を書き込むように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。

各リクエスト項目の書き込み先テーブル名
実行する各リクエスト項目のオペレーション。サポートされているオペレーションには、PutItem、UpdateItem、DeleteItem、および ConditionCheck の 4 種類があります。
書き込む各リクエスト項目のキー

DynamoDB の TransactWriteItems 制限が適用されます。

TransactWriteItems マッピングドキュメントの構造は次のとおりです。


{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "table1",
           "operation": "PutItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "attributeValues": {
               "baz": ... typed value
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table":"table2",
           "operation": "UpdateItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "update": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               }
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo":"foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table3",
           "operation": "DeleteItem",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table4",
           "operation": "ConditionCheck",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       }
    ]
}

各フィールドの定義は以下のようになります。

version

テンプレート定義のバージョンです。2018-05-29 のみサポートされています。この値は必須です。

operation

実行する DynamoDB の処理です。TransactWriteItems DynamoDB の処理を実行するには、これを TransactWriteItems に設定する必要があります。この値は必須です。

transactItems

PutItem の場合、各フィールドの定義は以下のようになります。

table: 書き込み先の DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
operation: 実行する DynamoDB の処理です。PutItem DynamoDB の処理を実行するには、これを PutItem に設定する必要があります。この値は必須です。
key: 配置する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
attributeValues: DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、PutItem リクエストはその項目の既存のエントリを上書きします。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。

UpdateItem の場合、各フィールドの定義は以下のようになります。

table: 更新する DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
operation: 実行する DynamoDB の処理です。UpdateItem DynamoDB の処理を実行するには、これを UpdateItem に設定する必要があります。この値は必須です。
key: 更新する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
update: update セクションには、DynamoDB の項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、DynamoDB UpdateExpressions のドキュメントを参照してください。このセクションは必須です。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、UpdateItem リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。

DeleteItem の場合、各フィールドの定義は以下のようになります。

table: 項目を削除する DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
operation: 実行する DynamoDB の処理です。DeleteItem DynamoDB の処理を実行するには、これを DeleteItem に設定する必要があります。この値は必須です。
key: 削除する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、DeleteItem リクエストによって、現在の状態にかかわらず、項目が削除されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。

ConditionCheck の場合、各フィールドの定義は以下のようになります。

table: 条件をチェックする DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
operation: 実行する DynamoDB の処理です。ConditionCheck DynamoDB の処理を実行するには、これを ConditionCheck に設定する必要があります。この値は必須です。
key: 条件をチェックする項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目にはテーブルの構造に応じて、1 つのハッシュキーが含まれるか、ハッシュキーとソートキーが含まれます。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値は必須です。

覚えておくべきポイント:

リクエスト項目のキーのみがレスポンスに返されます (正常に挿入された場合)。キーの順序は、リクエスト項目の順序と同じです。
トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。
同じ項目をターゲットにできるリクエスト項目が 2 つありません。それ以外の場合は、TransactionCanceledException エラーが発生します。
トランザクションのエラーが TransactionCanceledException である場合、cancellationReasons ブロックに入力されます。リクエスト項目の条件チェックが失敗し、かつ returnValuesOnConditionCheckFailure を false に指定しなかった場合、テーブルに存在する項目が取得され、item で cancellationReasons ブロックの対応する位置に保存されます。
TransactWriteItems のリクエスト項目数は 25 個に制限されています。

以下に示しているのは、リクエストマッピングテンプレートの例です。


{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "posts",
           "operation": "PutItem",
           "key": {
               "post_id": {
                   "S": "p1"
               }
           },
           "attributeValues": {
               "post_title": {
                   "S": "New title"
               },
               "post_description": {
                   "S": "New description"
               }
           },
           "condition": {
               "expression": "post_title = :post_title",
               "expressionValues": {
                   ":post_title": {
                       "S": "Expected old title"
                   }
               }
           }
       },
       {
           "table":"authors",
           "operation": "UpdateItem",
           "key": {
               "author_id": {
                   "S": "a1"
               },
           },
           "update": {
               "expression": "SET author_name = :author_name",
               "expressionValues": {
                   ":author_name": {
                       "S": "New name"
                   }
               }
           },
       }
    ]
}

トランザクションが成功した場合、$ctx.result で使用できる呼び出し結果は次のようになります。


{
    "keys": [
       // Key of the PutItem request
       {
           "post_id": "p1",
       },
       // Key of the UpdateItem request
       {
           "author_id": "a1"
       }
    ],
    "cancellationReasons": null
}

PutItem リクエストの条件チェックに失敗したためにトランザクションが失敗した場合、$ctx.result で使用できる呼び出し結果は次のようになります。


{
    "keys": null,
    "cancellationReasons": [
       {
           "item": {
               "post_id": "p1",
               "post_title": "Actual old title",
               "post_description": "Old description"
           },
           "type": "ConditionCheckFailed",
           "message": "The condition check failed."
       },
       {
           "type": "None",
           "message": "None"
       }
    ]
}

$ctx.error にエラーに関する詳細が含まれています。keys および cancellationReasons が $ctx.result に存在することが保証されています。

型システム (リクエストマッピング)

AWS AppSync DynamoDB のリゾルバーを使用して DynamoDB テーブルを呼び出す場合、AWS AppSync はその呼び出しで使用するそれぞれの値の型を知っている必要があります。これは、DynamoDB が GraphQL や JSON よりも多くの型プリミティブをサポートしているためです (セットやバイナリデータなど)。GraphQL と DynamoDB 間で変換を行う場合、AWS AppSync には何らかの情報が必要であり、これがない場合には、テーブルでのデータ構造について前提条件を作成する必要があります。

DynamoDB のデータ型の詳細については、DynamoDB の「データ型記述子」および「データ型」の各ドキュメントを参照してください。

DynamoDB の値は、単一のキーと値のペアを含む JSON オブジェクトで表されます。キーは DynamoDB の型を指定し、値はその値自身を指定します。次の例では、キー S は値が文字列であることを示し、値 identifier がその文字列値です。


{ "S" : "identifier" }

JSON オブジェクトは複数のキーと値のペアを持つことはできません。複数のキーと値のペアが指定されている場合、リクエストマッピングドキュメントは解析されません。

DynamoDB の値は、値を指定する必要がある場合にはリクエストマッピングドキュメントのどこかで使用されます。これが必要になる箇所には、key セクションと attributeValue セクション、および式セクションの expressionValues セクションが含まれています。次の例では、DynamoDB の文字列値 identifier が、(おそらくは GetItem リクエストマッピングドキュメントの) key セクションの id フィールドに割り当てられています。


"key" : {
   "id" : { "S" : "identifier" }
}

サポートされているタイプ

AWS AppSync では、以下の DynamoDB スカラー、ドキュメント、およびセット型をサポートしています。

文字列型 S

単一の文字列値です。DynamoDB の文字列値は次のように表されます。


{ "S" : "some string" }

以下は使用例です。


"key" : {
   "id" : { "S" : "some string" }
}

文字列セット型 SS

1 組の文字列値です。DynamoDB の文字列セット値は次のように表されます。


{ "SS" : [ "first value", "second value", ... ] }

以下は使用例です。


"attributeValues" : {
   "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] }
}

数値型 N

単一の数値です。DynamoDB の数値は次のように表されます。


{ "N" : 1234 }

以下は使用例です。


"expressionValues" : {
   ":expectedVersion" : { "N" : 1 }
}

数値セット型 NS

1 組の数値です。DynamoDB の数値セット値は次のように表されます。


{ "NS" : [ 1, 2.3, 4 ... ] }

以下は使用例です。


"attributeValues" : {
   "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] }
}

バイナリ型 B

バイナリ値です。DynamoDB のバイナリ値は次のように表されます。


{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

値は実際には文字列です。この文字列は、バイナリデータを Base64 でエンコードして表したものです。AWS AppSync では、この文字列をバイナリ値にデコードしてから DynamoDB に送信します。AWS AppSync は、RFC 2045 で定義された Base64 デコーディングスキームを使用します。Base64 のアルファベットにない文字は無視されます。

以下は使用例です。


"attributeValues" : {
   "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" }
}

バイナリセット型 BS

1 組のバイナリ値です。DynamoDB のバイナリセット値は次のように表されます。


{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

以下は使用例です。


"attributeValues" : {
   "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] }
}

ブール型 BOOL

ブール値。DynamoDB のブール値は次のように表されます。


{ "BOOL" : true }

有効な値は、true と false のみです。

以下は使用例です。


"attributeValues" : {
   "orderComplete" : { "BOOL" : false }
}

リスト型 L

サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は次のように表されます。


{ "L" : [ ... ] }

この値は複合値です。リストには、サポートされる DynamoDB の値 (他のリストも含む) が 0 個以上入ります。このリストには、異なる型を混在させることもできます。

以下は使用例です。


{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}

マップ型 M

サポートされる他の DynamoDB の値の、キーと値のペアの順序付けされていない集合を表します。DynamoDB のマップ値は次のように表されます。


{ "M" : { ... } }

マップには 0 個以上のキーと値のペアが入ります。キーは文字列である必要があり、値には、サポートされている DynamoDB の任意の値 (他のマップを含む) が使用できます。このマップには、異なる型を混在させることもできます。

以下は使用例です。


{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}

Null 型 NULL

null 値です。DynamoDB の Null 値は次のように表されます。


{ "NULL" : null }

以下は使用例です。


"attributeValues" : {
   "phoneNumbers" : { "NULL" : null }
}

各タイプの詳細については、DynamoDB のドキュメントを参照してください。

型システム (レスポンスマッピング)

DynamoDB からレスポンスを受信すると、AWS AppSync はこれを自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換します。DynamoDB の各属性はデコードされ、レスポンスマッピングコンテキストで返されます。

たとえば、DynamoDB が以下を返したとします。


{
    "id" : { "S" : "1234" },
    "name" : { "S" : "Nadia" },
    "age" : { "N" : 25 }
}

AWS AppSync DynamoDB のリゾルバーはこれを以下のように GraphQL 型と JSON 型に変換します。


{
    "id" : "1234",
    "name" : "Nadia",
    "age" : 25
}

このセクションでは、AWS AppSync が以下の DynamoDB スカラー型、ドキュメント型、およびセット型を変換する方法について説明します。

文字列型 S

単一の文字列値です。DynamoDB 文字列値が文字列として返されます。

たとえば、DynamoDB が次の DynamoDB の文字列値を返したとします。


{ "S" : "some string" }

AWS AppSync はそれを文字列に変換します。


"some string"

文字列セット型 SS

1 組の文字列値です。DynamoDB 文字列セット値が文字列のリストとして返されます。

たとえば、DynamoDB が次の DynamoDB 文字列セット値を返したとします。


{ "SS" : [ "first value", "second value", ... ] }

AWS AppSync はそれを文字列のリストに変換します。


[ "+1 555 123 4567", "+1 555 234 5678" ]

数値型 N

単一の数値です。DynamoDB 数値が数字として返されます。

たとえば、DynamoDB が次の DynamoDB の数値を返したとします。


{ "N" : 1234 }

AWS AppSync はそれを数字に変換します。

数値セット型 NS

1 組の数値です。DynamoDB 数値セットが数字のリストとして返されます。

たとえば、DynamoDB が次の DynamoDB の数値セット値を返したとします。


{ "NS" : [ 67.8, 12.2, 70 ] }

AWS AppSync はそれを数字のリストに変換します。


[ 67.8, 12.2, 70 ]

バイナリ型 B

バイナリ値です。DynamoDB のバイナリ値は、その値を Base64 で表した文字列として返されます。

たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。


{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

AWS AppSync はこの値を Base64 で表した文字列に変換します。


"SGVsbG8sIFdvcmxkIQo="

バイナリデータは、RFC 4648 と RFC 2045 で指定されているようにして Base64 エンコーディングスキームにエンコードされます。

バイナリセット型 BS

1 組のバイナリ値です。DynamoDB のバイナリセット値は、その値を Base64 で表した文字列のリストとして返されます。

たとえば、DynamoDB が次の DynamoDB のバイナリセット値を返したとします。


{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }

AWS AppSync はこの値を Base64 で表した文字列のリストに変換します。


[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]

バイナリデータは、RFC 4648 と RFC 2045 で指定されているようにして Base64 エンコーディングスキームにエンコードされます。

ブール型 BOOL

ブール値。DynamoDB ブール値がブールとして返されます。

たとえば、DynamoDB が次の DynamoDB のブール値を返したとします。


{ "BOOL" : true }

AWS AppSync はそれをブールに変換します。


true

リスト型 L

サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は値のリストとして返され、内部のそれぞれの値も変換されます。

たとえば、DynamoDB が次の DynamoDB のリスト値を返したとします。


{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}

AWS AppSync はそれを変換された値のリストに変換します。


[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]

マップ型 M

サポートされるその他の DynamoDB の値のキー/値の集合です。DynamoDB のマップ値は JSON オブジェクトとして返されます。それぞれのキー/値も変換されます。

たとえば、DynamoDB が次の DynamoDB のマップ値を返したとします。


{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}

AWS AppSync はそれを JSON オブジェクトに変換します。


{
   "someString" : "A string value",
   "someNumber" : 1,
   "stringSet"  : [ "Another string value", "Even more string values!" ]
}

Null 型 NULL

null 値です。

たとえば、DynamoDB が次の DynamoDB の Null 値を返したとします。


{ "NULL" : null }

AWS AppSync はそれを null に変換します。


null

フィルタ

Query 処理と Scan 処理を使用して DynamoDB のオブジェクトにクエリを実行する場合、オプションで、結果を評価する filter を指定して、必要な値のみを返すことができます。

Query または Scan マッピングドキュメントのフィルタマッピングセクションは以下の構造を持ちます。


"filter" : {
    "expression" : "filter expression"
    "expressionNames" : {
        "#name" : "name",
    },
    "expressionValues" : {
        ":value" : ... typed value
    },
}

各フィールドの定義は以下のようになります。

expression: クエリ式です。フィルタ式の記述方法の詳細については、「DynamoDB QueryFilter」および「DynamoDB ScanFilter」の各ドキュメントを参照してください。このフィールドの指定は必須です。
expressionNames: 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは、expression で使用される名前のプレースホルダーに対応します。値は、DynamoDB の項目の属性名に対応する文字列である必要があります。このフィールドはオプションであり、expression で使用される式の属性名のプレースホルダーのみを入力します。
expressionValues: 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。

例

以下は、マッピングテンプレートのフィルターセクションです。ここでは、DynamoDB から取得されたエントリのうち、タイトルが title 引数で始まるもののみが返されます。


"filter" : {
    "expression" : "begins_with(#title, :title)",
    "expressionNames" : {
        "#title" : "title"
    }
    "expressionValues" : {
        ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
    }
}

条件式

PutItem、UpdateItem、および DeleteItem の各 DynamoDB 処理を使用して DynamoDB のオブジェクトをミューテーションする場合、オプションで、処理を実行する前に、DynamoDB にある既存のオブジェクトの状態に基づいてリクエストが成功するかどうかを制御する条件式を指定することができます。

AWS AppSync DynamoDB のリゾルバーを使用して、PutItem、UpdateItem、および DeleteItem の各リクエストマッピングドキュメントに条件式を指定することができます。また、条件チェックでエラーが検出され、オブジェクトが更新されなかった場合に従う処理も指定できます。

例 1

以下の PutItem マッピングドキュメントには条件式がありません。その結果、同じキーに対応する項目がすでにある場合でも、項目は DynamoDB に挿入され、それにより既存の項目が上書きされます。


{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   }
}

例 2

以下の PutItem マッピングドキュメントには条件式があります。この条件式では、同じキーの項目が DynamoDB に存在しない場合にのみ、処理は成功として扱われます。


{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   },
   "condition" : {
      "expression" : "attribute_not_exists(id)"
   }
}

デフォルトでは、条件チェックでエラーが検出されると、AWS AppSync DynamoDB のリゾルバーは、ミューテーションに関するエラーを返すとともに、GraphQL レスポンスの error セクションの data フィールドで DynamoDB のオブジェクトの現在値を返します。ただし、AWS AppSync DynamoDB のリゾルバーにより追加の機能を提供して、一般的なエッジケースを開発者が処理することもできます。

AWS AppSync DynamoDB のリゾルバーにより、DynamoDB の現在値が必要な結果と一致すると判断できる場合、処理は成功として扱われます。
エラーを返す代わりに、リゾルバーを設定してカスタムの Lambda 関数を呼び出し、AWS AppSync DynamoDB のリゾルバーがエラーを処理する方法を決定することができます。

これらの詳細については、「条件チェックでのエラーを処理する」セクションを参照してください。

DynamoDB の条件式の詳細については、DynamoDB ConditionExpressions のドキュメントを参照してください。

条件を指定する

PutItem、UpdateItem、および DeleteItem の各リクエストマッピングドキュメントはすべて、オプションで condition セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。

condition セクションは以下の構造を持ちます。


"condition" : {
    "expression" : "someExpression"
    "expressionNames" : {
        "#foo" : "foo"
    },
    "expressionValues" : {
        ":bar" : ... typed value
    },
    "equalsIgnore" : [ "version" ],
    "consistentRead" : true,
    "conditionalCheckFailedHandler" : {
        "strategy" : "Custom",
        "lambdaArn" : "arn:..."
    }
}

以下のフィールドに条件を指定します。

expression: 更新式そのものを指定します。条件式の記述方法の詳細については、DynamoDB ConditionExpressions のドキュメントを参照してください。このフィールドの指定は必須です。
expressionNames: 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、expression で使用される式の属性名のプレースホルダーのみを入力します。
expressionValues: 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。

残りのフィールドは、AWS AppSync DynamoDB のリゾルバーに条件チェックで検出したエラーを処理する方法を指示します。

equalsIgnore

PutItem 処理の使用時に条件チェックでエラーが検出された場合、AWS AppSync DynamoDB のリゾルバーは DynamoDB に現在ある項目と、書き込もうとした項目とを比較します。これらが同じ場合、処理は成功として扱われます。equalsIgnore フィールドを使用して、AWS AppSync がこの比較を実行する際に無視する属性のリストを指定することができます。たとえば、唯一の違いが version 属性である場合、処理は成功として扱われます。このフィールドはオプションです。

consistentRead

条件チェックでエラーが検出された場合、AWS AppSync は強力な整合性のある読み込みを使用して DynamoDB から項目の現在の値を取得します。このフィールドを使用して、結果整合性のある読み込みを代わりに使用するよう AWS AppSync DynamoDB のリゾルバーに指示することができます。このフィールドはオプションであり、デフォルトは true です。

conditionalCheckFailedHandler

このセクションでは、AWS AppSync DynamoDB のリゾルバーが DynamoDB の現在値と期待値を比較した後、条件チェックでエラーが検出された場合に、これを処理する方法を指定することができます。このセクションはオプションです。省略した場合、デフォルトの処理は Reject です。

strategy

AWS AppSync DynamoDB のリゾルバーが DynamoDB の現在値と期待値を比較した後に行う処理です。このフィールドは必須であり、以下を値を設定できます。

Reject: このミューテーションは失敗し、ミューテーションに関するエラーが返されます。また、DynamoDB のオブジェクトの現在値が GraphQL レスポンスの error セクションの data フィールドで返されます。
Custom: AWS AppSync DynamoDB のリゾルバーはカスタムの Lambda 関数を呼び出して、条件チェックで検出したエラーの処理方法を決定します。strategy が Custom に設定されている場合、lambdaArn フィールドには、呼び出す Lambda 関数の ARN が含まれている必要があります。

lambdaArn

AWS AppSync DynamoDB のリゾルバーが、条件チェックで検出されたエラーを処理する方法を決定するために呼び出す Lambda 関数の ARN です。このフィールドは、strategy が Custom に設定されている場合のみ指定する必要があります。この機能の使用方法の詳細については、「条件チェックでのエラーを処理する」を参照してください。

条件チェックでのエラーを処理する

AWS AppSync DynamoDB のリゾルバーにより、DynamoDB の現在値が必要な結果と一致すると判断できる場合、処理は成功として扱われます。
エラーを返す代わりに、リゾルバーを設定してカスタムの Lambda 関数を呼び出し、AWS AppSync DynamoDB のリゾルバーがエラーを処理する方法を決定することができます。

このプロセスのフローチャートは次のとおりです。

必要な結果をチェックする

条件チェックでエラーが検出された場合、AWS AppSync DynamoDB のリゾルバーは GetItem DynamoDB リクエストを実行し、DynamoDB から項目の現在値を取得します。デフォルトでは、強力な整合性のある読み込みを使用しますが、condition ブロックの consistentRead フィールドを使用してこれを設定し、この値を期待した結果と比較することができます。

PutItem 処理では、AWS AppSync DynamoDB のリゾルバーは、equalsIgnore にリストされた以外の属性について、現在値と書き込もうとした値を比較します。項目が同じ場合は、処理は成功として扱われ、DynamoDB から取得された項目が返されます。それ以外の場合は、設定された処理に従います。

たとえば、PutItem リクエストマッピングドキュメントが以下のようになっているとします。
```
{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   },
   "attributeValues" : {
      "name" : { "S" : "Steve" },
      "version" : { "N" : 2 }
   },
   "condition" : {
      "expression" : "version = :expectedVersion",
      "expressionValues" : {
          ":expectedVersion" : { "N" : 1 }
      },
      "equalsIgnore": [ "version" ]
   }
}
```
現在、DynamoDB にある項目は以下のようになりました。
```
{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}
```
この場合、AWS AppSync DynamoDB のリゾルバーは書き込もうとした項目を現在の値と比較し、version フィールドのみ異なっていることを検出します。ただし、version フィールドは無視するよう設定されているため、処理は成功として扱われ、DynamoDB から取得された項目が返されます。
DeleteItem 処理では、AWS AppSync DynamoDB のリゾルバーは項目が DynamoDB から返されたことを確認します。項目が返されなかった場合、処理は成功として扱われます。それ以外の場合は、設定された処理に従います。
UpdateItem 処理では、AWS AppSync DynamoDB のリゾルバーには、DynamoDB に現在ある項目が期待した結果と一致するかどうかを判定するための十分な情報がないため、設定された処理に従います。

DynamoDB のオブジェクトの現在の状態が期待した結果と異なる場合、AWS AppSync DynamoDB のリゾルバーは設定された処理に従い、ミューテーションを拒否するか、Lambda 関数を呼び出して次の処理を決定します。

「拒否」処理に従う

Reject の処理に従う場合、AWS AppSync DynamoDB のリゾルバーは、ミューテーションに関するエラーを返すとともに、GraphQL レスポンスの error セクションの data フィールドで DynamoDB のオブジェクトの現在値を返します。DynamoDB から返された項目がレスポンスマッピングテンプレートにより入力され、クライアントが期待する形式に変換されます。また、選択設定によりフィルタ処理も行われます。

たとえば、次のミューテーションリクエストが指定されたとします。


mutation {
    updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
        Name
        theVersion
    }
}

DynamoDB から返された項目が以下のようになっているとします。


{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}

また、レスポンスマッピングテンプレートは以下のようになっているとします。


{
   "id" : $util.toJson($context.result.id),
   "Name" : $util.toJson($context.result.name),
   "theVersion" : $util.toJson($context.result.version)
}

GraphQL レスポンスは以下のようになります。


{
  "data": null,
  "errors": [
    {
      "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      "data": {
        "Name": "Steve",
        "theVersion": 8
      },
      ...
    }
  ]
}

また、返されたオブジェクトのフィールドすべてが他のリゾルバーによって入力され、そのミューテーションが成功した場合、オブジェクトが error セクションに返されたときに、それらのフィールドは解決されません。

「カスタム」処理に従う

Custom 処理に従う場合、AWS AppSync DynamoDB のリゾルバーは Lambda 関数を呼び出して、以下の処理を決定します。Lambda 関数は以下のオプションのいずれかを選択します。

reject ミューテーションです。これを指定すると、AWS AppSync DynamoDB のリゾルバーは設定された処理が Reject されたものとして処理し、前のセクションで説明したように、ミューテーションに関するエラーと DynamoDB のオブジェクトの現在値を返します。
discard ミューテーションです。これを指定すると、AWS AppSync DynamoDB のリゾルバーは条件チェックで検出されたエラーを通知することなく無視し、DynamoDB の値を返します。
retry ミューテーションです。これを指定すると、AWS AppSync DynamoDB のリゾルバーは新しいリクエストマッピングドキュメントを使用してミューテーションを再試行します。

Lambda 呼び出しリクエスト

AWS AppSync DynamoDB のリゾルバーは、lambdaArn で指定された Lambda 関数を呼び出します。また、データソースに設定されたものと同じ service-role-arn を使用します。呼び出しのペイロードは以下の構造を持ちます。


{
    "arguments": { ... },
    "requestMapping": {... },
    "currentValue": { ... },
    "resolver": { ... },
    "identity": { ... }
}

各フィールドの定義は以下のようになります。

arguments: GraphQL ミューテーションの引数です。これは、$context.arguments のリクエストマッピングドキュメントで使用できる引数と同じです。
requestMapping: この処理のリクエストマッピングドキュメントです。
currentValue: DynamoDB のオブジェクトの現在値です。
resolver: AWS AppSync のリゾルバーに関する情報です。
identity: 呼び出し元に関する情報です。これは、$context.identity のリクエストマッピングドキュメントで使用できる識別情報と同じです。

完全なペイロードの例を次に示します。


{
    "arguments": {
        "id": "1",
        "name": "Steve",
        "expectedVersion": 1
    },
    "requestMapping": {
        "version" : "2017-02-28",
        "operation" : "PutItem",
        "key" : {
           "id" : { "S" : "1" }
        },
        "attributeValues" : {
           "name" : { "S" : "Steve" },
           "version" : { "N" : 2 }
        },
        "condition" : {
           "expression" : "version = :expectedVersion",
           "expressionValues" : {
               ":expectedVersion" : { "N" : 1 }
           },
           "equalsIgnore": [ "version" ]
        }
    },
    "currentValue": {
        "id" : { "S" : "1" },
        "name" : { "S" : "Steve" },
        "version" : { "N" : 8 }
    },
    "resolver": {
        "tableName": "People",
        "awsRegion": "us-west-2",
        "parentType": "Mutation",
        "field": "updatePerson",
        "outputType": "Person"
    },
    "identity": {
        "accountId": "123456789012",
        "sourceIp": "x.x.x.x",
        "user": "AIDAAAAAAAAAAAAAAAAAA",
        "userArn": "arn:aws:iam::123456789012:user/appsync"
    }
}

Lambda 呼び出しレスポンス

Lambda 関数は、呼び出しペイロードを確認し、任意のビジネスロジックを適用して、AWS AppSync DynamoDB のリゾルバーがエラーを処理する方法を決定することができます。条件チェックで検出されたエラーを処理するために、以下の 3 つのオプションが指定できます。

reject ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "reject"
}
```
これを指定すると、AWS AppSync DynamoDB のリゾルバーは設定された処理が Reject されたものとして処理し、上記のセクションで説明したように、ミューテーションに関するエラーと DynamoDB のオブジェクトの現在値を返します。
discard ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "discard"
}
```
これを指定すると、AWS AppSync DynamoDB のリゾルバーは条件チェックで検出されたエラーを通知することなく無視し、DynamoDB の値を返します。
retry ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "retry",
    "retryMapping": { ... }
}
```
これを指定すると、AWS AppSync DynamoDB のリゾルバーは新しいリクエストマッピングドキュメントを使用してミューテーションを再試行します。retryMapping セクションの構造は DynamoDB の処理によって異なり、その処理の完全なリクエストマッピングドキュメントのサブセットとなります。

PutItem の場合、retryMapping セクションは次の構造を持ちます。attributeValues フィールドについては、「PutItem」を参照してください。
```
{
    "attributeValues": { ... },
    "condition": {
        "equalsIgnore" = [ ... ],
        "consistentRead" = true
    }
}
```
UpdateItem の場合、retryMapping セクションは次の構造を持ちます。update セクションについては、「UpdateItem」を参照してください。
```
{
    "update" : {
        "expression" : "someExpression"
        "expressionNames" : {
            "#foo" : "foo"
        },
        "expressionValues" : {
            ":bar" : ... typed value
        }
    },
    "condition": {
        "consistentRead" = true
    }
}
```
DeleteItem の場合、retryMapping セクションは次の構造を持ちます。
```
{
    "condition": {
        "consistentRead" = true
    }
}
```
使用する別の処理やキーを指定する方法はありません。AWS AppSync DynamoDB のリゾルバーは、同じオブジェクトに対する同じ処理の再試行のみが可能です。また、condition セクションでは conditionalCheckFailedHandler は指定できません。再試行が失敗した場合、AWS AppSync DynamoDB のリゾルバーは Reject の処理に従います。

以下は、失敗した PutItem リクエストを処理する Lambda 関数の例です。ビジネスロジックは呼び出し元を調べます。呼び出し元が jeffTheAdmin の場合は、リクエストを再試行して、現在 DynamoDB にある項目の version と expectedVersion を更新します。それ以外の場合は、ミューテーションを拒否します。


exports.handler = (event, context, callback) => {
    console.log("Event: "+ JSON.stringify(event));

    // Business logic goes here.

    var response;
    if ( event.identity.user == "jeffTheAdmin" ) {
        response = {
            "action" : "retry",
            "retryMapping" : {
                "attributeValues" : event.requestMapping.attributeValues,
                "condition" : {
                    "expression" : event.requestMapping.condition.expression,
                    "expressionValues" : event.requestMapping.condition.expressionValues
                }
            }
        }
        response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
        response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version

    } else {
        response = { "action" : "reject" }
    }

    console.log("Response: "+ JSON.stringify(response))
    callback(null, response)
};

トランザクション条件式

トランザクション条件式は、TransactWriteItems の 4 つのタイプのオペレーション (PutItem、DeleteItem、UpdateItem、ConditionCheck) すべてに対応するリクエストマッピングテンプレートで使用できます。

PutItem、DeleteItem、および UpdateItem の場合、トランザクション条件式はオプションです。ConditionCheck の場合、トランザクション条件式が必要です。

例 1

次のトランザクション DeleteItem マッピングドキュメントには条件式がありません。その結果、DynamoDB の項目が削除されます。


{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
      }
   ]
}

例 2

次のトランザクション DeleteItem マッピングドキュメントには、その投稿の作成者が特定の名前に等しい場合にのみオペレーションが成功できるトランザクション条件式があります。


{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
         "condition": {
            "expression": "author = :author",
            "expressionValues": {
               ":author": { "S" : "Chunyan" }
            }
         }
      }
   ]
}

条件チェックが失敗すると、TransactionCanceledException が発生し、エラーの詳細が $ctx.result.cancellationReasons で返されます。デフォルトでは、その条件チェックの失敗となった DynamoDB の古い項目は $ctx.result.cancellationReasons で返されます。

条件を指定する

PutItem、UpdateItem、および DeleteItem の各リクエストマッピングドキュメントはすべて、オプションで condition セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。ConditionCheck では、condition セクションを指定する必要があります。トランザクション全体が成功するためには、条件が true でなければなりません。

condition セクションは以下の構造を持ちます。


"condition": {
    "expression": "someExpression",
    "expressionNames": {
        "#foo": "foo"
    },
    "expressionValues": {
        ":bar": ... typed value
    },
    "returnValuesOnConditionCheckFailure": false
}

以下のフィールドに条件を指定します。

expression: 更新式そのものを指定します。条件式の記述方法の詳細については、DynamoDB ConditionExpressions のドキュメントを参照してください。このフィールドの指定は必須です。
expressionNames: 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、expression で使用される式の属性名のプレースホルダーのみを入力します。
expressionValues: 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。
returnValuesOnConditionCheckFailure: 条件チェックが失敗した場合に、DynamoDB の項目を取得し直すかどうかを指定します。取得された項目は $ctx.result.cancellationReasons[$index].item にあります。ここで $index は、条件チェックに失敗したリクエスト項目のインデックスです。デフォルトは true です。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

リゾルバーのマッピングテンプレートのユーティリティリファレンス

RDS のリゾルバーマッピングテンプレートリファレンス