翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 基本クエリの作成 (VTL)
**注記**
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。
GraphQL リゾルバーは、タイプのスキーマのフィールドをデータソースに接続します。リゾルバーは、リクエストが受理されるメカニズムです。 AWS AppSync は、コードを記述することなく、スキーマからリゾルバーを自動的に作成して接続したり、スキーマを作成して既存のテーブルからリゾルバーに接続したりできます。
AWS AppSync のリゾルバーは、JavaScript を使用して GraphQL 式をデータソースが使用できる形式に変換します。または、マッピングテンプレートを [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/2.0/vtl-reference.html) で記述すると、GraphQL 表現をデータソースで使用できる形式に変換できます。
このセクションでは、VTL を使用してリゾルバーを設定する方法について説明します。リゾルバーを記述するための入門チュートリアル形式のプログラミングガイドは、[リゾルバーマッピングテンプレートプログラミングガイド](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide)に記載されています。プログラミング時に使用できるヘルパーユーティリティは、[リゾルバーマッピングテンプレートコンテキストリファレンス](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference)にあります。 AWS AppSync には、ゼロから編集またはオーサリングするときに使用できるテストおよびデバッグフローも組み込まれています。詳細については、「[リゾルバーのテストとデバッグ](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)」を参照してください。
前述のチュートリアルを使用する前に、このガイドに従うことをお勧めします。
このセクションでは、リゾルバーを作成する方法、ミューテーション用のリゾルバーを追加する方法、詳細設定を使用する方法について説明します。
## 最初のリゾルバーを作成する
前のセクションの例に従うと、最初のステップとして、ご使用の `Query` タイプに合ったリゾルバーを作成します。
------
#### [ Console ]
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[スキーマ]** を選択します。
1. ページの右側には、**[リゾルバー]** というウィンドウがあります。このボックスには、ページの左側の **[スキーマ]** ウィンドウで定義されているタイプとフィールドのリストが含まれています。リゾルバーはフィールドにアタッチできます。たとえば、**[クエリ]** タイプで、`getTodos` フィールドの横にある **[アタッチ]** を選択します。
1. **[リゾルバーの作成]** ページで、「[データソースを追加する](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)」ガイドで作成したデータソースを選択します。**[マッピングテンプレートの設定]** ウィンドウでは、右側のドロップダウンリストを使用して汎用のリクエストおよびレスポンスのマッピングテンプレートを両方とも選択することも、独自のテンプレートを作成することもできます。
**注記**
リクエストマッピングテンプレートとレスポンスマッピングテンプレートの組み合わせをユニットリゾルバーと呼びます。ユニットリゾルバーは通常、機械的なオペレーションを実行するためのものであるため、データソース数が少ない単一のオペレーションのみに使用することをおすすめします。より複雑なオペレーションには、複数のデータソースで複数のオペレーションを連続して実行できるパイプラインリゾルバーの使用をお勧めします。
リクエストマッピングテンプレートとレスポンスマッピングテンプレートの違いの詳細については、「[ユニットリゾルバー](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-mapping-template-reference-overview.html#unit-resolvers)」を参照してください。
パイプラインリゾルバーの使用に関する詳細については、「[パイプラインリゾルバー](pipeline-resolvers.md#aws-appsync-pipeline-resolvers)」を参照してください。
1. 一般的なユースケースでは、 AWS AppSync コンソールには、データソースから項目を取得するために使用できる組み込みテンプレート (すべての項目クエリ、個々のルックアップなど) があります。たとえば、「[スキーマの設計](designing-your-schema.md#aws-appsync-designing-your-schema)」で使用したスキーマのシンプルバージョンでは、`getTodos` にページ分割がなく、項目を一覧表示するためのリクエストマッピングテンプレートは次のようになっていました。
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. リクエストに関連付けるレスポンスマッピングテンプレートが常に必要になります。コンソールには、リストの値をパススルーする次のようなデフォルトのテンプレートがあります。
```
$util.toJson($ctx.result.items)
```
この例では、項目のリストに対する `context` オブジェクト (`$ctx` としてエイリアスが作成された) の形式は `$context.result.items` です。GraphQL オペレーションが 1 つの項目を返す場合、 になります`$context.result`。 AWS AppSync は、レスポンスを適切にフォーマットするために、前述の関数など、一般的なオペレーション用のヘルパー`$util.toJson`関数を提供します。関数の完全なリストについては、「[リゾルバーのマッピングテンプレートのユーティリティリファレンス](resolver-util-reference.md#aws-appsync-resolver-mapping-template-util-reference)」を参照してください。
1. **[リゾルバーを保存]** を選択します。
------
#### [ API ]
1. [https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html) API を呼び出して、リゾルバーオブジェクトを作成します。
1. [https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html) API を呼び出して、リゾルバーのフィールドを変更できます。
------
#### [ CLI ]
1. [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html) コマンドを実行してリゾルバーを作成します。
このコマンドには次の 6 つのパラメータを入力する必要があります。
1. API の `api-id`。
1. スキーマ内で変更するタイプの `type-name`。このコンソールの例では、`Query` です。
1. タイプ内で変更するフィールドの `field-name`。このコンソールの例では、`getTodos` です。
1. 「[データソースを追加する](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)」ガイドで作成したデータソースの `data-source-name`。
1. `request-mapping-template`。リクエストの本文です。このコンソールの例では、次のようになります。
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. `response-mapping-template`。リクエストの本文です。このコンソールの例では、次のようになります。
```
$util.toJson($ctx.result.items)
```
コマンドの例は、次のようになります。
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"
```
出力は CLI に返されます。例を示します。
```
{
"resolver": {
"kind": "UNIT",
"dataSourceName": "TodoTable",
"requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
"typeName": "Query",
"fieldName": "getTodos",
"responseMappingTemplate": "$util.toJson($ctx.result.items)"
}
}
```
1. リゾルバーのフィールドおよび/またはマッピングテンプレートを変更するには、[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html) コマンドを実行します。
`api-id` パラメータを除いて、`create-resolver` コマンドで使用されたパラメータは、`update-resolver` コマンドの新しい値で上書きされます。
------
## ミューテーション用のリゾルバーの追加
次のステップは、ご使用の `Mutation` タイプに合ったリゾルバーを作成することです。
------
#### [ Console ]
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[スキーマ]** を選択します。
1. **[ミューテーション]** タイプで、`addTodo` フィールドの横にある **[アタッチ]** を選択します。
1. **[リゾルバーの作成]** ページで、「[データソースを追加する](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)」ガイドで作成したデータソースを選択します。
1. このミューテーションでは DynamoDB に新しい項目を追加するため、**[マッピングテンプレートの設定]** ウィンドウでリクエストテンプレートを変更する必要があります。次のリクエストマッピングテンプレートを使用します。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
1. AWS AppSync は、 `addTodo`フィールドで定義された引数を GraphQL スキーマから DynamoDB オペレーションに自動的に変換します。上記の例では、ミューテーションの引数で `$ctx.args.id` として渡された `id` のキーを使用して、レコードが DynamoDB に保存されます。渡した他のすべてのフィールドは、`$util.dynamodb.toMapValuesJson($ctx.args)` を使用して自動的に DynamoDB 属性にマッピングされます。
このリゾルバーでは、次のレスポンスマッピングテンプレートを使用します。
```
$util.toJson($ctx.result)
```
AWS AppSync は、リゾルバーを編集するためのテストワークフローとデバッグワークフローもサポートしています。モック `context` オブジェクトを使用して、呼び出す前にテンプレートでの変換後の値を確認できます。また、クエリを実行する際にデータソースへのリクエストの実行全体をインタラクティブに表示することもできます。詳細については、「[リゾルバーのテストとデバッグ](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)」および「[モニタリングとロギング](monitoring.md#aws-appsync-monitoring)」を参照してください。
1. **[リゾルバーを保存]** を選択します。
------
#### [ API ]
API では、[[最初のリゾルバーを作成する]](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) セクションのコマンドと、このセクションのパラメータの詳細を利用することで、これを行うこともできます。
------
#### [ CLI ]
CLI では、[[最初のリゾルバーを作成する]](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) セクションのコマンドと、このセクションのパラメータの詳細を利用することで、これを行うこともできます。
------
この時点で、高度なリゾルバーを使用していない場合は、「[API の使用](using-your-api.md#aws-appsync-using-your-api)」で説明されているよう GraphQL API の使用を開始できます。
## 高度なリゾルバー
「[スキーマの設計](designing-your-schema.md#aws-appsync-designing-your-schema)」でのサンプルスキーマの構築の「高度な機能」セクションに従ってページ分割スキャンを行う場合は、代わりに `getTodos` フィールドに次のリクエストテンプレートを使用します。
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": $util.defaultIfNull(${ctx.args.limit}, 20),
"nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}
```
このページ分割のユースケースでは、レスポンスマッピングに *cursor* (クライアントが次の開始ページを知るため) と結果セットの両方が含まれている必要があるため、レスポンスマッピングは単なるパススルーではありません。マッピングテンプレートは次のようになります。
```
{
"todos": $util.toJson($context.result.items),
"nextToken": $util.toJson($context.result.nextToken)
}
```
前述のレスポンスマッピングテンプレート内のフィールドは、`TodoConnection` 型で定義されているフィールドと一致している必要があります。
`Comments` テーブルがあり、`Todo` 型の comments フィールドを解決するリレーション (`[Comment]` の型を返す) の場合は、2 番目のテーブルに対してクエリを実行するマッピングテンプレートを使用できます。これを行うには、「[データソースをアタッチする](attaching-a-data-source.md#aws-appsync-getting-started-build-a-schema-from-scratch)」で説明しているように `Comments` テーブルのデータソースを作成しておく必要があります。
**注記**
ここで 2 番目のテーブルに対するクエリオペレーションを使用しているのは、例を示すことのみを目的としています。代わりに、DynamoDB に対して別のオペレーションを使用できます。さらに、リレーションは GraphQL スキーマによって制御されるため、 AWS Lambda や Amazon OpenSearch Service などの別のデータソースからデータを取得できます。
------
#### [ Console ]
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[スキーマ]** を選択します。
1. **[Todo]** タイプで、`comments` フィールドの横にある **[アタッチ]** を選択します。
1. **[リゾルバーの作成]** ページで、**Comments** テーブルのデータソースを選択します。クイックスタートガイドの **Comments** テーブルのデフォルト名は `AppSyncCommentTable` ですが、指定した名前によって異なる場合があります。
1. リクエストマッピングテンプレートに次のスニペットを追加します。
```
{
"version": "2017-02-28",
"operation": "Query",
"index": "todoid-index",
"query": {
"expression": "todoid = :todoid",
"expressionValues": {
":todoid": {
"S": $util.toJson($context.source.id)
}
}
}
}
```
1. `context.source` は、解決する現在のフィールドの親オブジェクトを参照します。この例では、`source.id` は個別の `Todo` オブジェクトを参照します。これはクエリ式に使用されます。
次のようにパススルーのレスポンスマッピングテンプレートを使用できます。
```
$util.toJson($ctx.result.items)
```
1. **[リゾルバーを保存]** を選択します。
1. 最後に、コンソールの **[スキーマ]** ページで、リゾルバーを `addComment` フィールドにアタッチして `Comments` テーブルのデータソースを指定します。この例のリクエストマッピングテンプレートは、引数としてコメントされる特定の `todoid` を含む単純な `PutItem` ですが、次のように `$utils.autoId()` ユーティリティを使用してコメントに対して一意なソートキーを作成します。
```
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"todoid": { "S": $util.toJson($context.arguments.todoid) },
"commentid": { "S": "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
次のようにパススルーレスポンステンプレートを使用します。
```
$util.toJson($ctx.result)
```
------
#### [ API ]
API では、[[最初のリゾルバーを作成する]](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) セクションのコマンドと、このセクションのパラメータの詳細を利用することで、これを行うこともできます。
------
#### [ CLI ]
CLI では、[[最初のリゾルバーを作成する]](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) セクションのコマンドと、このセクションのパラメータの詳細を利用することで、これを行うこともできます。
------
# ダイレクト Lambda リゾルバー (VTL) を使用した VTL マッピングテンプレートの無効化
**注記**
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。
直接 Lambda リゾルバーを使用すると、 AWS Lambda データソースを使用するときに VTL マッピングテンプレートの使用を回避できます。 AWS AppSync は、Lambda 関数へのデフォルトのペイロードと、GraphQL タイプへの Lambda 関数のレスポンスからのデフォルトの変換を提供できます。リクエストテンプレート、レスポンステンプレート、またはどちらも指定できず、 AWS AppSync はそれに応じて処理します。
AWS AppSync が提供するデフォルトのリクエストペイロードとレスポンス変換の詳細については、[「Direct Lambda リゾルバーリファレンス](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers)」を参照してください。 AWS Lambda データソースの設定と IAM 信頼ポリシーの設定の詳細については、[「データソースのアタッチ](attaching-a-data-source.md)」を参照してください。
## ダイレクト Lambda リゾルバーを設定する
以下のセクションでは、Lambda データソースをアタッチし、Lambda リゾルバーをフィールドに追加する方法を示します。
### Lambda データソースを追加する
ダイレクト Lambda リゾルバーをアクティブ化する前に、Lambda データソースを追加する必要があります。
------
#### [ Console ]
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[データソース]** を選択します。
1. **[データソースを作成]** を選択します。
1. **データソース名**を使用する場合、**myFunction** のようなデータソースの名前を入力します。
1. [**データソースタイプ**] で [**AWS Lambda 関数**] を選択します。
1. [**リージョン**] で、該当するリージョンを選択します。
1. **関数 ARN**を使用する場合は、ドロップダウンリストから Lambda 関数を選択します。関数名を検索するか、使用する関数の ARN を手動で入力します。
1. 次に、新しい IAM ロールを作成するか (推奨)、`lambda:invokeFunction` への IAM アクセス許可を持つ既存のロールを選択します。[データソースのアタッチ](attaching-a-data-source.md)セクションで説明しているように、既存のロールには信頼ポリシーが必要です。
次に、リソースで操作を実行するために必要なアクセス許可を持つ IAM ポリシーの例を示します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "lambda:invokeFunction" ],
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:myFunction",
"arn:aws:lambda:us-west-2:123456789012:function:myFunction:*"
]
}
]
}
```
------
1. **[サーバーの作成]** ボタンを選択します。
------
#### [ CLI ]
1. [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html) コマンドを実行してデータソースオブジェクトを作成します。
このコマンドには次の 4 つのパラメータを入力する必要があります。
1. API の `api-id` です。
1. データソースの `name`。コンソールの例では、これは**データソース名**です。
1. データソースの `type`。コンソールの例では、これは**AWS Lambda 関数**です。
1. コンソールの例では**関数 ARN** の `lambda-config`。
**注記**
`Region` など、設定する必要のあるパラメータは他にもありますが、通常はデフォルトで CLI 設定値になります。
コマンドの例は、次のようになります。
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name myFunction --type AWS_LAMBDA --lambda-config lambdaFunctionArn=arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example
```
出力は CLI に返されます。例を示します。
```
{
"dataSource": {
"dataSourceArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/datasources/myFunction",
"type": "AWS_LAMBDA",
"name": "myFunction",
"lambdaConfig": {
"lambdaFunctionArn": "arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example"
}
}
}
```
1. データソースの属性を変更するには、[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html) コマンドを実行します。
`api-id` パラメータを除いて、`create-data-source` コマンドで使用されているパラメータは、`update-data-source` コマンドの新しい値で上書きされます。
------
### ダイレクト Lambda リゾルバをアクティブ化する
Lambda データソースを作成し、 AWS AppSync が関数を呼び出せるように適切な IAM ロールを設定したら、リゾルバーまたはパイプライン関数にリンクできます。
------
#### [ Console ]
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[スキーマ]** を選択します。
1. **[リゾルバー]** セクションで、フィールドまたはオペレーションを選択し、**[アタッチ]** ボタンを選択します。
1. **新しいリゾルバーを作成する**ページで、ドロップダウンリストから Lambda 関数を選択します。
1. ダイレクト Lambda リゾルバーを利用するには、リクエストとレスポンスのマッピングテンプレートが**マッピングテンプレートを設定する**セクションで無効になっていることを確認します。
1. **[リゾルバーの保存]** ボタンを選択します。
------
#### [ CLI ]
+ [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html) コマンドを実行してリゾルバーを作成します。
このコマンドには次の 6 つのパラメータを入力する必要があります。
1. API の `api-id`。
1. スキーマでのタイプの `type-name`。
1. スキーマでのフィールドの `field-name`。
1. `data-source-name`、または Lambda 関数の名前。
1. リクエストの本文である `request-mapping-template`。コンソールの例では、これは無効になっています。
```
" "
```
1. レスポンスの本文である `response-mapping-template`。コンソールの例では、これも無効になっています。
```
" "
```
コマンドの例は、次のようになります。
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Subscription --field-name onCreateTodo --data-source-name LambdaTest --request-mapping-template " " --response-mapping-template " "
```
出力は CLI に返されます。例を示します。
```
{
"resolver": {
"resolverArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/types/Subscription/resolvers/onCreateTodo",
"typeName": "Subscription",
"kind": "UNIT",
"fieldName": "onCreateTodo",
"dataSourceName": "LambdaTest"
}
}
```
------
マッピングテンプレートを無効にすると、 AWS AppSyncで発生する追加の動作がいくつかあります。
+ マッピングテンプレートを無効にすると、[Direct Lambda リゾルバーリファレンス](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers)で指定されたデフォルトのデータ変換を受け入れる AWS AppSync ことを に知らせます。
+ リクエストマッピングテンプレートを無効にすると、Lambda データソースは、[Context](resolver-context-reference.md)オブジェクト全体で構成されるペイロードを受け取ります。
+ レスポンスマッピングテンプレートを無効にすると、リクエストマッピングテンプレートのバージョン、またはリクエストマッピングテンプレートも無効になっているかどうかに応じて、Lambda 呼び出しの結果が変換されます。
# AWS AppSync (VTL) でのリゾルバーのテストとデバッグ
**注記**
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。
AWS AppSync は、データソースに対して GraphQL フィールドでリゾルバーを実行します。「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」で説明しているように、リゾルバーはテンプレート作成言語を使用してデータソースと通信します。これにより、ユーザーは動作をカスタマイズでき、データソースと通信する前後にロジックおよび条件を適用できます。リゾルバーを記述するための入門者向けのチュートリアル形式プログラミングガイドについては、「[リゾルバーのマッピングテンプレートのプログラミングガイド](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide)」を参照してください。
デベロッパーがこれらのリゾルバーを記述、テスト、デバッグできるように、 AWS AppSync コンソールには、モックデータを含む GraphQL リクエストとレスポンスを個々のフィールドリゾルバーに作成するためのツールも用意されています。さらに、 AWS AppSync コンソールでクエリ、ミューテーション、サブスクリプションを実行し、リクエスト全体の Amazon CloudWatch からの詳細なログストリームを表示できます。ログストリームにはデータソースからの結果も含まれています。
## モックデータを使用したテスト
GraphQL リゾルバーが呼び出されるときに、そのリゾルバーには、リクエストに関する情報を含む `context` オブジェクトが含まれています。このオブジェクトには、クライアントからの引数、ID 情報、および親 GraphQL フィールドからのデータが含まれています。また、データソースからの結果も含まれていて、それをレスポンステンプレートで使用できます。この構造体およびプログラミング時に使用可能なヘルパーユーティリティの詳細については、「[リゾルバーのマッピングテンプレートのコンテキストリファレンス](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference)」を参照してください。
リゾルバーを記述または編集する場合に、*モック*または*テストコンテキスト*オブジェクトをコンソールエディタに渡すことができます。これにより、実際にデータソースに対して実行することなく、リクエストとレスポンスの両方のテンプレートでどのように評価されるかを確認できます。例えば、テストの `firstname: Shaggy` 引数を渡して、テンプレートのコードで `$ctx.args.firstname` を使用している場合にその引数がどのように評価されるかを確認できます。任意のユーティリティヘルパー (`$util.autoId()`、`util.time.nowISO8601()` など) での評価をテストすることもできます。
### リゾルバーのテスト
この例では、 AWS AppSync コンソールを使用してリゾルバーをテストします。
1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。
1. **API ダッシュボード**で、GraphQL API を選択します。
1. **サイドバー**で **[スキーマ]** を選択します。
1. まだ行っていない場合は、タイプの下のフィールドの横にある **[アタッチ]** を選択してリゾルバーを追加します。
完全なリゾルバーをビルドする方法の詳細については、「[リゾルバーを設定する](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html)」を参照してください。
それ以外の場合は、すでにフィールドにあるリゾルバーを選択してください。
1. **[リゾルバーを編集]** ページの上部で、**[テストコンテキストを選択]** を選択し、**[新しいコンテキストを作成]** を選択します。
1. サンプルコンテキストオブジェクトを選択するか、下の**実行コンテキスト**ウィンドウに JSON を手動で入力します。
1. **テキストコンテキスト名**を入力します。
1. **[保存]** ボタンを選択します。
1. **[リゾルバーを編集]** ページの上部にある **[テストを実行]** を選択します。
より現実的な例として、オブジェクトに対して自動 ID 生成を使用して Amazon DynamoDB に保存する `Dog` の GraphQL タイプを保存するアプリケーションがあるとします。また、一部の値を GraphQL ミューテーションの引数から書き込み、レスポンスが特定の 1 人のユーザーにのみ表示されるようにします。スキーマは次のようになります。
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
`addDog` ミューテーションに対してリゾルバーを追加するときに、次のようなコンテキストオブジェクトを入力できます。次の例には、クライアントから引数として `name` と `age` があり、`identity` オブジェクトに入力されている `username` があります。
```
{
"arguments" : {
"firstname": "Shaggy",
"age": 4
},
"source" : {},
"result" : {
"breed" : "Miniature Schnauzer",
"color" : "black_grey"
},
"identity": {
"sub" : "uuid",
"issuer" : " https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
"username" : "Nadia",
"claims" : { },
"sourceIp" :[ "x.x.x.x" ],
"defaultAuthStrategy" : "ALLOW"
}
}
```
これを、以下のリクエストとレスポンスのマッピングテンプレートを使用してテストします。
**リクエストテンプレート**
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
**レスポンステンプレート**
```
#if ($context.identity.username == "Nadia")
$util.toJson($ctx.result)
#else
$util.unauthorized()
#end
```
評価後のテンプレートには、テストコンテキストオブジェクトからのデータと、`$util.autoId()` から生成された値があります。また、`username` を `Nadia` 以外の値に変更した場合は、認可チェックが失敗するため、結果は返されません。きめ細かなアクセス制御の詳細については、「[認可のユースケース](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases)」を参照してください。
### AWS AppSync の APIs を使用したマッピングテンプレートのテスト
`EvaluateMappingTemplate` API コマンドを使用して、モックデータを使用してマッピングテンプレートをリモートでテストできます。コマンドを使い始めるには、ポリシーに `appsync:evaluateMappingTemplate` アクセス許可を追加していることを確認してください。例えば、次のようになります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateMappingTemplate",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
[AWS CLI](https://aws.amazon.com/cli/) または [AWS SDK](https://aws.amazon.com/tools/) を使用してコマンドを活用できます。例えば、前のセクションから、`Dog` スキーマとそのリクエスト/レスポンスマッピングテンプレートを見てみましょう。ローカルステーションの CLI を使用して、リクエストテンプレートを `request.vtl` という名前のファイルに保存し、`context` オブジェクトを `context.json` という名前のファイルに保存します。シェルから次のコマンドを実行します。
```
aws appsync evaluate-mapping-template --template file://request.vtl --context file://context.json
```
このコマンドは、次のレスポンスを返します。
```
{
"evaluationResult": "{\n \"version\" : \"2017-02-28\",\n \"operation\" : \"PutItem\",\n \"key\" : {\n \"id\" : { \"S\" : \"afcb4c85-49f8-40de-8f2b-248949176456\" }\n },\n \"attributeValues\" : {\"firstname\":{\"S\":\"Shaggy\"},\"age\":{\"N\":4}}\n}\n"
}
```
`evaluationResult` には、提供されたテンプレートを提供された `context` とともにテストした結果が含まれています。 AWS SDKs を使用してテンプレートをテストすることもできます。 AWS SDK for JavaScript V2 を使用した例を次に示します。
```
const AWS = require('aws-sdk')
const client = new AWS.AppSync({ region: 'us-east-2' })
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
client
.evaluateMappingTemplate({ template, context })
.promise()
.then((data) => console.log(data))
```
SDK を使用すると、お気に入りのテストスイートのテストを簡単に組み込んで、テンプレートの動作を検証できます。[Jest テストフレームワーク](https://jestjs.io/)を使用してテストを作成することをお勧めしますが、どのテストスイートでも問題ありません。次のスニペットは、仮説検証の実行を示しています。評価レスポンスは有効な JSON であることを想定しているので、`JSON.parse`を使用して文字列レスポンスから JSON を取得することに注意してください。
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
test('request correctly calls DynamoDB', async () => {
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateMappingTemplate({ template, context }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
これにより、次のような結果が得られます。
```
Ran all test suites.
> jest
PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.511 s, estimated 2 s
```
## ライブクエリのデバッグ
本番アプリケーションをデバッグするためのend-to-endのテストとログ記録に代わるものはありません。 AWS AppSync では、Amazon CloudWatch を使用してエラーとリクエストの詳細全体をログ記録できます。さらに、 AWS AppSync コンソールを使用して、各リクエストの GraphQL クエリ、ミューテーション、サブスクリプション、ライブストリームログデータをテストし、クエリエディタに戻し、リアルタイムでデバッグできます。サブスクリプションに関して表示されるログは接続時の情報です。
これを実行するには、「[モニタリングとロギング](monitoring.md#aws-appsync-monitoring)」で説明しているように、Amazon CloudWatch Logs を事前に有効にしておく必要があります。次に、 AWS AppSync コンソールで**クエリ**タブを選択し、有効な GraphQL クエリを入力します。右下のセクションで、**[ログ]** ウィンドウをクリックしてドラッグし、ログビューを開きます。ページの上部にある再生矢印アイコンを選択して GraphQL クエリを実行します。しばらくすると、そのオペレーションのリクエストとレスポンスの完全なログが、このセクションにストリーミングされ、コンソールで表示できます。
# AWS AppSync (VTL) でのパイプラインリゾルバーの設定と使用
**注記**
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。
AWS AppSync は GraphQL フィールドでリゾルバーを実行します。場合によっては、アプリケーションは 1 つの GraphQL フィールドを解決するために複数のオペレーションを実行する必要があります。パイプラインリゾルバーを使用すると、開発者は関数と呼ばれるオペレーションを構成して順番に実行できます。パイプラインリゾルバーは、たとえば、フィールドのデータを取得する前に承認チェックを実行する必要があるアプリケーションに便利です。
パイプラインリゾルバーは、**Before** マッピングテンプレート、**After** マッピングテンプレート、関数のリストで構成されています。各関数には、データソースに対して実行される**リクエスト**および**レスポンス**マッピングテンプレートがあります。パイプラインリゾルバーは実行をリスト内の関数に委任するため、いずれのデータソースにもリンクされていません。ユニットリゾルバーと関数は、データソースに対してオペレーションを実行するプリミティブです。詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
## ステップ 1: パイプラインリゾルバーを作成する
AWS AppSync コンソールで、**スキーマ**ページに移動します。
以下のスキーマを保存します。
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
パイプラインリゾルバーを**ミューテーション**タイプの **SignUp** フィールドに書き込みます。右側の **[ミューテーション]** タイプに入力し、[`signUp` ミューテーション] フィールドの横の **[アタッチ]** を選択します。[リゾルバーの作成] ページで、**[アクション]**、**[ランタイム更新]** の順にクリックします。[`Pipeline Resolver`]、[`VTL`] の順に選択してから、**[更新]** を選択します。このページには、**Before マッピングテンプレート**テキスト領域、**関数**セクション、**After マッピングテンプレート**テキスト領域の 3 つのセクションが表示されています。
パイプラインリゾルバーは、最初に E メールアドレスの入力を検証してからシステムにユーザーを保存することで、ユーザーをサインアップします。E メールの検証を **validateEmail** 関数内にカプセル化し、ユーザーの保存を **saveUser** 関数内にカプセル化します。**validateEmail** 関数が最初に実行され、E メールが有効であれば、**saveUser** 関数が実行されます。
実行フローは以下のようになります。
1. Mutation.signUp リゾルバーのリクエストマッピングテンプレート
1. validateEmail 関数
1. saveUser 関数
1. Mutation.signUp リゾルバーのレスポンスマッピングテンプレート
API の他のリゾルバーで **validateEmail** 関数を再利用することが多いため、GraphQL フィールド間でアクセス先の `$ctx.args` が変わるのを避けるとします。この場合、代わりに `$ctx.stash` を使用して、`signUp(input: Signup)` 入力フィールド引数からの email 属性を保存できます。
**BEFORE** マッピングテンプレート:
```
## store email input field into a generic email key
$util.qr($ctx.stash.put("email", $ctx.args.input.email))
{}
```
コンソールから、デフォルトのパススルー **AFTER** マッピングテンプレートを使用できます。
```
$util.toJson($ctx.result)
```
**[作成]** または **[保存]** を選択してリゾルバーを更新します。
## ステップ 2: 関数を作成する
パイプラインリゾルバーページの **[関数]** セクションで、**[関数の作成]** をクリックして、**[新しい関数の作成]** をクリックします。リゾルバーページを経由せずに関数を作成することもできます。これを行うには、 AWS AppSync コンソールで**関数**ページに移動します。**[関数の作成]** ボタンを選択します。E メールが有効であり特定のドメインからのものかどうかをチェックする関数を作成しましょう。E メールが無効な場合、この関数はエラーを発生させます。それ以外の場合、渡された入力をすべて転送します。
新しい関数ページで、**[アクション]** を選択して、**[ランタイムを更新]** を選択します。[`VTL`] を選択してから、**[更新]** を選択します。**NONE** 型のデータソースが作成されたことを確認してください。**[データソース名]** リストでこのデータソースを選択します。**[関数名]** に `validateEmail` と入力します。**関数コード** 領域で、次のスニペットですべてを上書きします。
```
#set($valid = $util.matches("^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com", $ctx.stash.email))
#if (!$valid)
$util.error("$ctx.stash.email is not a valid email.")
#end
{
"payload": { "email": $util.toJson(${ctx.stash.email}) }
}
```
レスポンスマッピングテンプレートにこれを貼り付けます。
```
$util.toJson($ctx.result)
```
変更内容を確認し、**[作成]** を選択します。これで、**validateEmail** 関数が作成されました。次のリクエストマッピングテンプレートとレスポンスマッピングテンプレートでこれらの手順を繰り返し、**saveUser** 関数を作成します (わかりやすくするため、**NONE** データソースを使用し、関数が実行された後にユーザーがシステムに保存されたものとしています。):
リクエストマッピングテンプレート:
```
## $ctx.prev.result contains the signup input values. We could have also
## used $ctx.args.input.
{
"payload": $util.toJson($ctx.prev.result)
}
```
レスポンスマッピングテンプレート
```
## an id is required so let's add a unique random identifier to the output
$util.qr($ctx.result.put("id", $util.autoId()))
$util.toJson($ctx.result)
```
これで、**saveUser** 関数が作成されました。
## ステップ 3: パイプラインリゾルバーに関数を追加する
先ほど作成したパイプラインリゾルバーには関数が自動的に追加されています。そうでない場合、または **[関数]** ページで関数を作成した場合は、リゾルバーページの **[関数を追加]** をクリックして、それらの関数をアタッチできます。**validateEmail** と **saveUser** の両方の関数をリゾルバーに追加します。**validateEmail** 関数は **saveUser** 関数の前に配置する必要があります。関数を追加するときには、**上に移動**および**下に移動**オプションを使用して関数の実行順序を並べ替えることができます。変更を確認し、**[保存]** を選択します。
## ステップ 4: クエリを実行する
AWS AppSync コンソールで、**クエリ**ページに移動します。Explorer で、ミューテーションを使用していることを確認します。そうでない場合は、ドロップダウンリストから [`Mutation`] を選択し、[`+`] を選択します。以下のクエリを入力します。
```
mutation {
signUp(input: {
email: "nadia@myvaliddomain.com"
username: "nadia"
}) {
id
email
}
}
```
以下のように返されます。
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"email": "nadia@myvaliddomain.com"
}
}
}
```
これで、パイプラインリゾルバーを使用して、ユーザーをサインアップし、入力 E メールを検証できました。パイプラインリゾルバーに焦点を当てたより完全なチュートリアルについては、「[チュートリアル: パイプラインリゾルバー](tutorial-pipeline-resolvers.md#aws-appsync-tutorial-pipeline-resolvers)」を参照してください。