翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 基本クエリの作成 (VTL)
**注記**
現在、主に APPSYNC\_JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)にある APPSYNC\_JS ランタイムとそのガイドの使用をご検討ください。
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) セクションのコマンドと、このセクションのパラメータの詳細を利用することで、これを行うこともできます。
------