リゾルバーを設定する (VTL)

注記

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

GraphQL リゾルバーは、タイプのスキーマのフィールドをデータソースに接続します。リゾルバーはリクエストを実行するメカニズムです。AWSAppSync はスキーマからリゾルバーを自動的に作成して接続でき、またはスキーマを作成し、既存のテーブルからリゾルバーと接続できます。このときコードを記述する必要はありません。

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

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

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

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

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

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

Console

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

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

API

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

CLI

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

この特定のコマンドには次の 6 つのパラメータを入力する必要があります。
1. API の api-id。
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. API ダッシュボードで、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

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

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 に対して別のオペレーションを使用できます。さらに、このリレーションはユーザーの GraphQL スキーマによって制御されているため、AWS Lambda や Amazon OpenSearch Service などの別のデータソースからデータを取り込むこともできます。

Console

AWS Management Console にサインインして、AppSync コンソールを開きます。
1. API ダッシュボードで、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

CLI

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

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

ドキュメントの表記規則

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

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