Lambda のリゾルバーのマッピングテンプレートリファレンス - AWS AppSync

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

♪AWSAppSync リゾルバマッピングテンプレートAWS LambdaリクエストをシェイプするにはAWSAppSync は、アカウントに配置された Lambda 関数と、Lambda 関数から Lambda 関数に返すレスポンスAWSAppSync。マッピングテンプレートを使用して、にヒントを渡すこともできます。AWSAppSync は、呼び出されるオペレーションの特性に関して。このセクションでは、サポートされる Lambda オペレーションのマッピングテンプレートについて説明します。

リクエストマッピングテンプレート

Lambda リクエストマッピングテンプレートは非常に簡単で、できるだけ多くのコンテキスト情報を Lambda 関数に渡すことができます。

{ "version": string, "operation": Invoke|BatchInvoke, "payload": any type }

以下に示しているのは、解決された Lambda リクエストマッピングテンプレートの JSON スキーマ表現です。

{ "definitions": {}, "$schema": "https://json-schema.org/draft-06/schema#", "$id": "https://aws.amazon.com/appsync/request-mapping-template.json", "type": "object", "properties": { "version": { "$id": "/properties/version", "type": "string", "enum": [ "2018-05-29" ], "title": "The Mapping template version.", "default": "2018-05-29" }, "operation": { "$id": "/properties/operation", "type": "string", "enum": [ "Invoke", "BatchInvoke" ], "title": "The Mapping template operation.", "description": "What operation to execute.", "default": "Invoke" }, "payload": {} }, "required": [ "version", "operation" ], "additionalProperties": false }

以下に示しているのは、fieldコンテキストの value および GraphQL フィールド引数。

{ "version": "2018-05-29", "operation": "Invoke", "payload": { "field": "getPost", "arguments": $util.toJson($context.arguments) } }

マッピングドキュメント全体は、Lambda 関数に入力として渡されます。これにより、前の例では次のようになります。

{ "version": "2018-05-29", "operation": "Invoke", "payload": { "field": "getPost", "arguments": { "id": "postId1" } } }

バージョン

すべてのリクエストマッピングテンプレートに共通で、version はテンプレートが使用するバージョンを定義します。version が必要です。

"version": "2018-05-29"

オペレーション

Lambda データソースでは、次の 2 つの操作を定義できます。InvokeそしてBatchInvoke。-Invokeオペレーションは許可しますAWSAppSync では、すべての GraphQL フィールドリゾルバーに対して Lambda 関数を呼び出すことを知っています。BatchInvoke指示するAWSAppSync を使用して、現在の GraphQL フィールドのリクエストをバッチ処理します。

operation は必須です。

を使用する場合Invokeでは、解決されたリクエストマッピングテンプレートは、Lambda 関数の入力ペイロードと完全に一致します。したがって、次の例では、テンプレートを以下に示します。

{ "version": "2018-05-29", "operation": "Invoke", "payload": { "arguments": $util.toJson($context.arguments) } }

解決され、次の内容が Lambda 関数に渡されます。

{ "version": "2018-05-29", "operation": "Invoke", "payload": { "arguments": { "id": "postId1" } } }

を使用する場合BatchInvokeでは、バッチ内のすべてのフィールドリゾルバーにマッピングテンプレートが適用されます。簡潔さのために、AWSAppSync は解決されたすべてのマッピングテンプレートをマージしますpayloadマッピングテンプレートに一致する単一オブジェクトの下でリストに値を挿入します。

次のサンプルテンプレートは、マージを示します。

{ "version": "2018-05-29", "operation": "BatchInvoke", "payload": $util.toJson($context) }

このテンプレートは、次のマッピングドキュメントに解決されます。

{ "version": "2018-05-29", "operation": "BatchInvoke", "payload": [ {...}, // context for batch item 1 {...}, // context for batch item 2 {...} // context for batch item 3 ] }

ここで payload リストの各要素は、1 回のバッチ項目に対応しています。また、Lambda 関数はリスト形式のレスポンスを返すことが予期され、次のように、各項目はリクエストで送信された順序になります。

[ { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1 { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2 { "data": {...}, "errorMessage": null, "errorType": null } // result for batch item 3 ]

operation は必須です。

Payload

payload フィールドは、任意の正しい形式の JSON を Lambda 関数に渡す際に使用するコンテナです。

そのファイルにoperationフィールドは次のように設定されています。BatchInvoke,AWSAppSync は既存のラップしますpayload値をリストに追加します。

payload は省略可能です。

レスポンスマッピングテンプレート

他のデータソースと同様に、Lambda 関数はレスポンスを送信します。AWSAppSync は、GraphQL タイプに変換する必要があります。

Lambda 関数の結果は、contextVelocity Template Language (VTL) 経由で利用できるオブジェクト$context.resultプロパティ。

Lambda 関数のレスポンスの形状と GraphQL タイプの形状が正確に一致する場合は、以下のレスポンスマッピングテンプレートを使用して、レスポンスを転送できます。

$util.toJson($context.result)

レスポンスマッピングテンプレートに適用される形状の制限や必須フィールドはありません。ただし、GraphQL が厳密に型指定されているので、解決されたマッピングテンプレートは予想される GraphQL タイプに一致する必要があります。

Lambda 関数のバッチ処理されたレスポンス

operation フィールドが BatchInvoke に設定されている場合、AWS AppSync は Lambda 関数からの項目のリストを想定します。AWS AppSync で、それぞれの結果を元のリクエスト項目にマッピングするためには、レスポンスリストでサイズと順番が一致する必要があります。持っても大丈夫ですnullレスポンスリスト内の項目。$ctx.resultは、 に設定されます。nullしたがって。

ダイレクトLambda リゾルバー

マッピングテンプレートの使用を完全に回避したい場合は、AWS AppSync は、Lambda 関数にデフォルトのペイロードを提供し、GraphQL タイプに対する Lambda 関数のデフォルトの応答を提供できます。リクエストテンプレート、レスポンステンプレート、またはどちらを指定しないかを選択できます。AWSAppSync はそれに応じて処理します。

ダイレクト Lambda リクエストマッピングテンプレート

リクエストマッピングテンプレートが提供されていない場合、AWSAppSync はContextLambda 関数に直接オブジェクトをInvokeオペレーション. Context オブジェクトの構造の詳細については、「リゾルバーのマッピングテンプレートのコンテキストリファレンス」を参照してください。

ダイレクト Lambda レスポンスマッピングテンプレート

レスポンスマッピングテンプレートが提供されていない場合、AWSAppSync は、Lambda 関数のレスポンスの受信時に 2 つの処理のいずれかを実行します。リクエストマッピングテンプレートを指定しなかった場合、またはバージョン「2018-05-29」でリクエストマッピングテンプレートを提供した場合、応答ロジックは次のレスポンスマッピングテンプレートと同じように機能します。

#if($ctx.error) $util.error($ctx.error.message, $ctx.error.type, $ctx.result) #end $util.toJson($ctx.result)

バージョン「2017-02-28」のテンプレートを提供した場合、応答ロジックは次のレスポンスマッピングテンプレートと同じように機能します。

$util.toJson($ctx.result)

表面的には、マッピングテンプレートのバイパスは、前の例に示すように、特定のマッピングテンプレートを使用する場合と同様に機能します。ただし、裏では、マッピングテンプレートの評価は完全に回避されます。テンプレート評価ステップはバイパスされるため、一部のシナリオでは、評価が必要なレスポンスマッピングテンプレートを持つ Lambda 関数と比較して、アプリケーションのレスポンスのオーバーヘッドとレイテンシーが少なくなる場合があります。

ダイレクト Lambda リゾルバーレスポンスのカスタムエラー処理

カスタム例外を発生させることにより、ダイレクト Lambda リゾルバーが呼び出す Lambda 関数からのエラーレスポンスをカスタマイズできます。次の例では、JavaScript を使用してカスタム例外を作成する方法を示します。

class CustomException extends Error { constructor(message) { super(message); this.name = "CustomException"; } } throw new CustomException("Custom message");

例外が発生すると、errorTypeそしてerrorMessagenameそしてmessage、それぞれスローされるカスタムエラーの。

errorTypeUnauthorizedException の場合は、AWS AppSync は、カスタムメッセージの代わりにデフォルトのメッセージ ("You are not authorized to make this call.") を返します。

以下は、カスタム errorType を示す GraphQL レスポンスの例です。

{ "data": { "query": null }, "errors": [ { "path": [ "query" ], "data": null, "errorType": "CustomException", "errorInfo": null, "locations": [ { "line": 5, "column": 10, "sourceName": null } ], "message": "Custom Message" } ] }

ダイレクトLambda リゾルバー バッチ処理の有効化

ダイレクト Lambda リゾルバーのバッチ処理は、maxBatchSizeリゾルバーで。メトリックmaxBatchSizeダイレクト Lambda リゾルバーでは 0 より大きい値に設定されています。AWSAppSync は、リクエストを Lambda 関数にバッチで最大サイズで送信します。maxBatchSize

の設定maxBatchSizeDirect Lambda リゾルバで 0 にすると、バッチ処理がオフになります。

Lambda リゾルバーでのバッチ処理の仕組みの詳細については、「」高度なユースケース: バッチ処理

リクエストマッピングテンプレート

バッチ処理が有効で、リクエストマッピングテンプレートが提供されていない場合、AWSAppSync がリストを送信するContextオブジェクトとしてBatchInvokeLambda 関数に直接操作します。

レスポンスマッピングテンプレート

バッチ処理が有効で、レスポンスマッピングテンプレートが提供されていない場合、応答ロジックは次のレスポンスマッピングテンプレートと同じです。

#if( $context.result && $context.result.errorMessage ) $utils.error($context.result.errorMessage, $context.result.errorType, $context.result.data) #else $utils.toJson($context.result.data) #end

Lambda 関数は、次のリストと同じ順序で結果のリストを返す必要があります。Context送信されたオブジェクト。個々のエラーを返すことは、errorMessageそしてerrorType特定の結果が得られます。リストの各結果の形式は次のとおりです。

{ "data" : { ... }, // your data "errorMessage" : { ... }, // optional, if included an error entry is added to the "errors" object in the AppSync response "errorType" : { ... } // optional, the error type }
注記

結果オブジェクトの他のフィールドは現在無視されます。

Lambda からのエラー処理

Lambda 関数で例外またはエラーをスローすることで、すべての結果に対してエラーを返すことができます。バッチリクエストのペイロードリクエストまたはレスポンスのサイズが大きすぎる場合、Lambda はエラーを返します。その場合、以下を検討する必要があります。maxBatchSizeまたは、レスポンスペイロードのサイズを小さくします。

個々のエラーの処理については、を参照してください。個々のエラーを返す

サンプル Lambda 関数

以下のスキーマを使用して、のダイレクト Lambda リゾルバーを作成できます。Post.relatedPostsフィールドリゾルバを設定してバッチ処理を有効にするmaxBatchSize0 より大きい場合:

schema { query: Query mutation: Mutation } type Query { getPost(id:ID!): Post allPosts: [Post] } type Mutation { addPost(id: ID!, author: String!, title: String, content: String, url: String): Post! } type Post { id: ID! author: String! title: String content: String url: String ups: Int downs: Int relatedPosts: [Post] }

次のクエリでは、解決するリクエストのバッチとともに Lambda 関数が呼び出されます。relatedPosts:

query getAllPosts { allPosts { id relatedPosts { id } } }

Lambda 関数の簡単な実装を以下に示します。

const posts = { 1: { id: '1', title: 'First book', author: 'Author1', url: 'https://amazon.com/', content: 'SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1', ups: '100', downs: '10', }, 2: { id: '2', title: 'Second book', author: 'Author2', url: 'https://amazon.com', content: 'SAMPLE TEXT AUTHOR 2 SAMPLE TEXT AUTHOR 2 SAMPLE TEXT', ups: '100', downs: '10', }, 3: { id: '3', title: 'Third book', author: 'Author3', url: null, content: null, ups: null, downs: null }, 4: { id: '4', title: 'Fourth book', author: 'Author4', url: 'https://www.amazon.com/', content: 'SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4', ups: '1000', downs: '0', }, 5: { id: '5', title: 'Fifth book', author: 'Author5', url: 'https://www.amazon.com/', content: 'SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT', ups: '50', downs: '0', }, } const relatedPosts = { 1: [posts['4']], 2: [posts['3'], posts['5']], 3: [posts['2'], posts['1']], 4: [posts['2'], posts['1']], 5: [], } exports.handler = async (event) => { console.log('event ->', event) // retrieve the ID of each post const ids = event.map((context) => context.source.id) // fetch the related posts for each post id const related = ids.map((id) => relatedPosts[id]) // return the related posts; or an error if none were found return related.map((r) => { if (r.length > 0) { return { data: r } } else { return { data: null, errorMessage: 'Not found', errorType: 'ERROR' } } }) }