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

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

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

トピック

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

GetItem

-GetItemリクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してGetItemリクエストを DynamoDB に送信し、以下を指定できます。

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 タイプ変換の詳細については、DynamoDB の「」を参照してください。型システム (レスポンスマッピング)。

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

Example

以下は、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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してPutItemDynamoDB、以下を指定できます。

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 タイプ変換の詳細については、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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してUpdateItemDynamoDB、以下を指定できます。

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 タイプ変換の詳細については、DynamoDB の「」を参照してください。型システム (レスポンスマッピング)。

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

例 1

以下は、GraphQL ミューテーション upvote(id: ID!) のマッピングテンプレートです。

この例では、DynamoDB の項目には、upvotesおよびversionfield。


{
    "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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してDeleteItemDynamoDB、以下を指定できます。

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 タイプ変換の詳細については、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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してQueryDynamoDB、以下を指定できます。

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

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

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

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

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

DynamoDB タイプ変換の詳細については、DynamoDB の「」を参照してください。型システム (レスポンスマッピング)。

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

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


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

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

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

Example

以下は、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

-Scanリクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してScanDynamoDB、以下を指定できます。

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

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

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

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

totalSegments

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

segment

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

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

DynamoDB タイプ変換の詳細については、DynamoDB の「」を参照してください。型システム (レスポンスマッピング)。

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

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


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

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

items: DynamoDB スキャンにより返された項目を含むリストです。
nextToken: より多くの結果があるかもしれない場合は、nextTokenには、別のリクエストで使用できるページ分割トークンが含まれています。AWSAppSync は、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 タイプ変換の詳細については、DynamoDB の「」を参照してください。型システム (レスポンスマッピング)。

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

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


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

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

items: 同期により返された項目を含むリストです。
nextToken: より多くの結果があるかもしれない場合は、nextTokenには、別のリクエストで使用できるページ分割トークンが含まれています。AWSAppSync は、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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してBatchGetItemリクエストDynamoDB、複数のテーブルから複数の項目を取得し直します。このリクエストテンプレートでは、以下の情報を指定する必要があります。

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

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 の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。
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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してBatchWriteItemリクエストDynamoDB、複数のテーブルから複数の項目を削除する必要があります。このリクエストテンプレートでは、以下の情報を指定する必要があります。

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

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 つ以上のテーブルを指定する必要があります。この 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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してBatchWriteItemリクエストDynamoDB、複数のテーブルから複数の項目を配置する必要があります。このリクエストテンプレートでは、以下の情報を指定する必要があります。

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

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リクエストマッピングドキュメントを使用すると、AWSAppSync DynamoDB リゾルバーを使用してTransactGetItemsリクエストDynamoDB、複数のテーブルから複数の項目を取得し直します。このリクエストテンプレートでは、以下の情報を指定する必要があります。

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

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

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

トランザクションが成功すると、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 のトランザクションリゾルバー。

TransactWriteItems

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

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

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 の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
attributeValues: DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。
condition: DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、PutItem リクエストはその項目の既存のエントリを上書きします。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。

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

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

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

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

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

table: 条件をチェックする DynamoDB テーブル。値はテーブル名の文字列です。この table の値は必須です。
operation: 実行する DynamoDB の処理です。ConditionCheck DynamoDB の処理を実行するには、これを ConditionCheck に設定する必要があります。この値は必須です。
key: 条件チェックの対象となる項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
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 に存在することが保証されています。

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

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

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

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

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


{ "S" : "identifier" }

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

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


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

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

AWSAppSync では、以下の 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 でエンコードして表したものです。AWSAppSync では、この文字列をバイナリ値にデコードしてから DynamoDB に送信します。AWSAppSync は、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 から応答を受信すると、AWSAppSync はこれを自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換します。DynamoDB の各属性はデコードされ、レスポンスマッピングコンテキストで返されます。

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


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

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


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

このセクションでは、次のようになります。AWSAppSync では、以下の DynamoDB スカラー型、ドキュメント型、およびセット型を変換します。

文字列型 S

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

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


{ "S" : "some string" }

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


"some string"

文字列セット型 SS

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

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


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

AWSAppSync はこれを文字列のリストに変換します。


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

数値型 N

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

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


{ "N" : 1234 }

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

数値セット型 NS

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

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


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

AWSAppSync はこれを数のリストに変換します。


[ 67.8, 12.2, 70 ]

バイナリ型 B

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

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


{ "B" : "SGVsbG8sIFdvcmxkIQo=" }

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


"SGVsbG8sIFdvcmxkIQo="

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

バイナリセット型 BS

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

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


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

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


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

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

ブール型 BOOL

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

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


{ "BOOL" : true }

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


true

リスト型 L

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

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


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

AWSAppSync はこれを変換した値のリストに変換します。


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

マップ型 M

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

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


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

AWSAppSync はこれを JSON オブジェクトに変換します。


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

Null 型 NULL

null 値です。

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


{ "NULL" : null }

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


null

Filters

DynamoDB でオブジェクトを照会する場合、QueryおよびScanオペレーションでは、オプションとして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 で使用される式の属性値のプレースホルダーのみを入力します。

Example

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


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

条件式

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

-AWSAppSync 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)"
   }
}

デフォルトでは、条件チェックが失敗した場合、AWSAppSync DynamoDB のリゾルバーが、ミューテーションに関するエラーを返すとともに、data」errorセクションGraphQL。ただし、AWSAppSync DynamoDB のリゾルバーにより追加の機能を提供して、一般的なエッジケースを開発者が処理することもできます。

もしAWSAppSync DynamoDB のリゾルバーにより、DynamoDB の現在値が必要な結果と一致すると判断でき、処理は成功として扱われます。
エラーを返す代わりに、リゾルバーを設定してカスタムの Lambda 関数を呼び出し、AWSAppSync 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 で使用される式の属性値のプレースホルダーのみを入力します。

残りのフィールドは、AWSAppSync DynamoDB のリゾルバーでは、条件チェックで検出したエラーを処理する方法は次のとおりです。

equalsIgnore

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

consistentRead

条件チェックが失敗すると、AWSAppSync は、強力な整合性のある読み込みを使用して DynamoDB から項目の現在の値を取得します。このフィールドを使用して、AWSAppSync DynamoDB のリゾルバーにより、結果整合性のある読み込みを代わりに使用します。このフィールドはオプションであり、デフォルトは true です。

conditionalCheckFailedHandler

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

strategy

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

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

lambdaArn

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

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

デフォルトでは、条件チェックが失敗すると、AWSAppSync DynamoDB のリゾルバーが、ミューテーションに関するエラーを返すとともに、data」errorセクションGraphQL。ただし、AWSAppSync DynamoDB のリゾルバーにより追加の機能を提供して、一般的なエッジケースを開発者が処理することもできます。

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

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

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

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

のPutItemオペレーションでは、AWSAppSync 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 }
}
```
-AWSAppSync DynamoDB リゾルバーにより、書き込もうとした項目を現在の値と比較し、それぞれ異なっている場合、versionフィールドを無視するように構成されているため、versionフィールドでエラーが検出された場合、処理は成功として扱われ、DynamoDB から取得された項目が返されます。
のDeleteItemオペレーションでは、AWSAppSync DynamoDB のリゾルバーは、項目が DynamoDB から返されたことを確認します。項目が返されなかった場合、処理は成功として扱われます。それ以外の場合は、設定された処理に従います。
のUpdateItemオペレーションでは、AWSAppSync DynamoDB リゾルバーには、DynamoDB 内の項目が期待した結果と一致するかどうかを判定するための十分な情報がないため、設定された処理に従います。

DynamoDB 内のオブジェクトの現在の状態が予想される結果と異なる場合、AWSAppSync DynamoDB リゾルバーにより、ミューテーションを拒否するか、Lambda 関数を呼び出して次の処理を決定します。

「拒否」処理に従う

従う場合Reject戦略です。AWSAppSync DynamoDB のリゾルバーにより、ミューテーションに関するエラーが返されます。また、DynamoDB のオブジェクトの現在値がdata」errorセクションGraphQL。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戦略です。AWSAppSync DynamoDB のリゾルバーは Lambda 関数を呼び出して、次の処理を決定します。Lambda 関数は以下のオプションのいずれかを選択します。

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

Lambda 呼び出しリクエスト

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


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

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

arguments: GraphQL ミューテーションの引数です。これは、$context.arguments のリクエストマッピングドキュメントで使用できる引数と同じです。
requestMapping: この処理のリクエストマッピングドキュメントです。
currentValue: DynamoDB のオブジェクトの現在値です。
resolver: に関する情報AWSAppSync リゾルバです。
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 関数は、呼び出しペイロードを確認し、任意のビジネスロジックを適用して、AWSAppSync DynamoDB リゾルバは、障害を処理する必要があります。条件チェックで検出されたエラーを処理するために、以下の 3 つのオプションが指定できます。

reject ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "reject"
}
```
これは、AWSAppSync DynamoDB リゾルバーは、設定された戦略がReject上記のセクションで説明したように、ミューテーションに関するエラーと DynamoDB のオブジェクトの現在値を返します。
discard ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "discard"
}
```
これは、AWSAppSync DynamoDB のリゾルバーを使用して、条件チェックで検出されたエラーを通知することなく無視し、値を DynamoDB で返します。
retry ミューテーションです。このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
    "action": "retry",
    "retryMapping": { ... }
}
```
これは、AWSAppSync 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
    }
}
```
使用する別の処理やキーを指定する方法はありません。-AWSAppSync DynamoDB のリゾルバーを使用して、同じオブジェクトに対する同じ処理の再試行のみが可能です。また、condition セクションでは conditionalCheckFailedHandler は指定できません。再試行が失敗した場合、AWSAppSync DynamoDB リゾルバーはReject戦略.

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


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 のリゾルバーマッピングテンプレートのリファレンス