AWS AppSync が GraphQL API のすべてのリゾルバで JavaScript をサポート

AWS AppSync は、アプリケーションがデータに接続するためのスケーラブルな API を簡単に構築できるマネージドサービスです。AppSync を使用することで、Amazon DynamoDB に接続する API で Web アプリケーションを強化する場合や、ユーザーにイベントのライブアップデートを提供するリアルタイムダッシュボードを構築する場合に、アプリケーションを需要に合わせてシームレスに拡張することができます。昨年、AppSync は AppSync パイプラインリゾルバと AppSync 関数で JavaScript のサポートを開始しました。これにより、お客様はリゾルバを JavaScript で記述し、AppSync の JavaScript ランタイム上で実行してクエリを解決できるようになりました。また、JavaScript リゾルバにより、お客様は一般的な変換や翻訳操作のために追加の計算リソースを使うことなく、リゾルバでより多くのことを行えるようになりました。

AppSync は JavaScript のサポートをユニットリゾルバに拡張しました。開発者は、単一のリゾルバで JavaScript の単一データソースアクセスパターンを扱えるようになりました。開発者は、複雑なアクセスパターンを処理したり、 パイプラインリゾルバで JavaScript 関数と Velocity Template Language (VTL) 関数を混在させたりすることができます。本記事では、独自の API で JavaScript リゾルバを使用する方法について説明します。

はじめに

AWS AppSync コンソールで JavaScript リゾルバを始めることができます。コンソールで “Create API” を選択し、”design from scratch” を選択します。API に名前を付け、ステップ 2 で “Create type backed by a DynamoDB table now” を選択します。ここでコンソールは、新しい GraphQL 型とオペレーションの作成をサポートしてくれます。型を持つ DynamoDB テーブルを作成します。id、owner、name、severity、dueOn のフィールドを持つ Todo 型を作成してみましょう。コンソールで、リゾルバに AppSync JavaScript ランタイムを事前に選択します。

DynamoDB テーブルで構築されたデータモデルを構成します。

次に、データを格納するテーブルを設定します。テーブル名を “todos” とし、プライマリキーを id、ソートキーを owner に設定します。owner で Todo を取得するためのインデックスを追加します。インデックス名を “owner-dueon-index” とし、主キーを owner、ソートキーを dueOn とします。

“Next” をクリックし、オプションを確認して API を作成します。API が作成され、リゾルバが自動的に生成されます。スキーマページから、生成されたリゾルバを 1 つ選択するか、任意のフィールドに新しいリゾルバをアタッチすることができます。id を与えなくても Todo が作成できるようににスキーマを変更してみましょう。CreateTodoInput を以下のように更新します。

input CreateTodoInput {
    id: String
    owner: String!
    name: String
    severity: Int
    dueOn: AWSDate
}

次に、”Resolvers” の画面で、createTodo フィールドを見つけ、そのリゾルバをクリックします。編集するコードは 1 行だけです。以下のように修正を行います。

修正前

const { id, owner, ...values } = ctx.args.input;

修正後

const { id = util.autoId(), owner, ...values } = ctx.args.input;

この単純な変更では、AppSync ユーティリティの autoId を使用して、一意な ID が提供されていない場合に新しい一意な ID を生成します。”Queries” の画面から、Query や Mutation の送信や、Subscription の設定ができます。
例えば、以下のように Todo を作成することができます。

mutation create {
  createTodo(input: {name: "first todo", owner: "brice", severity: 10, dueOn: "2023-08-10"}) {
    dueOn
    id
    name
    owner
    severity
  }
}

次に、owner を使用して作成した Todo を取得することができます。

query byOwner {
  queryTodosByOwnerDueonIndex(owner: "brice") {
    items {
      id
      name
      owner
    }
  }
}

どのスキーマフィールドにもリゾルバをアタッチすることができます。リゾルバをアタッチするには、リゾルバの型、ランタイム、データソースを選択します。

リゾルバが作成されると、いくつかのサンプルコードから選択して、独自のリゾルバを書き始めることができます。

AWS CDK の使用

AWS CDK プロジェクトでは JavaScript リゾルバを使用できます。ローカルで作業する場合は、TypeScript、AppSyncユーティリティライブラリや型、AWS Amplify codegen を活用してコーディング体験を向上させることができます。CDK プロジェクトで TypeScript を使い始めるには、AppSync リゾルバサンプルリポジトリの Todo API CDK サンプルを利用できます。この例では、ファイル名に基づいてリゾルバをデータソースに自動的にリンクするローカルのヘルパーコンストラクトを使用しています。まずリポジトリをローカルにクローンし、依存関係をインストールします。

$ git clone https://github.com/aws-samples/aws-appsync-resolver-samples.git
$ cd aws-appsync-resolver-samples
$ cd examples/cdk/constructs/appsync-helper
$ npm run init
$ cd ../../dynamodb-todo-app 
$ npm install

アプリのリゾルバは lib/appsync/resolvers にあります。Mutation.createTodo.[todos].ts を見てください。./lib/appsync/codegen にある自動生成コードの型を使用しています。codegen の型は、./lib/appsync/schema.graphql にあるスキーマファイルから自動生成されます。codegen を生成するには、以下を実行します。

$ npm run codegen

(このコマンドは amplify codegen を呼び出します。)

これで、コード内で型を使用できるようになります。スキーマが変更された場合はいつでも codegen を再実行し、型を更新することができます。これは Mutation.createTodo のリゾルバです。

import { util, Context } from '@aws-appsync/utils';
import { CreateTodoMutationVariables } from '../codegen';
import { dynamodbPutRequest } from './utils';
export { checkErrorsAndRespond as response } from './utils';

export function request(ctx: Context<CreateTodoMutationVariables>) {
    const { input: values } = ctx.arguments;
    const key = { id: util.autoId() };
    const condition = { id: { attributeExists: false } };
    console.log('--> create todo with requested values: ', values);
    return dynamodbPutRequest({ key, values, condition });
}

このリゾルバは、DynamoDB の PutItemリクエストを作成するためにヘルパー関数 dynamodbPutRequest を使用します。また、レスポンス処理には、レスポンスとしてエクスポートするヘルパー関数 checkErrorsAndRespond を使用します。これはよくあるパターンなので、すべてのリゾルバに書くのではなく、プロジェクトのユーティリティのリストに追加します。

/**
 * Checks for errors and returns the `result
 */
export function checkErrorsAndRespond(ctx: Context) {
    if (ctx.error) {
        util.error(ctx.error.message, ctx.error.type);
    }
    return ctx.result;
}

リゾルバをローカルで操作する際には、TypeScript、インポート、エクスポート、外部ユーティリティを使用できます。リゾルバを保存する前にコードをバンドルするだけです。バンドルの詳細については、AppSync のドキュメントをご参照ください。このプロジェクトでは、リゾルバを自動的にバンドルし、データソースにアタッチしてくれます。詳細については、ヘルパーコンストラクトをご参照ください。

変更をデプロイする準備ができたら、以下を実行してください。

$ npm run cdk deploy

プロジェクトが終了したら、リソースを削除することができます。

$ npm run cdk destroy

リゾルバのコードサンプルだけでなく、その他のサンプルもリポジトリにあります。

まとめ

本記事では、ユニットリゾルバで JavaScript が新たにサポートされたことについて説明しました。コンソールから簡単に始める方法を説明し、CDK プロジェクトのユニットリゾルバで TypeScript などの機能をどのように使用できるかを見ました。これで、すべてのリゾルバと関数で AppSync JavaScript ランタイムを利用できるようになり、データアクセスのすべてのユースケースを使い慣れた方法で簡単に扱えます。まだ JavaScript リゾルバを試したことがないのであれば、ぜひ試してみてください。AWS AppSync コンソールのサンプルやサンプルリポジトリで簡単に始めることができることを忘れないでください。

JavaScript リゾルバの詳細については、ドキュメントやチュートリアルを参照してください。詳細なガイド付きウォークスルーについては、AWS AppSync Immersion Day Workshop をご覧ください。サンプルリポジトリには、使いやすいサンプルやガイドがあります。

本記事は、AWS AppSync now supports JavaScript for all resolvers in GraphQL APIs を翻訳したものです。翻訳はソリューションアーキテクトの稲田大陸が担当しました。