翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
DynamoDB のリゾルバーのマッピングテンプレートリファレンス
AWS の AppSync DynamoDB リゾルバーにより、GraphQL
トピック
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 の処理。
GetItemDynamoDB の処理を実行するには、これを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 の処理。
PutItemDynamoDB の処理を実行するには、これを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 の処理。
UpdateItemDynamoDB の処理を実行するには、これを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 の処理。
DeleteItemDynamoDB の処理を実行するには、これを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 リクエストマッピングドキュメントを使用すると、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 の処理。
QueryDynamoDB の処理を実行するには、これを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 の処理。
ScanDynamoDB の処理を実行するには、これをScanに設定する必要があります。この値は必須です。 -
filter -
DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「フィルタ」を参照してください。このフィールドはオプションです。
-
index -
クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。
-
limit -
一度に評価する項目の最大数です。このフィールドはオプションです。
-
consistentRead -
DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは
falseです。 -
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には別のリクエストで使用できるページ分割トークンが含まれています。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 の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。
結果は以下の構造を持ちます。
{ 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 リクエストマッピングドキュメントを使用すると、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 の処理。
BatchGetItemDynamoDB の処理を実行するには、これを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 リクエストマッピングドキュメントを使用すると、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 の処理。
BatchDeleteItemDynamoDB の処理を実行するには、これを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 リクエストマッピングドキュメントをしようすると、 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 の処理。
BatchPutItemDynamoDB の処理を実行するには、これを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 の処理。
TransactGetItemsDynamoDB の処理を実行するには、これを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 リクエストマッピングドキュメントをしようすると、AWS の AppSync DynamoDB リゾルバーから DynamoDB への TransactWriteItems リクエストで、複数のテーブルに複数の項目を書き込むように指定できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
-
各リクエスト項目の書き込み先テーブル名
-
実行する各リクエスト項目のオペレーション。サポートされているオペレーションには 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 の処理。
TransactWriteItemsDynamoDB の処理を実行するには、これをTransactWriteItemsに設定する必要があります。この値は必須です。 -
transactItems -
含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この
transactItemsの値は必須です。PutItemの場合、各フィールドの定義は以下のようになります。-
table -
送信先のの DynamoDB テーブル。値はテーブル名の文字列です。この
tableの値は必須です。 -
operation -
実行する DynamoDB の処理。
PutItemDynamoDB の処理を実行するには、これをPutItemに設定する必要があります。この値は必須です。 -
key -
配置する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
-
attributeValues -
DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。このフィールドはオプションです。
-
condition -
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、
PutItemリクエストはその項目の既存のエントリを上書きします。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。
UpdateItemの場合、各フィールドの定義は以下のようになります。-
table -
更新する DynamoDB テーブル。値はテーブル名の文字列です。この
tableの値は必須です。 -
operation -
実行する DynamoDB の処理。
UpdateItemDynamoDB の処理を実行するには、これをUpdateItemに設定する必要があります。この値は必須です。 -
key -
更新する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
-
update -
updateセクションには、 DynamoDBの項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、DynamoDB UpdateExpressions のドキュメントを参照してください。このセクションは必須です。 -
condition -
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、
UpdateItemリクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。
DeleteItemの場合、各フィールドの定義は以下のようになります。-
table -
項目を削除する DynamoDB テーブル。値はテーブル名の文字列です。この
tableの値は必須です。 -
operation -
実行する DynamoDB の処理。
DeleteItemDynamoDB の処理を実行するには、これをDeleteItemに設定する必要があります。この値は必須です。 -
key -
削除する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。
-
condition -
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、
DeleteItemリクエストによって、現在の状態にかかわらず、項目が削除されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「トランザクション条件式」を参照してください。この値はオプションです。
ConditionCheckの場合、各フィールドの定義は以下のようになります。-
table -
条件をチェックする DynamoDB テーブル。値はテーブル名の文字列です。この
tableの値は必須です。 -
operation -
実行する DynamoDB の処理。
ConditionCheckDynamoDB の処理を実行するには、これを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 トランザクションの「チュートリアル」を参照してください。チュートリアル: DynamoDB トランザクションリゾルバー。
型システム (リクエストマッピング)
AWS の AppSync DynamoDB リゾルバーを使用して DynamoDB テーブルを呼び出す場合、AWS AppSync はその呼び出しで使用するそれぞれの値の型を知っている必要があります。これは、DynamoDB が GraphQL や JSON よりも多くの型プリミティブをサポートしているためです (セットやバイナリデータなど)。AWSGraphQL と DynamoDB 間で変換を行う場合、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 でエンコードして表したものです。AWSAppSync では、この文字列をバイナリ値にデコードしてから DynamoDB に送信します。AWSAppSync は、RFC 2045 で定義された Base64 デコーディングスキームを使用します。Base64 のアルファベットにない文字は無視されます。
以下は使用例です。
"attributeValues" : { "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" } } - バイナリセット型
BS -
1 組のバイナリ値です。DynamoDB のバイナリセット値は次のように表されます。
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }値は実際には文字列であることに注意してください。この文字列は、バイナリデータを Base64 でエンコードして表したものです。AWSAppSync では、この文字列をバイナリ値にデコードしてから DynamoDB に送信します。AWSAppSync は、RFC 2045 で定義された Base64 デコーディングスキームを使用します。Base64 のアルファベットにない文字は無視されます。
以下は使用例です。
"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 } }
AWSAppSync 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 はこれを数に変換します。
1234 - 数値セット型
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 }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 リゾルバーは、ミューテーションに関するエラーを返すとともに、GraphQL レスポンスの error セクションの data フィールドで DynamoDB のオブジェクトの現在値を返します。ただし、AWS AppSync DynamoDB のリゾルバーにより追加の機能を提供して、一般的なエッジケースを開発者が処理することもできます。
-
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 です。
