AWS AppSync JavaScript リゾルバーの概要

AWS AppSync を使用すると、データソースに対してオペレーションを実行して GraphQL リクエストに応答できます。クエリ、ミューテーション、サブスクリプションなど、実行する GraphQL フィールドごとに、リゾルバーをアタッチする必要があります。

リゾルバーは GraphQL とデータソースの間のコネクタです。受信した GraphQL リクエストをバックエンドのデータソースに対する指示に変換する方法と、そのデータソースからのレスポンスを GraphQL レスポンスに戻す方法を AWS AppSync に指示します。AWS AppSync を使用すると、JavaScript を使用してリゾルバーを記述し、AWS AppSync (APPSYNC_JS) 環境で実行できます。

AWS AppSync では、複数の AWS AppSync 関数で構成されるユニットリゾルバーまたはパイプラインリゾルバーをパイプラインに記述できます。

サポートされているランタイム機能

AWS AppSync JavaScript ランタイムは、JavaScript ライブラリ、ユーティリティ、および機能のサブセットを提供します。APPSYNC_JS ランタイムでサポートされている特徴と機能の完全なリストについては、「リゾルバーと関数用の JavaScript ランタイム機能」を参照してください。

ユニットリゾルバー

ユニットリゾルバーは、データソースに対して実行されるリクエストハンドラーとレスポンスハンドラーを定義するコードで構成されています。リクエストハンドラーはコンテキストオブジェクトを引数として受け取り、データソースの呼び出しに使用されたリクエストペイロードを返します。レスポンスハンドラーは、実行されたリクエストの結果を含むペイロードをデータソースから受け取ります。レスポンスハンドラーは、ペイロードを GraphQL レスポンスに変換して GraphQL フィールドを解決します。以下の例では、リゾルバーは DynamoDB データソースから項目を取得します。

import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
  return ddb.get({ key: { id: ctx.args.id } });
}

export const response = (ctx) => ctx.result;

JavaScript パイプラインリゾルバーの仕組み

パイプラインリゾルバーは、リクエストとレスポンスのハンドラーと関数のリストを定義するコードで構成されています。各関数には、データソースに対して実行されるリクエストおよびレスポンスハンドラーがあります。パイプラインリゾルバーは実行をリスト内の関数に委任するため、いずれのデータソースにもリンクされていません。ユニットリゾルバーと関数は、データソースに対してオペレーションを実行するプリミティブです。

パイプラインリゾルバーリクエストハンドラー

パイプラインリゾルバーのリクエストハンドラー (before step) では、定義した関数を実行する前に準備ロジックを実行できます。

関数のリスト

パイプラインリゾルバーが順番に実行する関数のリスト。パイプラインリゾルバーのリクエストハンドラーの評価結果は、最初の関数で ctx.prev.result として使用可能になります。各関数の評価結果は、以下の関数で ctx.prev.result として使用可能です。

パイプラインリゾルバーレスポンスハンドラー

パイプラインリゾルバーのレスポンスハンドラーでは、最後の関数の出力から、想定される GraphQL フィールドタイプへの、一部の最終的なロジックを実行できます。関数のリストの最後にある関数の出力は、パイプラインリゾルバーレスポンスハンドラーで ctx.prev.result または ctx.result として使用可能です。

実行フロー

2 つの関数で構成されるパイプラインリゾルバーがあるとします。以下のリストでは、リゾルバーが呼び出されたときの実行フローを表しています。

便利な APPSYNC_JS ランタイムビルトインユーティリティ

パイプラインリゾルバーでの作業には、以下のユーティリティが役立ちます。

ctx.stash

stash は、各リゾルバー、関数リクエスト、レスポンスハンドラー内で使用できるオブジェクトです。同じ stash インスタンスは 1 つのリゾルバーの実行を通して存続します。つまり、stash を使用して、リクエストとレスポンスのハンドラー間、およびパイプラインリゾルバーの関数間で、任意のデータを渡すことができます。stash は通常の JavaScript オブジェクトと同じようにテストできます。

ctx.prev.result

ctx.prev.result は、パイプラインで実行された前のオペレーションの結果を表します。前のオペレーションがパイプラインリゾルバーリクエストハンドラーであった場合、ctx.prev.result はチェーン内の最初の関数に使用可能になります。前のオペレーションが最初の関数であった場合、ctx.prev.result は最初の関数の出力を表し、パイプライン内の 2 番目の関数に使用可能になります。前のオペレーションが最後の関数であった場合、ctx.prev.result は最後の関数の出力を表し、パイプラインリゾルバーレスポンスハンドラーに使用可能になります。

util.error

util.error ユーティリティはフィールドエラーをスローするのに便利です。関数リクエストまたはレスポンスハンドラー内で util.error を使用すると、フィールドエラーがすぐにスローされ、それ以降の関数が実行されなくなります。詳細やその他の util.error シグネチャについては、「リゾルバーと関数の JavaScript ランタイム機能」を参照してください。

util.appendError

util.appendError は util.error() と似ていますが、ハンドラーの評価を中断しないという大きな違いがあります。代わりに、フィールドにエラーがあったことを通知します。ただし、ハンドラーを評価し、データを引き続き返すことも可能です。関数内で util.appendError を使用しても、パイプラインの実行フローは中断されません。詳細やその他の util.error シグネチャについては、「リゾルバーと関数の JavaScript ランタイム機能」を参照してください。

runtime.earlyReturn

runtime.earlyReturn 関数を使うと、どのリクエスト関数からでも途中で戻ることができます。リゾルバーのリクエストハンドラー内で runtime.earlyReturn を使用すると、リゾルバーから返されます。AWS AppSync 関数リクエストハンドラーから呼び出すと、関数から戻り、パイプライン内の次の関数またはリゾルバー応答ハンドラーのどちらかまで実行が続行されます。

パイプラインリゾルバーの記述

パイプラインリゾルバーには、パイプライン内の関数の実行を囲むリクエストハンドラーとレスポンスハンドラーもあります。リクエストハンドラーは最初の関数のリクエストの前に実行され、レスポンスハンドラーは最後の関数の応答の後に実行されます。リゾルバーリクエストハンドラーは、パイプライン内の関数が使用するデータを設定できます。リゾルバーレスポンスハンドラーは GraphQL フィールド出力タイプにマッピングするデータを返す役割を果たします。以下の例では、リゾルバーリクエストハンドラーが allowedGroups を定義しています。返されるデータはこれらのグループのいずれかに属している必要があります。この値は、リゾルバーの関数がデータをリクエストする際に使用できます。リゾルバーのレスポンスハンドラーは最終チェックを行い、結果をフィルタリングして、許可されたグループに属するアイテムだけが返されるようにします。

import { util } from '@aws-appsync/utils';

/**
 * Called before the request function of the first AppSync function in the pipeline.
 *  @param ctx the context object holds contextual information about the function invocation.
 */
export function request(ctx) {
  ctx.stash.allowedGroups = ['admin'];
  ctx.stash.startedAt = util.time.nowISO8601();
  return {};
}
/**
 * Called after the response function of the last AppSync function in the pipeline.
 * @param ctx the context object holds contextual information about the function invocation.
 */
export function response(ctx) {
  const result = [];
  for (const item of ctx.prev.result) {
    if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
  }
  return result;
}

AWS AppSync 関数の記述

AWS AppSync 関数では、スキーマ内の複数のリゾルバーにまたがって再利用できる共通のロジックを作成できます。例えば、Amazon DynamoDB データソースの項目をクエリする QUERY_ITEMS という AWS AppSync 関数を 1 つ指定できます。項目をクエリするリゾルバーについては、リゾルバーのパイプラインに関数を追加し、使用するクエリインデックスを指定するだけです。ロジックを再実装する必要はありません。

補足トピック

トピック