基本的なクエリの作成 (VTL）

注記

現在、主に APPSYNC_JS ランタイムとそのドキュメントをサポートしています。APPSYNC_JS ランタイムとそのガイドをここで使用することを検討してください。

GraphQL リゾルバーは、タイプのスキーマのフィールドをデータソースに接続します。リゾルバーは、リクエストが受理されるメカニズムです。 AWS AppSync は、コードを記述することなく、スキーマからリゾルバーを自動的に作成して接続したり、既存のテーブルからスキーマを作成してリゾルバーを接続したりできます。

データソースが使用できる形式に GraphQL 式を変換 JavaScript するために AWS AppSync 使用されているリゾルバー。または、マッピングテンプレートを Apache Velocity Template Language (VTL）で記述して、GraphQL 式をデータソースが使用できる形式に変換することもできます。

このセクションでは、を使用してリゾルバーを設定する方法について説明しますVTL。リゾルバーを記述するための入門チュートリアル形式のプログラミングガイドは、リゾルバーマッピングテンプレートプログラミングガイドに記載されています。プログラミング時に使用できるヘルパーユーティリティは、リゾルバーマッピングテンプレートコンテキストリファレンスにあります。 AWS AppSync また、には、ゼロから編集またはオーサリングするときに使用できるテストおよびデバッグフローが組み込まれています。詳細については、「リゾルバーのテストとデバッグ」を参照してください。

前述のチュートリアルを使用する前に、このガイドに従うことをお勧めします。

このセクションでは、リゾルバーを作成する方法、ミューテーション用のリゾルバーを追加する方法、詳細設定を使用する方法について説明します。

最初のリゾルバーを作成する

前のセクションの例に従うと、最初のステップとして、ご使用の Query タイプに合ったリゾルバーを作成します。

Console

にサインイン AWS Management Console し、AppSync コンソールを開きます。
1. APIs ダッシュボード で、GraphQL を選択しますAPI。
2. サイドバーで [スキーマ] を選択します。
ページの右側には、[リゾルバー] というウィンドウがあります。このボックスには、ページの左側の [スキーマ] ウィンドウで定義されているタイプとフィールドのリストが含まれています。リゾルバーはフィールドにアタッチできます。たとえば、[クエリ] タイプで、getTodos フィールドの横にある [アタッチ] を選択します。
[リゾルバーの作成] ページで、「データソースを追加する」ガイドで作成したデータソースを選択します。[マッピングテンプレートの設定] ウィンドウでは、右側のドロップダウンリストを使用して汎用のリクエストおよびレスポンスのマッピングテンプレートを両方とも選択することも、独自のテンプレートを作成することもできます。

注記
リクエストマッピングテンプレートとレスポンスマッピングテンプレートの組み合わせをユニットリゾルバーと呼びます。ユニットリゾルバーは通常、機械的なオペレーションを実行するためのものであるため、データソース数が少ない単一のオペレーションのみに使用することをおすすめします。より複雑なオペレーションには、複数のデータソースで複数のオペレーションを連続して実行できるパイプラインリゾルバーの使用をお勧めします。
リクエストマッピングテンプレートとレスポンスマッピングテンプレートの違いの詳細については、「ユニットリゾルバー」を参照してください。
パイプラインリゾルバーの使用に関する詳細については、「パイプラインリゾルバー」を参照してください。
一般的なユースケースでは、 AWS AppSync コンソールには、データソースから項目を取得するために使用できるテンプレートが組み込まれています (例: すべての項目クエリ、個々の検索など）。たとえば、「スキーマの設計」で使用したスキーマのシンプルバージョンでは、getTodos にページ分割がなく、項目を一覧表示するためのリクエストマッピングテンプレートは次のようになっていました。
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
リクエストに関連付けるレスポンスマッピングテンプレートが常に必要になります。コンソールには、リストの値をパススルーする次のようなデフォルトのテンプレートがあります。
```
$util.toJson($ctx.result.items)
```
この例では、項目のリストに対する context オブジェクト ($ctx としてエイリアスが作成された) の形式は $context.result.items です。GraphQL オペレーションが 1 つの項目を返す場合、になります$context.result。 AWS AppSync は、レスポンスを適切にフォーマットするために、前述の関数など、一般的なオペレーション用のヘルパー$util.toJson関数を提供します。関数の完全なリストについては、「リゾルバーのマッピングテンプレートのユーティリティリファレンス」を参照してください。
[リゾルバーを保存] を選択します。

API

を呼び出してリゾルバーオブジェクトを作成しますCreateResolverAPI。
を呼び出すことで、リゾルバーのフィールドを変更できますUpdateResolverAPI。

CLI

create-resolver コマンドを実行してリゾルバーを作成します。

このコマンドには次の 6 つのパラメータを入力する必要があります。
1. api-id の API。
2. スキーマ内で変更するタイプの type-name。このコンソールの例では、Query です。
3. タイプ内で変更するフィールドの field-name。このコンソールの例では、getTodos です。
4. 「データソースを追加する」ガイドで作成したデータソースの data-source-name。
5. request-mapping-template。リクエストの本文です。このコンソールの例では、次のようになります。
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
6. 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)"
    }
}
```
リゾルバーのフィールドおよび/またはマッピングテンプレートを変更するには、update-resolver コマンドを実行します。

api-id パラメータを除いて、create-resolver コマンドで使用されたパラメータは、update-resolver コマンドの新しい値で上書きされます。

ミューテーション用のリゾルバーの追加

次のステップは、ご使用の Mutation タイプに合ったリゾルバーを作成することです。

Console

にサインイン AWS Management Console し、AppSync コンソールを開きます。
1. APIs ダッシュボード で、GraphQL を選択しますAPI。
2. サイドバーで [スキーマ] を選択します。
[ミューテーション] タイプで、addTodo フィールドの横にある [アタッチ] を選択します。
[リゾルバーの作成] ページで、「データソースを追加する」ガイドで作成したデータソースを選択します。
このミューテーションでは DynamoDB に新しい項目を追加するため、[マッピングテンプレートの設定] ウィンドウでリクエストテンプレートを変更する必要があります。次のリクエストマッピングテンプレートを使用します。
```
{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
AWS AppSync は、 addTodoフィールドで定義された引数を GraphQL スキーマから DynamoDB オペレーションに自動的に変換します。上記の例では、ミューテーションの引数で $ctx.args.id として渡された id のキーを使用して、レコードが DynamoDB に保存されます。渡した他のすべてのフィールドは、$util.dynamodb.toMapValuesJson($ctx.args) を使用して自動的に DynamoDB 属性にマッピングされます。

このリゾルバーでは、次のレスポンスマッピングテンプレートを使用します。
```
$util.toJson($ctx.result)
```
AWS AppSync は、リゾルバーを編集するためのテストおよびデバッグワークフローもサポートしています。モック context オブジェクトを使用して、呼び出す前にテンプレートでの変換後の値を確認できます。また、クエリを実行する際にデータソースへのリクエストの実行全体をインタラクティブに表示することもできます。詳細については、「リゾルバーのテストとデバッグ」および「モニタリングとロギング」を参照してください。
[リゾルバーを保存] を選択します。

API

これを行うには、最初のリゾルバーの作成セクションのコマンドと、このセクションのパラメータの詳細APIsを使用します。

CLI

また、最初のリゾルバーの作成セクションのコマンドと、このセクションのパラメータの詳細CLIを利用して、でこれを行うこともできます。

この時点で、アドバンストリゾルバーを使用していない場合は、「の使用」の説明APIに従って GraphQL の使用を開始できますAPI。

高度なリゾルバー

「スキーマの設計」でのサンプルスキーマの構築の「高度な機能」セクションに従ってページ分割スキャンを行う場合は、代わりに 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 番目のテーブルに対してクエリを実行するマッピングテンプレートを使用できます。これを行うには、「データソースをアタッチする」で説明しているように Comments テーブルのデータソースを作成しておく必要があります。

注記

ここで 2 番目のテーブルに対するクエリオペレーションを使用しているのは、例を示すことのみを目的としています。代わりに、DynamoDB に対して別のオペレーションを使用できます。さらに、 AWS Lambda や Amazon OpenSearch Service などの別のデータソースからデータを取得することもできます。これは、リレーションが GraphQL スキーマによって制御されるためです。

Console

にサインイン AWS Management Console し、AppSync コンソールを開きます。
1. APIs ダッシュボード で、GraphQL を選択しますAPI。
2. サイドバーで [スキーマ] を選択します。
[Todo] タイプで、comments フィールドの横にある [アタッチ] を選択します。
[リゾルバーの作成] ページで、Comments テーブルのデータソースを選択します。クイックスタートガイドの Comments テーブルのデフォルト名は AppSyncCommentTable ですが、指定した名前によって異なる場合があります。

リクエストマッピングテンプレートに次のスニペットを追加します。


{
    "version": "2017-02-28",
    "operation": "Query",
    "index": "todoid-index",
    "query": {
        "expression": "todoid = :todoid",
        "expressionValues": {
            ":todoid": {
                "S": $util.toJson($context.source.id)
            }
        }
    }
}

context.source は、解決する現在のフィールドの親オブジェクトを参照します。この例では、source.id は個別の Todo オブジェクトを参照します。これはクエリ式に使用されます。

次のようにパススルーのレスポンスマッピングテンプレートを使用できます。
```
$util.toJson($ctx.result.items)
```
[リゾルバーを保存] を選択します。
最後に、コンソールの [スキーマ] ページで、リゾルバーを 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

これを行うには、最初のリゾルバーの作成セクションのコマンドと、このセクションのパラメータの詳細APIsを使用します。

CLI

これを行うには、最初のリゾルバーの作成セクションのコマンドと、このセクションのパラメータの詳細CLIを使用します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

パイプラインリゾルバー (JavaScript)

ダイレクト Lambda リゾルバー (VTL)