翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS AppSync リゾルバーリファレンス (JavaScript) 次のセクションには、`APPSYNC_JS` ランタイムと JavaScript リゾルバーリファレンスが含まれています。 + [JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html) - リゾルバーの AWS AppSyncでの仕組みについて詳しく説明します。 + [リゾルバーコンテキストオブジェクトリファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) - コンテキストオブジェクトの詳細とリゾルバーでの使用方法について説明します。 + [リゾルバーと関数の JavaScript ランタイム機能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) - サポートされているランタイム機能の詳細と、コードを簡素化するためのユーティリティの使用について説明します。 + [DynamoDB 用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html) - リゾルバーが DynamoDB とやり取りする方法の詳細について説明します。 + [OpenSearch 用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-elasticsearch-js.html) - リゾルバーのリクエストとレスポンスの構造、および OpenSearch Service とのやり取りの詳細について説明します。 + [Lambda 用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-lambda-js.html) - リゾルバーのリクエストとレスポンスの構造、および Lambda とのやり取りについて詳しく説明します。 + [EventBridge データソース用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-eventbridge-js.html) - リゾルバーのリクエストとレスポンスの構造、および EventBridge とのやり取りの詳細について説明します。 + [None データソース用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-none-js.html) - リゾルバーのリクエストとレスポンスの構造、および NONE データソースとのやり取りについて詳しく説明します。 + [HTTP 用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-http-js.html) - リゾルバーのリクエストとレスポンスの構造、および HTTP エンドポイントとのやり取りの詳細について説明します。 + [Amazon RDS 用 JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-rds-js.html) - リゾルバーの構造と RDS とのやり取りの詳細について説明します。 + [Amazon Bedrock JavaScript リゾルバー関数リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-bedrock-js.html) - リゾルバーの構造と Amazon Bedrock とのやり取りの詳細について説明します。 # 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 ランタイム機能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)」を参照してください。 ## ユニットリゾルバー ユニットリゾルバーは、データソースに対して実行されるリクエストハンドラーとレスポンスハンドラーを定義するコードで構成されています。リクエストハンドラーはコンテキストオブジェクトを引数として受け取り、データソースの呼び出しに使用されたリクエストペイロードを返します。レスポンスハンドラーは、実行されたリクエストの結果を含むペイロードをデータソースから受け取ります。レスポンスハンドラーは、ペイロードを 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 つの関数で構成されるパイプラインリゾルバーがあるとします。以下のリストでは、リゾルバーが呼び出されたときの実行フローを表しています。 1. パイプラインリゾルバーリクエストハンドラー 1. 関数 1: 関数リクエストハンドラー 1. 関数 1: データソースの呼び出し 1. 関数 1: 関数レスポンスハンドラー 1. 関数 2: 関数リクエストハンドラー 1. 関数 2: データソースの呼び出し 1. 関数 2: 関数レスポンスハンドラー 1. パイプラインリゾルバーレスポンスハンドラー ![\[GraphQL request flow diagram showing interactions between request, data sources, and response components.\]](http://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/images/appsync-js-resolver-logic.png) ### 便利な `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 ランタイム機能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)」を参照してください。 #### util.appendError `util.appendError` は `util.error()` と似ていますが、ハンドラーの評価を中断しないという大きな違いがあります。代わりに、フィールドにエラーがあったことを通知します。ただし、ハンドラーを評価し、データを引き続き返すことも可能です。関数内で `util.appendError` を使用しても、パイプラインの実行フローは中断されません。詳細やその他の `util.error` シグネチャについては、「[リゾルバーと関数の JavaScript ランタイム機能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)」を参照してください。 #### 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` という名前の one AWS AppSync 関数を使用できます。項目をクエリするリゾルバーについては、リゾルバーのパイプラインに関数を追加し、使用するクエリインデックスを指定するだけです。ロジックを再実装する必要はありません。 ## 補足トピック **トピック** + [Amazon DynamoDB を使用したパイプラインリゾルバーの例](https://docs.aws.amazon.com/appsync/latest/devguide/writing-code.html) + [`APPSYNC_JS` ランタイムのユーティリティの設定](https://docs.aws.amazon.com/appsync/latest/devguide/utility-resolvers.html) + [`APPSYNC_JS` ランタイムのバンドル、TypeScript、ソースマップ](https://docs.aws.amazon.com/appsync/latest/devguide/additional-utilities.html) + [リゾルバーと関数ハンドラーのテスト](https://docs.aws.amazon.com/appsync/latest/devguide/test-resolvers.html) + [VTL から JavaScript への移行](https://docs.aws.amazon.com/appsync/latest/devguide/migrating-resolvers.html) + [データソースへの直接アクセスと Lambda データソース経由のプロキシのどちらかを選択する](https://docs.aws.amazon.com/appsync/latest/devguide/choosing-data-source.html) # Amazon DynamoDB を使用したパイプラインリゾルバーの例 次の GraphQL クエリを使用して、Amazon DynamoDB データソースから `Post` 型を返す `getPost(id:ID!)` という名前のフィールドにパイプラインリゾルバーをアタッチするとします。 ``` getPost(id:1){ id title content } ``` まず、以下のコードで簡単なリゾルバーを `Query.getPost` にアタッチします。これは単純なリゾルバーコードの例です。リクエストハンドラーにはロジックは定義されておらず、レスポンスハンドラーは最後の関数の結果を返すだけです。 ``` /** * Invoked **before** the request handler of the first AppSync function in the pipeline. * The resolver `request` handler allows to perform some preparation logic * before executing the defined functions in your pipeline. * @param ctx the context object holds contextual information about the function invocation. */ export function request(ctx) { return {} } /** * Invoked **after** the response handler of the last AppSync function in the pipeline. * The resolver `response` handler allows to perform some final evaluation logic * from the output of the last function to the expected GraphQL field type. * @param ctx the context object holds contextual information about the function invocation. */ export function response(ctx) { return ctx.prev.result } ``` 次に、データソースから投稿項目を取得する関数 `GET_ITEM` を定義します。 ``` import { util } from '@aws-appsync/utils' import * as ddb from '@aws-appsync/utils/dynamodb' /** * Request a single item from the attached DynamoDB table datasource * @param ctx the context object holds contextual information about the function invocation. */ export function request(ctx) { const { id } = ctx.args return ddb.get({ key: { id } }) } /** * Returns the result * @param ctx the context object holds contextual information about the function invocation. */ export function response(ctx) { const { error, result } = ctx if (error) { return util.appendError(error.message, error.type, result) } return ctx.result } ``` リクエスト中にエラーが発生した場合、関数のレスポンスハンドラーは、呼び出し元のクライアントに返されるエラーを GraphQL レスポンスに追加します。`GET_ITEM` 関数をリゾルバー関数リストに追加します。クエリを実行すると、`GET_ITEM`関数のリクエストハンドラーは DynamoDB モジュールが提供する utils AWS AppSyncを使用して、 をキー`id`として使用して`DynamoDBGetItem`リクエストを作成します。 は適切な`GetItem`オペレーション`ddb.get({ key: { id } })`を生成します。 ``` { "operation" : "GetItem", "key" : { "id" : { "S" : "1" } } } ``` AWS AppSync は リクエストを使用して Amazon DynamoDB からデータを取得します。データが返されると、`GET_ITEM` 関数のレスポンスハンドラーによって処理されます。レスポンスハンドラーはエラーをチェックして結果を返します。 ``` { "result" : { "id": 1, "title": "hello world", "content": "" } } ``` 最後に、リゾルバーのレスポンスハンドラーは結果を直接返します。 ## エラーの使用 リクエスト中に関数でエラーが発生した場合、そのエラーは `ctx.error` の関数レスポンスハンドラーで利用できるようになります。`util.appendError` ユーティリティを使用して GraphQL レスポンスにエラーを追加できます。stash を使用すると、パイプライン内の他の関数がエラーを利用できるようになります。次の例を参照してください。 ``` /** * Returns the result * @param ctx the context object holds contextual information about the function invocation. */ export function response(ctx) { const { error, result } = ctx; if (error) { if (!ctx.stash.errors) ctx.stash.errors = [] ctx.stash.errors.push(ctx.error) return util.appendError(error.message, error.type, result); } return ctx.result; } ``` # `APPSYNC_JS` ランタイムのユーティリティの設定 AWS AppSync には、 `APPSYNC_JS`ランタイムを使用したリゾルバーの開発に役立つ 2 つのライブラリが用意されています。 + `@aws-appsync/eslint-plugin` - 開発中に問題を迅速に発見して修正します。 + `@aws-appsync/utils` - コードエディターで型検証とオートコンプリートを行います。 ## eslint プラグインの設定 [ESLint](https://eslint.org/) は、コードを静的に分析して問題をすばやく見つけるツールです。ESLint は継続的インテグレーションパイプラインの一部として実行できます。`@aws-appsync/eslint-plugin`は、`APPSYNC_JS` ランタイムを利用する際にコード内の無効な構文を検出する ESLint プラグインです。このプラグインを使用すると、変更をクラウドにプッシュしなくても、開発中にコードに関するフィードバックを迅速に得ることができます。 `@aws-appsync/eslint-plugin` には、開発中に使用できる 2 つのルールセットが用意されています。 **"plugin:@aws-appsync/base"** は、プロジェクトで活用できる基本ルールセットを設定します。 | ルール | 説明 | | --- | --- | | 非同期 | 非同期のプロセスと Promise はサポートされていません。 | | no-await | 非同期のプロセスと Promise はサポートされていません。 | | no-classes | ルールはサポートされていません。 | | no-for | for はサポートされていない (サポートされている for-in および for-of は除く) | | no-continue | continue はサポートされていません。 | | no-generators | ジェネレータはサポートされていません。 | | no-yield | yield はサポートされていません。 | | no-labels | ラベルはサポートされていません。 | | no-this | this キーワードはサポートされていません。 | | no-try | try/catch 構造はサポートされていません。 | | no-while | while ループはサポートされていません。 | | no-disallowed-unary-operators | \$1\$1、-- および \$1 単項演算子は使用できません。 | | no-disallowed-binary-operators | instanceof 演算子は使用できません。 | | no-promise | 非同期のプロセスと Promise はサポートされていません。 | **"plugin:@aws-appsync/recommended"** にはいくつかの追加のルールがありますが、プロジェクトに TypeScript 構成を追加する必要もあります。 | ルール | 説明 | | --- | --- | | no-recursion | 再帰的な関数呼び出しは許可されません。 | | no-disallowed-methods | 使用できないメソッドもあります。サポートされている組み込み関数の全セットについては、[リファレンス](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)を参照してください。 | | no-function-passing | 関数を関数の引数として関数に渡すことはできません。 | | no-function-reassign | 関数は再割り当てできません。 | | no-function-return | 関数を関数の戻り値にすることはできません。 | プラグインをプロジェクトに追加するには、「[ESLint 入門](https://eslint.org/docs/latest/user-guide/getting-started#installation-and-usage)」のインストールと使用手順に従ってください。次に、プロジェクトパッケージマネージャー (npm、yarn、pnpm など) を使用してプロジェクトに[プラグイン](https://www.npmjs.com/package/@aws-appsync/eslint-plugin)をインストールします。 ``` $ npm install @aws-appsync/eslint-plugin ``` `.eslintrc.{js,yml,json}` ファイルで **"plugin:@aws-appsync/base"**または **"plugin:@aws-appsync/recommended"**を `extends` プロパティに追加します。以下のスニペットは JavaScript の基本的なサンプル `.eslintrc` 設定です。 ``` { "extends": ["plugin:@aws-appsync/base"] } ``` **"plugin:@aws-appsync/recommended"** ルールセットを使用するには、必要な依存関係をインストールします。 ``` $ npm install -D @typescript-eslint/parser ``` `.eslintrc.js` ファイルを作成するには ``` { "parser": "@typescript-eslint/parser", "parserOptions": { "ecmaVersion": 2018, "project": "./tsconfig.json" }, "extends": ["plugin:@aws-appsync/recommended"] } ``` # `APPSYNC_JS` ランタイムのバンドル、TypeScript、ソースマップ TypeScript は、型の安全性と早期エラー検出を提供することで AWS AppSync 開発を強化します。TypeScript コードをローカルで記述し、`APPSYNC_JS` ランタイムで使用する前に JavaScript にトランスパイルできます。このプロセスは、TypeScript のインストールと `APPSYNC_JS` 環境の tsconfig.json の設定から始まります。その後、esbuild などのバンドルツールを使用して、コードをコンパイルしてバンドルできます。Amplify CLI は GraphQL スキーマからタイプを生成し、リゾルバーコードでこれらのタイプを使用できます。 リゾルバーと関数コードでは、`APPSYNC_JS` 要件を満たす限り、カスタムライブラリと外部ライブラリの両方を活用できます。バンドルツールは、コードを 1 つのファイルに結合して使用します AWS AppSync。ソースマップを含めると、デバッグに役立ちます。 ## ライブラリの活用とコードのバンドル リゾルバーと関数コードでは、`APPSYNC_JS` 要件を満たす限り、カスタムライブラリと外部ライブラリの両方を活用できます。これにより、アプリケーション内の既存のコードを再利用できます。複数のファイルで定義されたライブラリを使用するには、[esbuild](https://esbuild.github.io/) などのバンドルツールを使用してコードを 1 つのファイルに結合し、リ AWS AppSync ゾルバーまたは関数に保存する必要があります。 コードをバンドルするときは、次の点に留意してください。 + `APPSYNC_JS` は、ECMAScript モジュール (ESM) のみをサポートします。 + `@aws-appsync/*` モジュールは `APPSYNC_JS` に統合されており、バンドルすべきではありません。 + `APPSYNC_JS` ランタイム環境は、コードがブラウザ環境では実行されないという点で NodeJS に似ています。 + オプションでソースマップを含めることができます。ただし、ソースコンテンツを含めないでください。 ソースマップの詳細については、「[ソースマップの使用](#source-maps)」を参照してください。 例えば、`src/appsync/getPost.resolver.js` にあるリゾルバーコードをバンドルするには、次の esbuild CLI コマンドを使用することができます。 ``` $ esbuild --bundle \ --sourcemap=inline \ --sources-content=false \ --target=esnext \ --platform=node \ --format=esm \ --external:@aws-appsync/utils \ --outdir=out/appsync \ src/appsync/getPost.resolver.js ``` ## コードのビルドと TypeScript での作業 [TypeScript](https://www.typescriptlang.org/) は Microsoft が開発したプログラミング言語で、TypeScript タイピングシステムとともに JavaScript のすべての機能を備えています。TypeScript を使用すると、タイプセーフなコードを記述し、ビルド時にコードを AWS AppSyncに保存する前にエラーやバグを検出できます。`@aws-appsync/utils` パッケージは完全に型指定されています。 `APPSYNC_JS` ランタイムは TypeScript を直接サポートしていません。コードを AWS AppSyncに保存する前に、まず TypeScript コードを `APPSYNC_JS` ランタイムがサポートする JavaScript コードにトランスパイルする必要があります。TypeScript を使用してローカル統合開発環境 (IDE) にコードを記述できますが、 AWS AppSync コンソールで TypeScript コードを作成することはできません。 開始する前に、プロジェクトに [TypeScript](https://www.typescriptlang.org/download) がインストールされていることを確認してください。次に、[TSConfig](https://www.typescriptlang.org/tsconfig) を使用して `APPSYNC_JS` ランタイムと連携するように TypeScript のトランスコンパイル設定を構成します。使用できる基本 `tsconfig.json` ファイルの例を次に示します。 ``` // tsconfig.json { "compilerOptions": { "target": "esnext", "module": "esnext", "noEmit": true, "moduleResolution": "node", } } ``` その後、esbuild などのバンドルツールを使用して、コードをコンパイルしてバンドルできます。たとえば、 にある AWS AppSync コードを持つプロジェクトの場合`src/appsync`、次のコマンドを使用してコードをコンパイルしてバンドルできます。 ``` $ esbuild --bundle \ --sourcemap=inline \ --sources-content=false \ --target=esnext \ --platform=node \ --format=esm \ --external:@aws-appsync/utils \ --outdir=out/appsync \ src/appsync/**/*.ts ``` ### Amplify Codegen を使用する [Amplify CLI](https://docs.amplify.aws/cli/) を使用してスキーマのタイプを生成できます。`schema.graphql` ファイルが置かれているディレクトリから以下のコマンドを実行し、プロンプトを確認して codegen を設定します。 ``` $ npx @aws-amplify/cli codegen add ``` 特定の状況 (スキーマの更新時など) で codegen を再生成するには、以下のコマンドを実行します。 ``` $ npx @aws-amplify/cli codegen ``` その後、生成された型をリゾルバーコードで使用できます。例として、次のスキーマがあるとします。 ``` type Todo { id: ID! title: String! description: String } type Mutation { createTodo(title: String!, description: String): Todo } type Query { listTodos: Todo } ``` 生成された型は、次の例の AWS AppSync 関数で使用できます。 ``` import { Context, util } from '@aws-appsync/utils' import * as ddb from '@aws-appsync/utils/dynamodb' import { CreateTodoMutationVariables, Todo } from './API' // codegen export function request(ctx: Context) { ctx.args.description = ctx.args.description ?? 'created on ' + util.time.nowISO8601() return ddb.put({ key: { id: util.autoId() }, item: ctx.args }) } export function response(ctx) { return ctx.result as Todo } ``` ### TypeScript でのジェネリックの使用 ジェネリックスは用意されているいくつかの型で使用できます。例えば、以下のスニペットは `Todo` タイプです。 ``` export type Todo = { __typename: "Todo", id: string, title: string, description?: string | null, }; ``` `Todo` を利用するサブスクリプション用のリゾルバーを書くことができます。お使いの IDE では、型定義とオートコンプリートのヒントを参考にして、`toSubscriptionFilter` 変換ユーティリティを適切に使用してください。 ``` import { util, Context, extensions } from '@aws-appsync/utils' import { Todo } from './API' export function request(ctx: Context) { return {} } export function response(ctx: Context) { const filter = util.transform.toSubscriptionFilter({ title: { beginsWith: 'hello' }, description: { contains: 'created' }, }) extensions.setSubscriptionFilter(filter) return null } ``` ## バンドルのリンティング `esbuild-plugin-eslint` プラグインをインポートすることで、バンドルを自動的にリントできます。その後、eslint 機能を有効にする `plugins` 値を指定することで有効化できます。以下は、esbuild JavaScript API を `build.mjs` というファイルで使用しているスニペットです。 ``` /* eslint-disable */ import { build } from 'esbuild' import eslint from 'esbuild-plugin-eslint' import glob from 'glob' const files = await glob('src/**/*.ts') await build({ format: 'esm', target: 'esnext', platform: 'node', external: ['@aws-appsync/utils'], outdir: 'dist/', entryPoints: files, bundle: true, plugins: [eslint({ useEslintrc: true })], }) ``` ## ソースマップの使用 JavaScript コードでインラインソースマップ (`sourcemap`) を提供できます。ソースマップは、JavaScript または TypeScript コードをバンドルしていて、入力ソースファイルへの参照をログやランタイム JavaScript エラーメッセージに表示したい場合に便利です。 `sourcemap` はコードの最後に表示する必要があります。以下の形式の 1 行のコメントで定義されます。 ``` //# sourceMappingURL=data:application/json;base64, ``` 例を示します。 ``` //# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsibGliLmpzIiwgImNvZGUuanMiXSwKICAibWFwcGluZ3MiOiAiO0FBQU8sU0FBUyxRQUFRO0FBQ3RCLFNBQU87QUFDVDs7O0FDRE8sU0FBUyxRQUFRLEtBQUs7QUFDM0IsU0FBTyxNQUFNO0FBQ2Y7IiwKICAibmFtZXMiOiBbXQp9Cg== ``` ソースマップは esbuild で作成できます。以下の例は、コードをビルドしてバンドルするときに esbuild JavaScript API を使用してインラインソースマップを組み込む方法を示しています。 ``` /* eslint-disable */ import { build } from 'esbuild' import eslint from 'esbuild-plugin-eslint' import glob from 'glob' const files = await glob('src/**/*.ts') await build({ sourcemap: 'inline', sourcesContent: false, format: 'esm', target: 'esnext', platform: 'node', external: ['@aws-appsync/utils'], outdir: 'dist/', entryPoints: files, bundle: true, plugins: [eslint({ useEslintrc: true })], }) ``` 特に、`sourcemap` および `sourcesContent` オプションでは、各ビルドの最後にソースマップをインラインで追加し、ソースコンテンツは含めないように指定しています。慣例として、ソースコンテンツは `sourcemap` には含めないことをお勧めします。これを無効にするには、`sources-content` を `false` に設定します。 ソースマップの仕組みを説明するために、リゾルバーコードがヘルパーライブラリのヘルパー関数を参照する次の例を確認してください。このコードには、リゾルバーコードとヘルパーライブラリーのログステートメントが含まれています。 **./src/default.resolver.ts** (自身のリゾルバー) ``` import { Context } from '@aws-appsync/utils' import { hello, logit } from './helper' export function request(ctx: Context) { console.log('start >') logit('hello world', 42, true) console.log('< end') return 'test' } export function response(ctx: Context): boolean { hello() return ctx.prev.result } ``` **.src/helper.ts** (ヘルパーファイル) ``` export const logit = (...rest: any[]) => { // a special logger console.log('[logger]', ...rest.map((r) => `<${r}>`)) } export const hello = () => { // This just returns a simple sentence, but it could do more. console.log('i just say hello..') } ``` リゾルバーファイルをビルドしてバンドルすると、リゾルバーコードにはインラインソースマップが含まれます。リゾルバーを実行すると、CloudWatch ログに次のエントリが表示されます。 ![\[CloudWatch log entries showing resolver code execution with inline source map information.\]](http://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/images/cloudwatch-sourcemap.jpeg) CloudWatch ログのエントリを見ると、2 つのファイルの機能がバンドルされ、同時に実行されていることがわかります。各ファイルの元のファイル名もログにはっきりと反映されています。 # でのリゾルバーと関数ハンドラーのテスト AWS AppSync `EvaluateCode` API コマンドを使用すると、コードをリゾルバーまたは関数に保存する前に、モックデータを使用してリゾルバーと関数ハンドラーをリモートでテストできます。コマンドを使い始めるには、ポリシーに `appsync:evaluatecode` アクセス許可を追加していることを確認してください。例えば、次のようになります。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "appsync:evaluateCode", "Resource": "arn:aws:appsync:us-east-1:111122223333:*" } ] } ``` ------ [AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/index.html) または [AWS SDK](https://aws.amazon.com/tools/) を使用してコマンドを活用できます。例えば、CLI を使用してコードをテストするには、ファイルを指定し、コンテキストを指定し、評価するハンドラーを指定するだけです。 ``` aws appsync evaluate-code \ --code file://code.js \ --function request \ --context file://context.json \ --runtime name=APPSYNC_JS,runtimeVersion=1.0.0 ``` レスポンスには、ハンドラーから返されたペイロードを含む `evaluationResult` が含まれます。また、評価中にハンドラーによって生成されたログのリストを保持する `logs` オブジェクトも含まれています。これにより、コード実行のデバッグが容易になり、評価に関する情報を確認してトラブルシューティングに役立てることができます。例えば、次のようになります。 ``` { "evaluationResult": "{\"operation\":\"PutItem\",\"key\":{\"id\":{\"S\":\"record-id\"}},\"attributeValues\":{\"owner\":{\"S\":\"John doe\"},\"expectedVersion\":{\"N\":2},\"authorId\":{\"S\":\"Sammy Davis\"}}}", "logs": [ "INFO - code.js:5:3: \"current id\" \"record-id\"", "INFO - code.js:9:3: \"request evaluated\"" ] } ``` 評価結果は JSON として解析でき、以下のようになります。 ``` { "operation": "PutItem", "key": { "id": { "S": "record-id" } }, "attributeValues": { "owner": { "S": "John doe" }, "expectedVersion": { "N": 2 }, "authorId": { "S": "Sammy Davis" } } } ``` SDK を使用すると、テストスイートのテストを簡単に組み込んで、コードの動作を検証できます。この例では [Jest テストフレームワーク](https://jestjs.io/)を使用していますが、どのテストスイートでも機能します。次のスニペットは、仮説検証の実行を示しています。評価レスポンスは有効な JSON であることを想定しているので、`JSON.parse`を使用して文字列レスポンスから JSON を取得することに注意してください。 ``` const AWS = require('aws-sdk') const fs = require('fs') const client = new AWS.AppSync({ region: 'us-east-2' }) const runtime = {name:'APPSYNC_JS',runtimeVersion:'1.0.0') test('request correctly calls DynamoDB', async () => { const code = fs.readFileSync('./code.js', 'utf8') const context = fs.readFileSync('./context.json', 'utf8') const contextJSON = JSON.parse(context) const response = await client.evaluateCode({ code, context, runtime, function: 'request' }).promise() const result = JSON.parse(response.evaluationResult) expect(result.key.id.S).toBeDefined() expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname) }) ``` これにより、次のような結果が得られます。 ``` Ran all test suites. > jest PASS ./index.test.js ✓ request correctly calls DynamoDB (543 ms) Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 totalTime: 1.511 s, estimated 2 s ``` # での VTL から JavaScript への移行 AWS AppSync AWS AppSync を使用すると、VTL または JavaScript を使用してリゾルバーと関数のビジネスロジックを記述できます。どちらの言語でも、データソースの操作方法を AWS AppSync サービスに指示するロジックを記述します。VTL では、有効な JSON エンコードされた文字列に評価される必要があるマッピングテンプレートを作成します。JavaScript では、オブジェクトを返すリクエストハンドラーとレスポンスハンドラーを記述します。JSON エンコードされた文字列を返すことはありません。 例えば、次の VTL マッピングテンプレートを使用して Amazon DynamoDB アイテムを取得します。 ``` { "operation": "GetItem", "key": { "id": $util.dynamodb.toDynamoDBJson($ctx.args.id), } } ``` このユーティリティ `$util.dynamodb.toDynamoDBJson` は、JSON エンコードされた文字列を返します。`$ctx.args.id` を `` に設定すると、テンプレートは有効な JSON エンコードされた文字列と評価されます。 ``` { "operation": "GetItem", "key": { "id": {"S": ""}, } } ``` JavaScript を使用する場合、コード内に JSON でエンコードされた生の文字列を出力する必要はなく、`toDynamoDBJson`のようなユーティリティを使用する必要もありません。上記のマッピングテンプレートと同等の例を以下に示します。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { return { operation: 'GetItem', key: {id: util.dynamodb.toDynamoDB(ctx.args.id)} }; } ``` 別の方法としては、`util.dynamodb.toMapValues` を使用する方法があります。これは、値のオブジェクトを処理する場合に推奨される方法です。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { return { operation: 'GetItem', key: util.dynamodb.toMapValues({ id: ctx.args.id }), }; } ``` これは以下のように評価されます。 ``` { "operation": "GetItem", "key": { "id": { "S": "" } } } ``` **注記** DynamoDB モジュールを DynamoDB データソースで使用することをお勧めします。 ``` import * as ddb from '@aws-appsync/utils/dynamodb' export function request(ctx) { ddb.get({ key: { id: ctx.args.id } }) } ``` 別の例として、次のマッピングテンプレートを使用して Amazon DynamoDB データソースに項目を配置します。 ``` { "operation" : "PutItem", "key" : { "id": $util.dynamodb.toDynamoDBJson($util.autoId()), }, "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args) } ``` このマッピングテンプレート文字列を評価すると、有効な JSON でエンコードされた文字列が生成される必要があります。JavaScript を使用する場合、コードはリクエストオブジェクトを直接返します。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id = util.autoId(), ...values } = ctx.args; return { operation: 'PutItem', key: util.dynamodb.toMapValues({ id }), attributeValues: util.dynamodb.toMapValues(values), }; } ``` 以下として評価されます。 ``` { "operation": "PutItem", "key": { "id": { "S": "2bff3f05-ff8c-4ed8-92b4-767e29fc4e63" } }, "attributeValues": { "firstname": { "S": "Shaggy" }, "age": { "N": 4 } } } ``` **注記** DynamoDB モジュールを DynamoDB データソースで使用することをお勧めします。 ``` import { util } from '@aws-appsync/utils' import * as ddb from '@aws-appsync/utils/dynamodb' export function request(ctx) { const { id = util.autoId(), ...item } = ctx.args return ddb.put({ key: { id }, item }) } ``` # データソースへの直接アクセスと Lambda データソース経由のプロキシのどちらかを選択する AWS AppSync と `APPSYNC_JS`ランタイムを使用すると、 AWS AppSync 関数を使用してデータソースにアクセスすることで、カスタムビジネスロジックを実装する独自のコードを記述できます。これにより、追加の計算 AWS サービスやインフラストラクチャをデプロイすることなく、Amazon DynamoDB、Aurora Serverless、OpenSearch Service、HTTP APIs、その他の サービスなどのデータソースと直接やり取りすることが容易になります。 AWS AppSync では、Lambda データソースを設定することで、 AWS Lambda 関数の操作も簡単です。Lambda データソースを使用すると、 AWS Lambdaのフルセット機能を使用して複雑なビジネスロジックを実行し、GraphQL リクエストを解決できます。ほとんどの場合、ターゲットデータソースに直接接続された AWS AppSync 関数は、必要なすべての機能を提供します。`APPSYNC_JS` ランタイムでサポートされていない複雑なビジネスロジックを実装する必要がある状況では、Lambda データソースをプロキシとして使用してターゲットデータソースとやり取りできます。 | | | | | --- |--- |--- | | | データソースの直接統合 | プロキシとしての Lambda データソース | | ユースケース | AWS AppSync functions interact directly with API data sources. | AWS AppSync functions call Lambdas that interact with API data sources. | | Runtime | APPSYNC\$1JS (JavaScript) | サポートされる Lambda ランタイム | | Maximum size of code | AWS AppSync 関数あたり 32,000 文字 | 50 MB (zip 圧縮済み、直接アップロード) | | External modules | 制限あり-APPSYNC\$1JS がサポートしている機能のみ | はい | | Call any AWS service | はい - AWS AppSync HTTP データソースの使用 | はい - AWS SDK の使用 | | Access to the request header | はい | あり | | Network access | なし | あり | | File system access | なし | はい | | Logging and metrics | はい | はい | | Build and test entirely within AppSync | あり | なし | | Cold start | いいえ | No - プロビジョニング済み同時実行 | | Auto-scaling | はい - AWS AppSync によって透過的に | Yes - Lambda で設定されているとおり | | Pricing | 追加料金なし | Lambda の使用に対して課金 | ターゲットデータソースと直接統合するAWS AppSync 関数は、次のようなユースケースに最適です。 + Amazon DynamoDB、Aurora サーバーレス、OpenSearch サービスとのやり取り + HTTP API とのやりとりと受信ヘッダーの受け渡し + HTTP データソースを使用して AWS サービスとやり取りする (指定されたデータソースロールを使用してリクエスト AWS AppSync に自動的に署名する) + データソースにアクセスする前のアクセス制御の実装 + リクエストに応答する前に、取得したデータをフィルター処理する。 + リゾルバーパイプラインでの AWS AppSync 関数のシーケンシャル実行によるシンプルなオーケストレーションの実装 + クエリとミューテーションにおけるキャッシュ接続とサブスクリプション接続の制御。 Lambda データソースをプロキシとして使用するAWS AppSync 関数は、次のようなユースケースに最適です。 + JavaScript または Velocity TL (VTL) 以外の言語を使用する + CPU またはメモリの調整と制御によるパフォーマンスの最適化 + サードパーティ製ライブラリのインポートまたは `APPSYNC_JS` でサポートされていない機能の使用が必要 + 複数のネットワークリクエストを行ったり、クエリを実行するためにファイルシステムにアクセスしたりする + [バッチ設定](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-lambda-js.html)を使用してリクエストをバッチ処理する。 # AWS AppSync JavaScript リゾルバーコンテキストオブジェクトリファレンス AWS AppSync は、リクエストハンドラーとレスポンスハンドラーを操作するための一連の変数と関数を定義します。これにより、GraphQL を使用してデータの論理的オペレーションが容易になります。このドキュメントでは、それらの関数について説明し、例を示します。 ## `context` へのアクセス リクエスト&レスポンスハンドラーの `context` 引数は、リゾルバー呼び出しのコンテキスト情報をすべて保持するオブジェクトです。この変数の構造は次のとおりです。 ``` type Context = { arguments: any; args: any; identity: Identity; source: any; error?: { message: string; type: string; }; stash: any; result: any; prev: any; request: Request; info: Info; }; ``` **注記** `context` オブジェクトは `ctx` と呼ばれることがよくあります。 `context` オブジェクトの各フィールドは次のように定義されます。 ### `context` フィールド ** `arguments` ** このフィールドのすべての GraphQL 引数を含むマップ。 ** `identity` ** 呼び出し元に関する情報を含むオブジェクト。このフィールドの構造の詳細については、「[ID](#aws-appsync-resolver-context-reference-identity-js)」を参照してください。 ** `source` ** 親フィールドの解像度を含むマップ。 ** `stash` ** stash は、リゾルバーと関数ハンドラー内部で使用可能になるオブジェクトです。リゾルバーを 1 回実行すると、同じ stash オブジェクトが存続します。つまり、stash を使用して、リクエストとレスポンスのハンドラー間、およびパイプラインリゾルバーの関数間で、任意のデータを渡すことができます。 stash 全体を削除または置換することはできませんが、スタッシュのプロパティを追加、更新、削除、および読み取ることはできます。 以下のコード例のいずれかを変更することで、stash にアイテムを追加できます。 ``` //Example 1 ctx.stash.newItem = { key: "something" } //Example 2 Object.assign(ctx.stash, {key1: value1, key2: value}) ``` 以下のコードを変更することで、stashからアイテムを削除できます。 ``` delete ctx.stash.key ``` ** `result` ** このリゾルバーの結果用のコンテナ。このフィールドは、レスポンスハンドラーのみが使用できます。 例えば、次のクエリの `author` フィールドを解決する場合: ``` query { getPost(id: 1234) { postId title content author { id name } } } ``` そうすれば、レスポンスハンドラーが評価されるときに `context` 変数全体が使用可能になります。 ``` { "arguments" : { id: "1234" }, "source": {}, "result" : { "postId": "1234", "title": "Some title", "content": "Some content", "author": { "id": "5678", "name": "Author Name" } }, "identity" : { "sourceIp" : ["x.x.x.x"], "userArn" : "arn:aws:iam::123456789012:user/appsync", "accountId" : "666666666666", "user" : "AIDAAAAAAAAAAAAAAAAAA" } } ``` ** `prev.result` ** パイプラインリゾルバーで実行された前回のオペレーションの結果を表します。 前のオペレーションがパイプラインリゾルバーのリクエストハンドラーであった場合、`ctx.prev.result` はテンプレートの評価結果を表し、パイプライン内の最初の関数に使用可能になります。 前のオペレーションが最初の関数であった場合、`ctx.prev.result` は最初の関数レスポンスハンドラーの評価結果を表し、パイプライン内の 2 番目の関数に使用可能になります。 前のオペレーションが最後の関数であった場合、`ctx.prev.result` は最後の関数の評価結果を表し、パイプラインリゾルバーのレスポンスハンドラーに使用可能になります。 ** `info` ** GraphQL リクエストに関する情報を含むオブジェクト。このフィールドの構造については、「[情報](#aws-appsync-resolver-context-reference-info-js)」を参照してください。 ### アイデンティティ `identity` セクションには、呼び出し元に関する情報が含まれています。このセクションのシェイプは、使用する AWS AppSync API の認可タイプによって異なります。 AWS AppSync セキュリティオプションの詳細については、[「認可と認証](security-authz.md#aws-appsync-security)」を参照してください。 ** `API_KEY` authorization** `identity` フィールドは入力されていません。 **`AWS_LAMBDA` authorization** `identity` の形式は次のとおりです。 ``` type AppSyncIdentityLambda = { resolverContext: any; }; ``` `identity`には、リクエストを承認する Lambda 関数によって返されるのと同じ `resolverContext` コンテンツを含む `resolverContext` キーが含まれています。 ** `AWS_IAM` authorization** `identity` の形式は次のとおりです。 ``` type AppSyncIdentityIAM = { accountId: string; cognitoIdentityPoolId: string; cognitoIdentityId: string; sourceIp: string[]; username: string; userArn: string; cognitoIdentityAuthType: string; cognitoIdentityAuthProvider: string; }; ``` ** `AMAZON_COGNITO_USER_POOLS` authorization** `identity` の形式は次のとおりです。 ``` type AppSyncIdentityCognito = { sourceIp: string[]; username: string; groups: string[] | null; sub: string; issuer: string; claims: any; defaultAuthStrategy: string; }; ``` 各フィールドは次のように定義されています。 ** `accountId` ** 発信者の AWS アカウント ID。 ** `claims` ** ユーザーが持っているクレーム。 ** `cognitoIdentityAuthType` ** ID タイプに基づいて認証済みまたは未認証のいずれか。 ** `cognitoIdentityAuthProvider` ** リクエストの署名に使用された認証情報の取得先となる外部 ID プロバイダ情報のカンマ区切りリスト。 ** `cognitoIdentityId` ** リクエストを行う呼び出し元の Amazon Cognito 認証 ID。 ** `cognitoIdentityPoolId` ** 呼び出し元に関連付けられている Amazon Cognito ID プール。 ** `defaultAuthStrategy` ** この呼び出し元のデフォルトの認可方法 (`ALLOW`または`DENY`)。 ** `issuer` ** トークン発行者。 ** `sourceIp` ** が AWS AppSync 受信する発信者の送信元 IP アドレス。リクエストに `x-forwarded-for` ヘッダーが含まれていない場合、ソース IP の値には TCP 接続からの 1 つの IP アドレスのみが含まれます。リクエストに `x-forwarded-for` ヘッダーが含まれている場合、ソース IP は、TCP 接続からの IP アドレスと `x-forwarded-for` ヘッダーからの IP アドレスのリストです。 ** `sub` ** 認証されたユーザーの UUID。 ** `user` ** IAM ユーザー。 ** `userArn` ** IAM ユーザーの Amazon リソースネーム (ARN)。 ** `username` ** 認証されたユーザーのユーザー名です。`AMAZON_COGNITO_USER_POOLS` 認可の場合、*username* の値は *cognito:username* 属性の値です。`AWS_IAM` 認可の場合、*ユーザー名*の値は AWS ユーザープリンシパルの値です。Amazon Cognito アイデンティティプールから発行された認証情報による IAM 認可を使用されている場合は、`cognitoIdentityId`の使用をお勧めします。 ### リクエストヘッダーへのアクセス AWS AppSync は、クライアントからのカスタムヘッダーの受け渡しと、 を使用した GraphQL リゾルバーでのカスタムヘッダーへのアクセスをサポートしています`ctx.request.headers`。データソースへデータの挿入や認可チェックなどのアクションでそのヘッダーの値を使用できます。次の例のようにコマンドラインから API キーで `$curl` を使用して、1 つまたは複数のリクエストヘッダーを使用できます。 **単一ヘッダーの例** 次のように、`custom` のヘッダーに `nadia` の値を設定しているとします。 ``` curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https:///graphql ``` この値には `ctx.request.headers.custom` を使用してアクセスできます。たとえば、DynamoDB に対する VTL は次のようになります。 ``` "custom": util.dynamodb.toDynamoDB(ctx.request.headers.custom) ``` **複数ヘッダーの例** 1 つのリクエストで複数のヘッダーを渡して、リゾルバーのハンドラーでそれらのヘッダーにアクセスすることもできます。たとえば、次のように `custom` ヘッダーに 2 つの値が設定されるとします。 ``` curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https:///graphql ``` それらのヘッダーに配列としてアクセスできます (例: `ctx.request.headers.custom[1]`)。 **注記** AWS AppSync は の Cookie ヘッダーを公開しません`ctx.request.headers`。 ### リクエストカスタムドメイン名にアクセスする AWS AppSync は、APIs の GraphQL およびリアルタイムエンドポイントにアクセスするために使用できるカスタムドメインの設定をサポートしています。カスタムドメイン名を使用してリクエストを行う場合は、`ctx.request.domainName` を使用してドメイン名を取得できます。 デフォルトの GraphQL エンドポイントドメイン名を使用する場合、値は `null` です。 ### [情報] `info` セクションには、GraphQL リクエストに関する情報が含まれています。このセクションには、次の形式が含まれます。 ``` type Info = { fieldName: string; parentTypeName: string; variables: any; selectionSetList: string[]; selectionSetGraphQL: string; }; ``` 各フィールドは次のように定義されています。 ** `fieldName` ** 現在解決中のフィールドの名前。 ** `parentTypeName` ** 現在解決中のフィールドの親タイプの名前。 ** `variables` ** GraphQLリクエストに渡されるすべての変数を保持するマップ。 ** `selectionSetList` ** GraphQL 選択セット内のフィールドのリスト表現。エイリアスされたフィールドは、フィールド名ではなく、エイリアス名によってのみ参照されます。次の例で詳細を示します。 ** `selectionSetGraphQL` ** 選択セットの文字列表現。GraphQL スキーマ定義言語 (SDL) としてフォーマットされます。フラグメントは選択セットにマージされませんが、次の例に示すように、インラインフラグメントは保持されます。 **注記** `JSON.stringify` では文字列のシリアル化には `selectionSetGraphQL` および `selectionSetList` は含まれません。これらのプロパティは直接参照する必要があります。 たとえば、次のクエリの `getPost` フィールドを解決する場合: ``` query { getPost(id: $postId) { postId title secondTitle: title content author(id: $authorId) { authorId name } secondAuthor(id: "789") { authorId } ... on Post { inlineFrag: comments: { id } } ... postFrag } } fragment postFrag on Post { postFrag: comments: { id } } ``` ハンドラーを処理する際に使用可能な完全な `ctx.info` 変数は次のようになります。 ``` { "fieldName": "getPost", "parentTypeName": "Query", "variables": { "postId": "123", "authorId": "456" }, "selectionSetList": [ "postId", "title", "secondTitle" "content", "author", "author/authorId", "author/name", "secondAuthor", "secondAuthor/authorId", "inlineFragComments", "inlineFragComments/id", "postFragComments", "postFragComments/id" ], "selectionSetGraphQL": "{\n getPost(id: $postId) {\n postId\n title\n secondTitle: title\n content\n author(id: $authorId) {\n authorId\n name\n }\n secondAuthor(id: \"789\") {\n authorId\n }\n ... on Post {\n inlineFrag: comments {\n id\n }\n }\n ... postFrag\n }\n}" } ``` `selectionSetList` は現在のタイプに属するフィールドのみを公開します。現在のタイプがインタフェースまたは共用体の場合、そのインタフェースに属する選択されたフィールドのみが公開されます。例として、次のスキーマがあるとします。 ``` type Query { node(id: ID!): Node } interface Node { id: ID } type Post implements Node { id: ID title: String author: String } type Blog implements Node { id: ID title: String category: String } ``` そして次のクエリがあります。 ``` query { node(id: "post1") { id ... on Post { title } ... on Blog { title } } } ``` `Query.node` フィールド解決で `ctx.info.selectionSetList` が呼び出されると、`id` のみが公開されます。 ``` "selectionSetList": [ "id" ] ``` # リゾルバーと関数のAWS AppSync JavaScript ランタイム機能 `APPSYNC_JS` ランタイム環境には [ECMAScript (](https://262.ecma-international.org/6.0/)ES) バージョン 6.0 と同様の機能が備わっています。一部の機能をサポートし、ES 仕様に含まれない追加のメソッド (ユーティリティ) も提供しています。次のトピックでは、サポートされるすべての言語機能の一覧を示します。 + [サポートされているランタイム機能](https://docs.aws.amazon.com/appsync/latest/devguide/supported-features.html) - サポートされているコア機能、プリミティブオブジェクト、組み込みオブジェクトと関数などの詳細について説明します。 + [組み込みユーティリティ](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html) - 変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。 + [組み込みモジュール](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-modules-js.html) - 組み込みモジュールが JavaScript リゾルバーと関数の記述にどのように役立つかについて説明します。 + [ランタイムユーティリティ](https://docs.aws.amazon.com/appsync/latest/devguide/runtime-utils-js.html) - ランタイムライブラリには、リゾルバーと関数のランタイムプロパティを制御または変更するためのユーティリティが用意されています。 + [util.time のタイムヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/time-helpers-in-util-time-js.html) - util.time 変数には、タイムスタンプの生成、日時形式間の変換、および日時文字列の解析に役立つ日時メソッドが含まれています。日時形式の構文は DateTimeFormatter に基づいています。詳細については、[DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) を参照してください。 + [util.dynamodb のDynamoDB ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html) - util.dynamodb には、Amazon DynamoDB に対するデータの読み書きを容易にするヘルパーメソッド (自動型マッピングやフォーマットなど) が含まれています。 + [util.http の HTTP ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/http-helpers-in-utils-http-js.html) - util.http ユーティリティには、HTTP リクエストパラメータの管理やレスポンスヘッダーの追加に使用できるヘルパーメソッドが用意されています。 + [util.transform の変換ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/transformation-helpers-in-utils-transform-js.html) - util.transform には、データソースに対して複雑な操作を簡単に実行できるヘルパーメソッドが含まれています。 + [util.str の文字列ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/str-helpers-in-util-str-js.html) - util.str には、一般的な文字列オペレーションに役立つメソッドが含まれています。 + [拡張機能](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html) - 拡張機能には、リゾルバー内で追加のアクションを行うためのメソッドのセットが含まれています。 + [util.xml の XML ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/xml-helpers-in-util-xml-js.html) - util.xml には、XML 文字列変換に役立つメソッドが含まれています。 **注記** 現在、このリファレンスはランタイムバージョン **1.0.0** にのみ適用されます。 # サポートされているランタイム機能 以下のセクションでは、APPSYNC\$1JS ランタイムでサポートされる機能セットについて説明します。 ## 主要機能 次の主要機能がサポートされています。 ------ #### [ Types ] 次のタイプの BGP がサポートされています。 + 数字 + 文字列 + ブール値 + objects + 配列 + 関数 ------ #### [ Operators ] 次のような演算子がサポートされています。 + 標準の数学演算子 (`+`、`-`、`/`、`%`、`*` など) + Null 合体演算子 (`??`) + オプションのチェーニング (`?.`) + ビット演算子 + `void` および `typeof` 演算子 + スプレッド演算子 (`...`) 以下は、サポートされていない演算子です。 + 単項演算子 (`++`、`--`、および `~`) + `in` operator **注記** `Object.hasOwn` 演算子を使用して、指定したプロパティが指定されたオブジェクト内にあるかどうかを調べます。 ------ #### [ Statements ] 次のステートメントがサポートされています。 + `const` + `let` + `var` + `break` + `else` + `for-in` + `for-of` + `if` + `return` + `switch` + スプレッド構文 ただし、以下はサポートしていません。 + `catch` + `continue` + `do-while` + `finally` + `for(initialization; condition; afterthought)` **注記** ただし、サポートされている `for-in` および `for-of` 式は例外です。 + `throw` + `try` + `while` + ラベル付きステートメント ------ #### [ Literals ] 以下の ES 6 [テンプレートリテラル](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)がサポートされています。 + 複数行文字列 + 式の補間 + ネストテンプレート ------ #### [ Functions ] 以下の構文がサポートされています。 + 関数宣言はサポートされています。 + ES 6 アロー関数はサポートされています。 + ES 6 REST パラメータ構文はサポートされています。 ------ #### [ Strict mode ] 関数は Strict モードで動作するため、関数コードに `use_strict` ステートメントを追加する必要はありません。これは変更できません。 ------ ## プリミティブオブジェクト 以下の ES プリミティブオブジェクトがサポートされています。 ------ #### [ Object ] 以下のオブジェクトがサポートされています。 + `Object.assign()` + `Object.entries()` + `Object.hasOwn()` + `Object.keys()` + `Object.values()` + `delete` ------ #### [ String ] 以下の文字列がサポートされています。 + `String.prototype.length()` + `String.prototype.charAt()` + `String.prototype.concat()` + `String.prototype.endsWith()` + `String.prototype.indexOf()` + `String.prototype.lastIndexOf()` + `String.raw()` + `String.prototype.replace()` **注記** 正規表現はサポートされていません。 ただし、Java スタイルの正規表現コンストラクトは、指定されたパラメータでサポートされています。詳細については、「[パターン](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)」を参照してください。 + `String.prototype.replaceAll()` **注記** 正規表現はサポートされていません。 ただし、Java スタイルの正規表現コンストラクトは、指定されたパラメータでサポートされています。詳細については、「[パターン](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)」を参照してください。 + `String.prototype.slice()` + `String.prototype.split()` + `String.prototype.startsWith()` + `String.prototype.toLowerCase()` + `String.prototype.toUpperCase()` + `String.prototype.trim()` + `String.prototype.trimEnd()` + `String.prototype.trimStart()` ------ #### [ Number ] 次の番号がサポートされています。 + `Number.isFinite` + `Number.isNaN` ------ ## 組み込みオブジェクトと関数 以下の ES 5.1 グローバル関数がサポートされています。 ------ #### [ Math ] 次の Math 関数はサポートされていません。 + `Math.random()` + `Math.min()` + `Math.max()` + `Math.round()` + `Math.floor()` + `Math.ceil()` ------ #### [ Array ] 以下の配列メソッドがサポートされています。 + `Array.prototype.length` + `Array.prototype.concat()` + `Array.prototype.fill()` + `Array.prototype.flat()` + `Array.prototype.indexOf()` + `Array.prototype.join()` + `Array.prototype.lastIndexOf()` + `Array.prototype.pop()` + `Array.prototype.push()` + `Array.prototype.reverse()` + `Array.prototype.shift()` + `Array.prototype.slice()` + `Array.prototype.sort()` **注記** `Array.prototype.sort()` は引数はサポートしていません。 + `Array.prototype.splice()` + `Array.prototype.unshift()` + `Array.prototype.forEach()` + `Array.prototype.map()` + `Array.prototype.flatMap()` + `Array.prototype.filter()` + `Array.prototype.reduce()` + `Array.prototype.reduceRight()` + `Array.prototype.find()` + `Array.prototype.some()` + `Array.prototype.every()` + `Array.prototype.findIndex()` + `Array.prototype.findLast()` + `Array.prototype.findLastIndex()` + `delete` ------ #### [ Console ] コンソールオブジェクトはデバッグに使用できます。ライブクエリの実行中、コンソールのログ/エラーステートメントが Amazon CloudWatch Logs に送信されます (ロギングが有効になっている場合)。`evaluateCode` でのコード評価中、コマンドレスポンスにログステートメントが返されます。 + `console.error()` + `console.log()` ------ #### [ Function ] + `apply`、`bind` `call` メソッドはサポートされていません。 + 関数コンストラクタはサポートされていません。 + 関数を引数として渡すことはサポートされていません。 + 再帰的な関数呼び出しはサポートされていません。 ------ #### [ JSON ] 以下の JSON メソッドがサポートされています。 + `JSON.parse()` **注記** 解析された文字列が有効な JSON でない場合は、空白の文字列を返します。 + `JSON.stringify()` ------ #### [ Promises ] 非同期プロセスはサポートされておらず、Promise もサポートされていません。 **注記** ネットワークおよびファイルシステムへのアクセスは、 `APPSYNC_JS`ランタイム内ではサポートされていません AWS AppSync。 は、 AWS AppSync リゾルバーまたは AWS AppSync 関数によって行われたリクエストに基づいて、すべての I/O オペレーション AWS AppSync を処理します。 ------ ## Globals 以下のグローバル定数がサポートされています。 + `NaN` + `Infinity` + `undefined` + [https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html) + [https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html) + `runtime` ## エラータイプ `throw` でエラーをスローすることはサポートされていません。`util.error()` 関数を使用するとエラーを返すことができます。`util.appendError` 関数を使用して GraphQL レスポンスにエラーを含めることができます。 詳細については、「[エラー utils](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-util-js.html#utility-helpers-in-error-js)」を参照してください。 # 組み込みユーティリティ `util` 変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。 ## エンコーディング utils ### エンコーディング utils リスト **`util.urlEncode(String)`** 入力文字列を `application/x-www-form-urlencoded` でエンコードされた文字列として返します。 **`util.urlDecode(String)`** `application/x-www-form-urlencoded` でエンコードされた文字列をデコードして、エンコードされていない形式に戻します。 **`util.base64Encode(string) : string`** 入力を base64 でエンコードされた文字列にエンコードします。 **`util.base64Decode(string) : string`** base64 エンコードされた文字列からデータをデコードします。 ## ID 生成 utils ### ID 生成 utils リスト **`util.autoId()`** ランダムに生成された 128 ビットの UUID を返します。 **`util.autoUlid()`** ランダムに生成された 128 ビットの ULID (辞書的にソート可能なユニバーサルユニーク識別子) を返します。 **`util.autoKsuid()`** 長さ 27 の文字列としてエンコードされた、ランダムに生成された 128 ビットの KSUID (K ソート可能な固有識別子) base62 を返します。 ## エラー utils ### エラー utils リスト **`util.error(String, String?, Object?, Object?)`** カスタムエラーをスローします。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `errorInfo` はクエリ選択セットに基づいてフィルタリング**されません**。 **`util.appendError(String, String?, Object?, Object?)`** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`util.error(String, String?, Object?, Object?)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `errorInfo` はクエリ選択セットに基づいてフィルタリング**されません**。 ## タイプとパターンマッチングの utils ### タイプとパターンマッチングの utils リスト **`util.matches(String, String) : Boolean`** 最初の引数で指定されたパターンが、2 番目の引数で指定されたデータと一致する場合は true を返します。パターンは正規表現である必要があります (例: `util.matches("a*b", "aaaaab")`)。この機能は Java の Pattern に基づいています。詳細については、[Pattern](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html) を参照してください。 **`util.authType()`** リクエストで使用されているマルチ認可タイプを表す文字列型 (String) の値を返します。「IAM 認可」、「ユーザープールの認可」、「オープン ID Connect 認可」、または「API キー認可」のいずれかを返します。 ## 戻り値動作 utils ### 戻り値動作 utils リスト **`util.escapeJavaScript(String)`** 入力文字列を JavasScript のエスケープした文字列として返します。 ## リゾルバー認可 utils ### リゾルバー認可 utils リスト **`util.unauthorized()`** 解決されるフィールドに対して `Unauthorized` をスローします。リクエストまたはレスポンスのマッピングテンプレートでこれを使用し、呼び出し元にそのフィールドの解決が許可されるかどうかを判別します。 # ビルトインモジュール モジュールは `APPSYNC_JS` ランタイムの一部であり、JavaScript リゾルバーと関数の作成に役立つユーティリティを提供します。サンプルと例については、[aws-appsync-resolver-samples](https://github.com/aws-samples/aws-appsync-resolver-samples) GitHub リポジトリを参照してください。 ## DynamoDB モジュール関数 DynamoDB モジュール関数を使用すると、DynamoDB データソースを操作する際のエクスペリエンスが向上します。タイプマッピングを追加しなくても、関数を使用して DynamoDB データソースに対してリクエストを行うことができます。 モジュールは `@aws-appsync/utils/dynamodb` を使用してインポートされます。 ``` // Modules are imported using @aws-appsync/utils/dynamodb import * as ddb from '@aws-appsync/utils/dynamodb'; ``` ### 関数 #### 関数のリスト **` get(payload: GetInput): DynamoDBGetItemRequest`** GetInput については、「[入力](#built-in-ddb-modules-inputs)」を参照してください。 DynamoDB に [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-getitem) リクエストを行うための `DynamoDBGetItemRequest` オブジェクトを生成します。 ``` import { get } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { return get({ key: { id: ctx.args.id } }); } ``` **`put(payload): DynamoDBPutItemRequest`** DynamoDB に [PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem) リクエストを行うための `DynamoDBPutItemRequest` オブジェクトを生成します。 ``` import * as ddb from '@aws-appsync/utils/dynamodb' export function request(ctx) { return ddb.put({ key: { id: util.autoId() }, item: ctx.args }); } ``` **`remove(payload): DynamoDBDeleteItemRequest`** DynamoDB に [DeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-deleteitem) リクエストを行うための `DynamoDBDeleteItemRequest` オブジェクトを生成します。 ``` import * as ddb from '@aws-appsync/utils/dynamodb'; export function request(ctx) { return ddb.remove({ key: { id: ctx.args.id } }); } ``` **`scan(payload): DynamoDBScanRequest`** DynamoDB に [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan) リクエストを行うための`DynamoDBScanRequest`を生成します。 ``` import * as ddb from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const { limit = 10, nextToken } = ctx.args; return ddb.scan({ limit, nextToken }); } ``` **`sync(payload): DynamoDBSyncRequest`** [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-sync) リクエストを行う `DynamoDBSyncRequest` オブジェクトを生成します。リクエストは、前回のクエリ (デルタ更新) 以降に変更されたデータのみを受け取ります。リクエストは、バージョン管理された DynamoDB データソースに対してのみ行うことができます。 ``` import * as ddb from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const { limit = 10, nextToken, lastSync } = ctx.args; return ddb.sync({ limit, nextToken, lastSync }); } ``` **`update(payload): DynamoDBUpdateItemRequest`** DynamoDB に [UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-updateitem) リクエストを行うための `DynamoDBUpdateItemRequest` オブジェクトを生成します。 ### オペレーション オペレーションヘルパーを使用すると、更新中にデータの一部に対して特定のアクションを実行できます。はじめに、`@aws-appsync/utils/dynamodb` から `operations` をインポートしてください。 ``` // Modules are imported using operations import {operations} from '@aws-appsync/utils/dynamodb'; ``` #### オペレーションリスト **`add(payload)`** DynamoDB を更新するときに新しい属性項目を追加するヘルパー関数。 **例** ID 値を使用して既存の DynamoDB 項目に住所 (番地、市区町村、郵便番号) を追加するには ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const updateObj = { address: operations.add({ street1: '123 Main St', city: 'New York', zip: '10001', }), }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`append (payload)`** DynamoDB の既存のリストにペイロードを追加するヘルパー関数。 **例** 更新中に新しく追加されたフレンド ID (`newFriendIds`) を既存のフレンドリスト (`friendsIds`) に追加するには ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const newFriendIds = [101, 104, 111]; const updateObj = { friendsIds: operations.append(newFriendIds), }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`decrement (by?)`** DynamoDB を更新するときに項目内の既存の属性値をデクリメントするヘルパー関数。 **例** フレンドカウンター (`friendsCount`) を 10 ずつ減らすには ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const updateObj = { friendsCount: operations.decrement(10), }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`increment (by?)`** DynamoDB を更新するときに項目内の既存の属性値をインクリメントするヘルパー関数。 **例** フレンドカウンター (`friendsCount`) を 10 ずつ増やすには: ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const updateObj = { friendsCount: operations.increment(10), }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`prepend (payload)`** DynamoDB の既存のリストの前に追加するヘルパー関数。 **例** 更新時に、新しく追加されたフレンド ID (`newFriendIds`) を既存のフレンドリスト (`friendsIds`) の先頭に追加するには ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const newFriendIds = [101, 104, 111]; const updateObj = { friendsIds: operations.prepend(newFriendIds), }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`replace (payload)`** DynamoDB の項目を更新するときに既存の属性を置き換えるヘルパー関数。これは、ペイロードのキーだけでなく、属性のオブジェクトまたはサブオブジェクト全体を更新したい場合に便利です。 **例** `info` オブジェクト内の住所 (番地、市区町村、郵便番号) を置き換えるには ``` import { update, operations } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const updateObj = { info: { address: operations.replace({ street1: '123 Main St', city: 'New York', zip: '10001', }), }, }; return update({ key: { id: 1 }, update: updateObj }); } ``` **`updateListItem (payload, index)`** リスト内の項目を置き換えるヘルパー関数。 **例** 更新 (`newFriendIds`) のスコープで、この例では `friendsIds` を使用してリスト (`updateListItem`) の 2 番目の項目 (index: `1`、new ID:`102`) と 3 番目の項目 (index: `2`、new ID:`112`) の ID 値を更新しました。 ``` import { update, operations as ops } from '@aws-appsync/utils/dynamodb'; export function request(ctx) { const newFriendIds = [ ops.updateListItem('102', 1), ops.updateListItem('112', 2) ]; const updateObj = { friendsIds: newFriendIds }; return update({ key: { id: 1 }, update: updateObj }); } ``` ### 入力 #### 入力リスト **`Type GetInput`** ``` GetInput: { consistentRead?: boolean; key: DynamoDBKey; } ``` **タイプ宣言** + `consistentRead?: boolean` (オプション) DynamoDB で強力な整合性のある読み込みを実行するかどうかを指定するオプションのブール値。 + `key: DynamoDBKey` (必須) DynamoDB の項目のキーを指定する必須パラメータ。DynamoDB の項目には、単一のハッシュキーとソートキーが含まれています。 **`Type PutInput`** ``` PutInput: { _version?: number; condition?: DynamoDBFilterObject | null; customPartitionKey?: string; item: Partial; key: DynamoDBKey; populateIndexFields?: boolean; } ``` **タイプ宣言** + `_version?: number` (オプション) + `condition?: DynamoDBFilterObject | null` (オプション) DynamoDB テーブルにオブジェクトを格納する際、オプションで条件式を指定することができます。この条件式は、操作を実行する前にすでに DynamoDB に格納されているオブジェクトの状態に基づいて、リクエストを成功させるかどうかを制御します。 + `customPartitionKey?: string` (オプション) 有効にすると、この文字列値によって、バージョニングが有効になっているときにデルタ同期テーブルが使用する `ds_sk` および `ds_pk` レコードの形式が変更されます。有効にすると、`populateIndexFields` エントリの処理も有効になります。 + `item: Partial` (必須) DynamoDB に配置される項目の残りの属性です。 + `key: DynamoDBKey` (必須) Put が実行される DynamoDB 内の項目のキーを指定する必須パラメータ。DynamoDB の項目には、単一のハッシュキーとソートキーが含まれています。 + `populateIndexFields?: boolean` (オプション) ブール値で、`customPartitionKey` と一緒に有効にすると、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSync デベロッパーガイド」の「[構成項目の配信](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。 **`Type QueryInput`** ``` QueryInput: ScanInput & { query: DynamoDBKeyCondition>; } ``` **タイプ宣言** + `query: DynamoDBKeyCondition>` (必須) クエリする項目を記述するキー条件を指定します。特定のインデックスでは、パーティションキーの条件は等しく、ソートキーは比較または `beginsWith` (文字列の場合) でなければなりません。パーティションキーとソートキーでは、数値型と文字列型のみがサポートされています。 **例** 以下の `User` タイプを考えてみてください。 ``` type User = { id: string; name: string; age: number; isVerified: boolean; friendsIds: string[] } ``` このクエリには`id`、`name`、`age` のフィールドのみを含めることができます。 ``` const query: QueryInput = { name: { eq: 'John' }, age: { gt: 20 }, } ``` **`Type RemoveInput`** ``` RemoveInput: { _version?: number; condition?: DynamoDBFilterObject; customPartitionKey?: string; key: DynamoDBKey; populateIndexFields?: boolean; } ``` **タイプ宣言** + `_version?: number` (オプション) + `condition?: DynamoDBFilterObject` (オプション) DynamoDB テーブルにオブジェクトを格納する際、オプションで条件式を指定することができます。この条件式は、操作を実行する前にすでに DynamoDB に格納されているオブジェクトの状態に基づいて、リクエストを成功させるかどうかを制御します。 **例** 次の例は、ドキュメントの所有者がリクエストを行ったユーザーと一致する場合にのみ操作が成功することを許可する条件を含む `DeleteItem` 式です。 ``` type Task = { id: string; title: string; description: string; owner: string; isComplete: boolean; } const condition: DynamoDBFilterObject = { owner: { eq: 'XXXXXXXXXXXXXXXX' }, } remove({ key: { id: 'XXXXXXXXXXXXXXXX', }, condition, }); ``` + `customPartitionKey?: string` (オプション) 有効にすると、`customPartitionKey` 値によって、バージョニングが有効になっているときにデルタ同期テーブルが使用する `ds_sk` および `ds_pk` レコードの形式が変更されます。有効にすると、`populateIndexFields` エントリの処理も有効になります。 + `key: DynamoDBKey` (必須) 削除する DynamoDB 内の項目のキーを指定する必須パラメータ。DynamoDB の項目には、単一のハッシュキーとソートキーが含まれています。 **例** `User` がユーザー `id` のハッシュキーしか持っていない場合、キーは次のようになります。 ``` type User = { id: number name: string age: number isVerified: boolean } const key: DynamoDBKey = { id: 1, } ``` テーブルユーザーがハッシュキー (`id`) とソートキー (`name`) を持っている場合、キーは以下のようになります。 ``` type User = { id: number name: string age: number isVerified: boolean friendsIds: string[] } const key: DynamoDBKey = { id: 1, name: 'XXXXXXXXXX', } ``` + `populateIndexFields?: boolean` (オプション) ブール値で、`customPartitionKey` と一緒に有効にすると、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。 **`Type ScanInput`** ``` ScanInput: { consistentRead?: boolean | null; filter?: DynamoDBFilterObject | null; index?: string | null; limit?: number | null; nextToken?: string | null; scanIndexForward?: boolean | null; segment?: number; select?: DynamoDBSelectAttributes; totalSegments?: number; } ``` **タイプ宣言** + `consistentRead?: boolean | null` (オプション) DynamoDB のクエリ時に一貫性のあるリードを示すオプションのブール値。デフォルト値は `false` です。 + `filter?: DynamoDBFilterObject | null` (オプション) テーブルから結果を取得した後に結果に適用するオプションのフィルター。 + `index?: string | null` (オプション) スキャンするインデックスの名前。 + `limit?: number | null` (オプション) 返される結果の最大数。 + `nextToken?: string | null` (オプション) 前のクエリを継続するためのオプションのページ分割トークンです。これは前のクエリから取得されます。 + `scanIndexForward?: boolean | null` (オプション) クエリを昇順にするか、降順にするかを示すオプションのブール値。デフォルトではこの値は `true` に設定されます。 + `segment?: number` (オプション) + `select?: DynamoDBSelectAttributes` (オプション) DynamoDB から返される属性。デフォルトでは、 AWS AppSync DynamoDB リゾルバーはインデックスに射影された属性のみを返します。サポートされている値には以下があります。 + `ALL_ATTRIBUTES` 指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。 + `ALL_PROJECTED_ATTRIBUTES` インデックスにプロジェクションされたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は `ALL_ATTRIBUTES` を指定した場合と同等になります。 + `SPECIFIC_ATTRIBUTES` `ProjectionExpression` にリストされている属性のみを返します。この戻り値は、`AttributesToGet` の値を指定せずに `ProjectionExpression` を指定することと同じです。 + `totalSegments?: number` (オプション) **`Type DynamoDBSyncInput`** ``` DynamoDBSyncInput: { basePartitionKey?: string; deltaIndexName?: string; filter?: DynamoDBFilterObject | null; lastSync?: number; limit?: number | null; nextToken?: string | null; } ``` **タイプ宣言** + `basePartitionKey?: string` (オプション) Sync 操作を実行するときに使用するベーステーブルのパーティションキー。このフィールドにより、テーブルがカスタムパーティションキーを使用している場合に Sync 操作を実行できます。 + `deltaIndexName?: string` (オプション) Sync 操作に使用されるインデックス。このインデックスは、テーブルがカスタムパーティションキーを使用する場合に、デルタストアテーブル全体で Sync 操作を有効にするために必要です。Sync オペレーションは GSI (`gsi_ds_pk` と `gsi_ds_sk` で作成) で実行されます。 + `filter?: DynamoDBFilterObject | null` (オプション) テーブルから結果を取得した後に結果に適用するオプションのフィルター。 + `lastSync?: number` (オプション) 最後に成功した Sync オペレーションが開始されたエポックミリ秒単位の時刻。指定すると、`lastSync` 以降に変更された項目のみが返されます。このフィールドはオプションです。最初の Sync オペレーションからすべてのページを取得した後にのみ入力する必要があります。省略すると、ベーステーブルの結果が返されます。それ以外の場合は、差分テーブルの結果が返されます。 + `limit?: number | null` (オプション) 一度に評価する項目の最大数です。省略した場合、デフォルトの制限は `100` 項目に設定されます。このフィールドの最大値は `1000` 項目です。 + `nextToken?: string | null` (オプション) **`Type DynamoDBUpdateInput`** ``` DynamoDBUpdateInput: { _version?: number; condition?: DynamoDBFilterObject; customPartitionKey?: string; key: DynamoDBKey; populateIndexFields?: boolean; update: DynamoDBUpdateObject; } ``` **タイプ宣言** + `_version?: number` (オプション) + `condition?: DynamoDBFilterObject` (オプション) DynamoDB でオブジェクトを更新する場合、オプションで条件式を指定することができます。この条件式は、操作を実行する前にすでに DynamoDB にあるオブジェクトの状態に基づいて、リクエストを成功させるかどうかを制御します。 + `customPartitionKey?: string` (オプション) 有効にすると、`customPartitionKey` 値によって、バージョニングが有効になっているときにデルタ同期テーブルが使用する `ds_sk` および `ds_pk` レコードの形式が変更されます。有効にすると、`populateIndexFields` エントリの処理も有効になります。 + `key: DynamoDBKey` (必須) 更新中の DynamoDB 内の項目のキーを指定する必須パラメータ。DynamoDB の項目には、単一のハッシュキーとソートキーが含まれています。 + `populateIndexFields?: boolean` (オプション) ブール値で、`customPartitionKey` と一緒に有効にすると、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。 + `update: DynamoDBUpdateObject` 更新する属性とその新しい値を指定するオブジェクト。更新オブジェクトは `add`、`remove`、`replace`、`increment`、`decrement`、`append`、`prepend`、`updateListItem` と共に使用できます。 ## Amazon RDS モジュール関数 Amazon RDS モジュール関数を使用すると、Amazon RDS Data API で設定されたデータベースを操作する際のエクスペリエンスが向上します。モジュールは `@aws-appsync/utils/rds` を使用してインポートされます。 ``` import * as rds from '@aws-appsync/utils/rds'; ``` 関数は個別にインポートすることもできます。例えば、以下のインポートでは `sql` を使用します。 ``` import { sql } from '@aws-appsync/utils/rds'; ``` ### 関数 AWS AppSync RDS モジュールのユーティリティヘルパーを使用して、データベースとやり取りできます。 #### Select `select` ユーティリティは、リレーショナルデータベースにクエリを実行する `SELECT` ステートメントを作成します。 **基本的な使用法** 基本的な形式では、クエリを実行するテーブルを指定できます。 ``` import { select, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { // Generates statement: // "SELECT * FROM "persons" return createPgStatement(select({table: 'persons'})); } ``` なお、テーブル識別子でスキーマを指定することもできます。 ``` import { select, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { // Generates statement: // SELECT * FROM "private"."persons" return createPgStatement(select({table: 'private.persons'})); } ``` **列の指定** `columns` プロパティで列を指定できます。これを値に設定しない場合、デフォルトでは `*` になります。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" return createPgStatement(select({ table: 'persons', columns: ['id', 'name'] })); } ``` また、列のテーブルも指定できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "persons"."name" // FROM "persons" return createPgStatement(select({ table: 'persons', columns: ['id', 'persons.name'] })); } ``` **LIMIT と OFFSET** `limit` と `offset` をクエリに適用できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // LIMIT :limit // OFFSET :offset return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], limit: 10, offset: 40 })); } ``` **ORDER BY** 結果は `orderBy` プロパティを使用してソートできます。列とオプションの `dir` プロパティを指定するオブジェクトの配列を指定します。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" FROM "persons" // ORDER BY "name", "id" DESC return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], orderBy: [{column: 'name'}, {column: 'id', dir: 'DESC'}] })); } ``` **フィルター** 特殊条件オブジェクトを使用してフィルターを構築できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: {name: {eq: 'Stephane'}} })); } ``` 以下のフィルターを組み合わせることもできます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME and "id" > :ID return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: {name: {eq: 'Stephane'}, id: {gt: 10}} })); } ``` また、`OR` ステートメントも作成できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME OR "id" > :ID return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: { or: [ { name: { eq: 'Stephane'} }, { id: { gt: 10 } } ]} })); } ``` `not` を使用して条件を無効にすることもできます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE NOT ("name" = :NAME AND "id" > :ID) return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: { not: [ { name: { eq: 'Stephane'} }, { id: { gt: 10 } } ]} })); } ``` 以下の演算子を使用して、値を比較することもできます。 | | | 演算子 | 説明 | 可能な値型 | | --- |--- |--- | | eq | Equal | number, string, boolean | | ne | Not equal | number, string, boolean | | le | Less than or equal | number, string | | lt | Less than | number, string | | ge | Greater than or equal | number, string | | gt | Greater than | number, string | | contains | Like | string | | notContains | Not like | string | | beginsWith | Starts with prefix | string | | between | Between two values | number, string | | attributeExists | The attribute is not null | number, string, boolean | | size | checks the length of the element | string | #### Insert `insert` ユーティリティによって、`INSERT` オペレーションを使用してデータベースに単一行の項目を簡単に挿入できます。 **単一項目の挿入** 項目を挿入するには、テーブルを指定して、値のオブジェクトを渡します。オブジェクトキーはテーブルの列にマッピングされます。列名は自動的にエスケープされ、値は変数マップを使用してデータベースに送信されます。 ``` import { insert, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values }); // Generates statement: // INSERT INTO `persons`(`name`) // VALUES(:NAME) return createMySQLStatement(insertStatement) } ``` **MySQL ユースケース** `insert` の後に `select` を組み合わせて、挿入した行を取得できます。 ``` import { insert, select, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values }); const selectStatement = select({ table: 'persons', columns: '*', where: { id: { eq: values.id } }, limit: 1, }); // Generates statement: // INSERT INTO `persons`(`name`) // VALUES(:NAME) // and // SELECT * // FROM `persons` // WHERE `id` = :ID return createMySQLStatement(insertStatement, selectStatement) } ``` **Postgres のユースケース** Postgres では、[https://www.postgresql.org/docs/current/dml-returning.html](https://www.postgresql.org/docs/current/dml-returning.html) を使用して、挿入した行からデータを取得できます。`*` または列名の配列が受け入れられます。 ``` import { insert, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values, returning: '*' }); // Generates statement: // INSERT INTO "persons"("name") // VALUES(:NAME) // RETURNING * return createPgStatement(insertStatement) } ``` #### 更新 `update` ユーティリティでは、既存の行を更新できます。条件オブジェクトを使用すると、条件を満たすすべての行の指定された列に変更を適用できます。例えば、このミューテーションを可能にするスキーマがあるとします。`Person` の `name` を `3` の `id` 値で更新したいのですが、これは `2000` 年以降にそれら (`known_since`) がわかっている場合に限ります。 ``` mutation Update { updatePerson( input: {id: 3, name: "Jon"}, condition: {known_since: {ge: "2000"}} ) { id name } } ``` 更新リゾルバーは以下のようになります。 ``` import { update, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: { id, ...values }, condition } = ctx.args; const where = { ...condition, id: { eq: id }, }; const updateStatement = update({ table: 'persons', values, where, returning: ['id', 'name'], }); // Generates statement: // UPDATE "persons" // SET "name" = :NAME, "birthday" = :BDAY, "country" = :COUNTRY // WHERE "id" = :ID // RETURNING "id", "name" return createPgStatement(updateStatement) } ``` 条件にチェックを追加して、`3` と等しいプライマリキー `id` を持つ行だけが更新されるようにすることができます。同様に、Postgres `inserts` の場合も、`returning` を使用して変更されたデータを返すことができます。 #### 削除 `remove` ユーティリティでは、既存の行を削除できます。条件オブジェクトは、条件を満たすすべての行で使用できます。なお、`delete` はJavaScriptの予約キーワードです。代わりに `remove` を使ってください。 ``` import { remove, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: { id }, condition } = ctx.args; const where = { ...condition, id: { eq: id } }; const deleteStatement = remove({ table: 'persons', where, returning: ['id', 'name'], }); // Generates statement: // DELETE "persons" // WHERE "id" = :ID // RETURNING "id", "name" return createPgStatement(updateStatement) } ``` ### キャスティング ステートメントで使用する正しいオブジェクト型に関して、さらに特異度が必要となる場合もあるでしょう。指定された型ヒントを使用してパラメータのタイプを指定できます。 は Data API [と同じ型ヒント](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html#rdsdtataservice-Type-SqlParameter-typeHint) AWS AppSync をサポートします。モジュールの `typeHint`関数を使用してパラメータを AWS AppSync `rds`キャストできます。 次の例では、JSON オブジェクトとしてキャストされた値として配列を送信できます。`->` 演算子を使用して JSON 配列内にある `index` `2` の要素を取得します。 ``` import { sql, createPgStatement, toJsonObject, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const arr = ctx.args.list_of_ids const statement = sql`select ${typeHint.JSON(arr)}->2 as value` return createPgStatement(statement) } export function response(ctx) { return toJsonObject(ctx.result)[0][0].value } ``` キャスティングは、`DATE`、`TIME`、`TIMESTAMP` の処理や比較を行うときにも役立ちます。 ``` import { select, createPgStatement, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const when = ctx.args.when const statement = select({ table: 'persons', where: { createdAt : { gt: typeHint.DATETIME(when) } } }) return createPgStatement(statement) } ``` 現在の日付と時刻を送信する方法について別の例を以下に示します。 ``` import { sql, createPgStatement, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const now = util.time.nowFormatted('YYYY-MM-dd HH:mm:ss') return createPgStatement(sql`select ${typeHint.TIMESTAMP(now)}`) } ``` **使用可能な型ヒント** + `typeHint.DATE` - 対応するパラメータが、`DATE` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `YYYY-MM-DD` です。 + `typeHint.DECIMAL` - 対応するパラメータが、`DECIMAL` 型のオブジェクトとしてデータベースに送信されます。 + `typeHint.JSON` - 対応するパラメータが、`JSON` 型のオブジェクトとしてデータベースに送信されます。 + `typeHint.TIME` - 対応する文字列パラメータ値が、`TIME` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `HH:MM:SS[.FFF]` です。 + `typeHint.TIMESTAMP` - 対応する文字列パラメータ値が、`TIMESTAMP` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `YYYY-MM-DD HH:MM:SS[.FFF]` です。 + `typeHint.UUID` - 対応する文字列パラメータ値が、`UUID` 型のオブジェクトとしてデータベースに送信されます。 # ランタイムユーティリティ `runtime` ライブラリには、リゾルバーと関数のランタイムプロパティを制御または変更するためのユーティリティが用意されています。 ## ランタイム utils リスト **`runtime.earlyReturn(obj?: unknown, returnOptions?: {skipTo: 'END' | 'NEXT'}): never`** この関数を呼び出すと、現在のコンテキストに応じて、現在のハンドラー、 AWS AppSync 関数、またはリゾルバー (ユニットまたはパイプラインリゾルバー) の実行が停止します。指定したオブジェクトが結果として返されます。 + AWS AppSync 関数リクエストハンドラーで呼び出されると、データソースハンドラーとレスポンスハンドラーはスキップされ、次の関数リクエストハンドラー (または最後の AWS AppSync 関数の場合はパイプラインリゾルバーレスポンスハンドラー) が呼び出されます。 + AWS AppSync パイプラインリゾルバーリクエストハンドラーで呼び出されると、パイプラインの実行はスキップされ、パイプラインリゾルバーレスポンスハンドラーはすぐに呼び出されます。 + `returnOptions` を「END」に `skipTo` 設定すると、パイプラインの実行はスキップされ、パイプラインリゾルバーレスポンスハンドラーは即座に呼び出されます。 + `returnOptions` を「NEXT」に `skipTo` 設定すると、関数の実行はスキップされ、次のパイプラインハンドラーが呼び出されます。 **例** ``` import { runtime } from '@aws-appsync/utils' export function request(ctx) { runtime.earlyReturn({ hello: 'world' }) // code below is not executed return ctx.args } // never called because request returned early export function response(ctx) { return ctx.result } ``` # util.time の日時ヘルパー `util.time` 変数には、タイムスタンプの生成、日時形式間の変換、および日時文字列の解析に役立つ日時メソッドが含まれています。日時形式の構文は Java の DateTimeFormatter に基づいています。詳細については、[DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) を参照してください。 ## 日時 utils リスト **`util.time.nowISO8601()`** [ISO 8601 形式](https://en.wikipedia.org/wiki/ISO_8601)の UTC の文字列型表現を返します。 **`util.time.nowEpochSeconds()`** エポック (1970-01-01T00:00:00Z) から現在までの秒数を返します。 **`util.time.nowEpochMilliSeconds()`** エポック (1970-01-01T00:00:00Z) から現在までのミリ秒数を返します。 **`util.time.nowFormatted(String)`** 文字列型の入力引数で指定された形式を使用して、UTC での現在のタイムスタンプを返します。 **`util.time.nowFormatted(String, String)`** 文字列型の入力引数で指定された形式とタイムゾーンを使用して、そのタイムゾーンでの現在のタイムスタンプを返します。 **`util.time.parseFormattedToEpochMilliSeconds(String, String)`** 文字列として、タイムゾーンを含む形式で渡されたタイムスタンプを解析し、エポックからのミリ秒単位のタイムスタンプを返します。 **`util.time.parseFormattedToEpochMilliSeconds(String, String, String)`** 文字列型として渡されたタイムスタンプ、形式、およびタイムゾーンを解析し、エポックからのミリ秒単位のタイムスタンプを返します。 **`util.time.parseISO8601ToEpochMilliSeconds(String)`** 文字列型として渡された ISO8601 形式のタイムスタンプを解析し、エポックからのミリ秒単位のタイムスタンプを返します。 **`util.time.epochMilliSecondsToSeconds(long)`** エポックからのミリ秒単位のタイムスタンプを、エポックからの秒単位のタイムスタンプに変換します。 **`util.time.epochMilliSecondsToISO8601(long)`** エポックからのミリ秒単位のタイムスタンプを、ISO8601 形式のタイムスタンプに変換します。 **`util.time.epochMilliSecondsToFormatted(long, String)`** long として渡されたエポックからのミリ秒単位のタイムスタンプを、文字列型で指定された形式に合わせて UTC でのタイムスタンプに変換します。 **`util.time.epochMilliSecondsToFormatted(long, String, String)`** long として渡されたエポックからのミリ秒単位のタイムスタンプを、文字列型で指定された形式とタイムゾーンに合わせて、そのタイムゾーンでのタイムスタンプに変換します。 # util.dynamodb の DynamoDB ヘルパー `util.dynamodb` には、Amazon DynamoDB に対するデータの読み書きを容易にするヘルパーメソッド (自動型マッピングやフォーマットなど) が含まれています。 ## toDynamoDB ### toDynamoDB utils リスト **`util.dynamodb.toDynamoDB(Object)`** 入力されたオブジェクトを適切な DynamoDB 表現形式に変換する DynamoDB 用の一般的なオブジェクト変換ツールです。このツールは、一部の型の表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。これは、DynamoDB 属性値を記述するオブジェクトを返します。 **文字列型の例** ``` Input: util.dynamodb.toDynamoDB("foo") Output: { "S" : "foo" } ``` **数値型の例** ``` Input: util.dynamodb.toDynamoDB(12345) Output: { "N" : 12345 } ``` **ブール型の例** ``` Input: util.dynamodb.toDynamoDB(true) Output: { "BOOL" : true } ``` **リスト型の例** ``` Input: util.dynamodb.toDynamoDB([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] } ``` **マップ型の例** ``` Input: util.dynamodb.toDynamoDB({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } } ``` ## toString utils ### toString utils リスト **`util.dynamodb.toString(String)`** 入力文字列を DynamoDB の文字列形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toString("foo") Output: { "S" : "foo" } ``` **`util.dynamodb.toStringSet(List)`** 文字列型のリスト型を DynamoDB の文字列セット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toStringSet([ "foo", "bar", "baz" ]) Output: { "SS" : [ "foo", "bar", "baz" ] } ``` ## toNumber utils ### toNumber utils リスト **`util.dynamodb.toNumber(Number)`** 数値を DynamoDB の数値形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toNumber(12345) Output: { "N" : 12345 } ``` **`util.dynamodb.toNumberSet(List)`** 数値のリストを DynamoDB の数値セット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toNumberSet([ 1, 23, 4.56 ]) Output: { "NS" : [ 1, 23, 4.56 ] } ``` ## toBinary utils ### toBinary utils リスト **`util.dynamodb.toBinary(String)`** base64 文字列としてエンコードされたバイナリデータを DynamoDB のバイナリ形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toBinary("foo") Output: { "B" : "foo" } ``` **`util.dynamodb.toBinarySet(List)`** base64 文字列としてエンコードされたバイナリデータのリストを DynamoDB のバイナリセット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toBinarySet([ "foo", "bar", "baz" ]) Output: { "BS" : [ "foo", "bar", "baz" ] } ``` ## toBoolean utils ### toBoolean utils リスト **`util.dynamodb.toBoolean(Boolean)`** ブール値を DynamoDB の該当するブール形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toBoolean(true) Output: { "BOOL" : true } ``` ## toNull utils ### toNull utils リスト **`util.dynamodb.toNull()`** null を DynamoDB の null 形式で返します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toNull() Output: { "NULL" : null } ``` ## toList utils ### toList utils リスト **`util.dynamodb.toList(List)`** オブジェクトのリストを DynamoDB のリスト形式に変換します。リスト内の各項目も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toList([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] } ``` ## toMap utils ### toMap utils リスト **`util.dynamodb.toMap(Map)`** マップを DynamoDB のマップ形式に変換します。マップ内の各値も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toMap({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } } ``` **`util.dynamodb.toMapValues(Map)`** マップ内の各値を該当する DynamoDB 形式に変換して、マップのコピーを作成します。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。 ``` Input: util.dynamodb.toMapValues({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } ``` 注 : このツールは `util.dynamodb.toMap(Map)` と少し異なっていて、属性値全体ではなく DynamoDB の属性値の内容のみを返します。例えば、次の 2 つのステートメントはまったく同じです。 ``` util.dynamodb.toMapValues() util.dynamodb.toMap()("M") ``` ## S3Object utils ### S3Object utils リスト **`util.dynamodb.toS3Object(String key, String bucket, String region)`** キー、バケット、およびリージョンを DynamoDB の S3 オブジェクト表現に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toS3Object("foo", "bar", region = "baz") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo", \"bucket\" : \"bar", \"region\" : \"baz" } }" } ``` **`util.dynamodb.toS3Object(String key, String bucket, String region, String version)`** キー、バケット、リージョン、およびバージョン (省略可) を DynamoDB の S3 オブジェクト表現に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: util.dynamodb.toS3Object("foo", "bar", "baz", "beep") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" } ``` **`util.dynamodb.fromS3ObjectJson(String)`** DynamoDB の S3 オブジェクトの文字列値を受け入れて、キー、バケット、リージョン、およびバージョン (省略可) が含まれているマップを返します。 ``` Input: util.dynamodb.fromS3ObjectJson({ "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" }) Output: { "key" : "foo", "bucket" : "bar", "region" : "baz", "version" : "beep" } ``` # util.http の HTTP ヘルパー `util.http` ユーティリティには、HTTP リクエストパラメータの管理やレスポンスヘッダーの追加に使用できるヘルパーメソッドが用意されています。 ## util.http utils リスト **`util.http.copyHeaders(headers)`** 以下の制限された HTTP ヘッダーを除き、マップからヘッダーをコピーします。 + transfer-encoding + connection + host + expect + keep-alive + upgrade + proxy-authenticate + proxy-authorization + te + content-length **`util.http.addResponseHeader(String, Object)`** レスポンスの名前 (`String`) と値 (`Object`) を含むカスタムヘッダーを 1 つ追加します。以下の制限が適用されます。 + `copyHeaders(headers)` の制限付きヘッダーのリストに加えて、ヘッダー名は次のいずれかと一致することはできません。 + Access-Control-Allow-Credentials + Access-Control-Allow-Origin + Access-Control-Expose-Headers + Access-Control-Max-Age + Access-Control-Allow-Methods + Access-Control-Allow-Headers + Vary + Content-Type + ヘッダー名は、`x-amzn-` や `x-amz-` などの制限付きプレフィックスで始めることはできません。 + カスタムレスポンスヘッダーのサイズは 4 KB を超えることはできません。これにはヘッダー名と値が含まれます。 + 各レスポンスヘッダーは、GraphQL 操作ごとに 1 回定義する必要があります。ただし、同じ名前のカスタムヘッダーを複数回定義すると、最新の定義がレスポンスに表示されます。名前に関係なく、すべてのヘッダーがヘッダーサイズの上限に含まれます。 + 名前 `(String)` が空または制限されているヘッダーや null 値 `(Object)` のヘッダーは無視され、オペレーションの `errors` 出力に追加される `ResponseHeaderError` エラーが発生します。 ``` export function request(ctx) { util.http.addResponseHeader('itemsCount', 7) util.http.addResponseHeader('render', ctx.args.render) return {} } ``` **`util.http.addResponseHeaders(Map)`** 複数のレスポンスヘッダーを、名前 `(String)` と値 `(Object)` の指定したマップからのレスポンスに追加します。`addResponseHeader(String, Object)` メソッドにリストされているのと同じ制限が、このメソッドにも適用されます。 ``` export function request(ctx) { const headers = { headerInt: 12, headerString: 'stringValue', headerObject: { field1: 7, field2: 'string' } } util.http.addResponseHeaders(headers) return {} } ``` # util.transform の変換ヘルパー `util.transform` には、Amazon DynamoDB フィルター処理などの、データソースに対する複雑なオペレーションの実行を容易にするヘルパーメソッドが含まれています。 ## 変換ヘルパー utils リスト **`util.transform.toDynamoDBFilterExpression(filterObject: DynamoDBFilterObject) : string`** Amazon DynamoDB で使用するために、入力文字列をフィルター式に変換します。`toDynamoDBFilterExpression` を使用して、[組み込みモジュール関数](https://docs.aws.amazon.com/appsync/latest/devguide/built-in-modules-js.html)と併用することをおすすめします。 **`util.transform.toElasticsearchQueryDSL(object: OpenSearchQueryObject) : string`** 指定された入力を同等の OpenSearch Query DSL 式に変換し、JSON 文字列として返します。 **入力例** ``` util.transform.toElasticsearchQueryDSL({ "upvotes":{ "ne":15, "range":[ 10, 20 ] }, "title":{ "eq":"hihihi", "wildcard":"h*i" } }) ``` **出力例:** ``` { "bool":{ "must":[ { "bool":{ "must":[ { "bool":{ "must_not":{ "term":{ "upvotes":15 } } } }, { "range":{ "upvotes":{ "gte":10, "lte":20 } } } ] } }, { "bool":{ "must":[ { "term":{ "title":"hihihi" } }, { "wildcard":{ "title":"h*i" } } ] } } ] } } ``` デフォルトの演算子は AND であると仮定されます。 **`util.transform.toSubscriptionFilter(objFilter, ignoredFields?, rules?): SubscriptionFilter`** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`util.transform.toSubscriptionFilter` メソッドは`extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子の使用](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html)」を参照してください。 パラメータと return ステートメントは以下のとおりです。 *パラメータ* + `objFilter`: `SubscriptionFilterObject` `SubscriptionFilter`式オブジェクトに変換された `Map` 入力オブジェクト。 + `ignoredFields`: `SubscriptionFilterExcludeKeysType` (オプション) 最初のオブジェクトのフィールド名は無視されます。 + `rules`: `SubscriptionFilterRuleObject` (オプション) `SubscriptionFilter` 式オブジェクトを作成する際に含める、厳格なルールが適用された `Map` 入力オブジェクト。これらの厳格なルールは `SubscriptionFilter` 式オブジェクトに含まれるため、少なくとも 1 つのルールが満たされてサブスクリプションフィルターを通過することになります。 *レスポンス* 戻り値は `[SubscriptionFilter](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html)`。 **`util.transform.toSubscriptionFilter(Map, List)`** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`util.transform.toSubscriptionFilter` メソッドは`extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子の使用](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html)」を参照してください。 1 番目の引数は、`SubscriptionFilter` 式オブジェクトに変換される `Map` 入力オブジェクトです。2 番目の引数は、`SubscriptionFilter` 式オブジェクトを作成する際に 1 番目の `Map` 入力オブジェクトでは無視されるフィールド名の `List` です。 **`util.transform.toSubscriptionFilter(Map, List, Map)`** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`util.transform.toSubscriptionFilter` メソッドは`extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子の使用](https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html)」を参照してください。 **`util.transform.toDynamoDBConditionExpression(conditionObject)`** DynamoDB の条件式を作成します。 ## サブスクリプションフィルター引数 以下の表では、以下のユーティリティの引数の定義方法について説明しています。 + `Util.transform.toSubscriptionFilter(objFilter, ignoredFields?, rules?): SubscriptionFilter` ------ #### [ Argument 1: Map ] 引数 1 は、以下のキー値を持つ `Map` オブジェクトです。 + フィールド名 + "and" + "or" フィールド名をキーとする場合、これらのフィールドのエントリの条件は `"operator" : "value"` という形式になります。 次の例では、`Map` にエントリを追加する方法を示します。 ``` "field_name" : { "operator1" : value } ## We can have multiple conditions for the same field_name: "field_name" : { "operator1" : value "operator2" : value . . . } ``` フィールドに 2 つ以上の条件が設定されている場合、これらの条件はすべて OR 演算を使用するものとみなされます。 入力 `Map` には「and」と「or」をキーとして使用することもできます。つまり、その中のすべてのエントリは、キーに応じて AND または OR ロジックを使用して結合する必要があります。キー値「and」と「or」には条件の配列が必要です。 ``` "and" : [ { "field_name1" : { "operator1" : value } }, { "field_name2" : { "operator1" : value } }, . . ]. ``` 「and」と「or」はネストできることに注意してください。つまり、「and/or」を別の「and/or」ブロック内にネストしてもかまいません。ただし、これは単純なフィールドでは機能しません。 ``` "and" : [ { "field_name1" : { "operator" : value } }, { "or" : [ { "field_name2" : { "operator" : value } }, { "field_name3" : { "operator" : value } } ]. ``` 次の例は、`util.transform.toSubscriptionFilter(Map) : Map`を使用して*引数 1* を入力したものです。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 2000 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 2: List ] 引数 2 には、`SubscriptionFilter` 式オブジェクトを作成するときに入力 `Map` (引数 1) で考慮してはいけないフィールド名の `List` が含まれています。`List` は空になることもあります。 次の例は、`util.transform.toSubscriptionFilter(Map, List) : Map` を使用した引数 1 と引数 2 の入力を示しています。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引数 2: リスト: ``` ["percentageUp", "author"] ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 3: Map ] 引数 3 は、フィールド名をキー値とする `Map` オブジェクトです (「and」や「or」は使用できません)。フィールド名がキーの場合、これらのフィールドの条件は `"operator" : "value"` という形式のエントリになります。引数 1 とは異なり、引数 3 では同じキーに複数の条件を設定できません。さらに、引数 3 には「and」や「or」句がないため、ネストも必要ありません。 引数 3 は厳密な規則のリストを表し、これらの条件の**少なくとも 1 つ**が満たされてフィルタを通過するように `SubscriptionFilter` 式オブジェクトに追加されます。 ``` { "fieldname1": { "operator": value }, "fieldname2": { "operator": value } } . . . ``` 次の例は、`util.transform.toSubscriptionFilter(Map, List, Map) : Map` を使用した*引数 1*、*引数 2*、*引数 3* の入力を示しています。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "lt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引数 2: リスト: ``` ["percentageUp", "author"] ``` 引数 3: マップ: ``` { "upvotes": { "gte": 250 }, "author": { "eq": "Person1" } } ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "upvotes", "operator": "gte", "value": 250 } ] }, { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "author", "operator": "eq", "value": "Person1" } ] } ] } ``` ------ # util.str の文字列ヘルパー `util.str` には一般的な文字列操作を支援するメソッドが含まれています。 ## util.str utils リスト **`util.str.normalize(String, String)`** NFC、NFD、NFKC、または NFKD の 4 つのユニコード正規化形式のいずれかを使用して文字列を正規化します。最初の引数は正規化する文字列です。2 番目の引数は、正規化プロセスに使用する正規化タイプを指定する「nfc」「nfd」「nfkc」「nfkd」のいずれかです。 # 拡張子 `extensions` には、リゾルバー内で追加のアクションを行うためのメソッドセットが含まれています。 ## 拡張子の使用 **`extensions.evictFromApiCache(typeName: string, fieldName: string, keyValuePair: Record) : Object`** AWS AppSync サーバー側のキャッシュから項目を削除します。最初の引数は型名です。2 番目の引数はフィールド名です。3 番目の引数は、キャッシュキー値を指定するキーと値のペア項目を含むオブジェクトです。オブジェクト内の項目は、キャッシュされたリゾルバーの `cachingKey` のキャッシュキーと同じ順序で配置する必要があります。キャッシュの詳細については、「[キャッシング動作](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html#caching-behavior)」を参照してください。 **例 1:** この例では、呼び出されたキャッシュキー `context.arguments.semester` が使用されたリゾルバー `Query.allClasses` に対してキャッシュされた項目がエビクションされています。ミューテーションが呼び出されてリゾルバーが実行され、エントリが正常にクリアされると、レスポンスには拡張子オブジェクトに、削除されたエントリの数を示す `apiCacheEntriesDeleted` 値が含まれます。 ``` import { util, extensions } from '@aws-appsync/utils'; export const request = (ctx) => ({ payload: null }); export function response(ctx) { extensions.evictFromApiCache('Query', 'allClasses', { 'context.arguments.semester': ctx.args.semester, }); return null; } ``` この関数はミューテーションに対して**のみ**機能し、クエリでは機能しません。 ## サブスクリプションの延長 **`extensions.setSubscriptionFilter(filterJsonObject)`** 強化されたサブスクリプションフィルターを定義します。各サブスクリプション通知イベントは、提供されたサブスクリプションフィルタに対して評価され、すべてのフィルタが `true` に評価された場合、クライアントに通知を配信します。引数は `filterJsonObject` です (この引数の詳細については、以下の「*引数: filterJsonObject*」セクションを参照してください)。「[強化されたサブスクリプションのフィルタリング](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-enhanced-filtering.html)」を参照してください。 この拡張関数は、サブスクリプションリゾルバーのレスポンスハンドラーでのみ使用できます。また、フィルターの作成にも `util.transform.toSubscriptionFilter` を使用することをおすすめします。 **`extensions.setSubscriptionInvalidationFilter(filterJsonObject)`** サブスクリプション無効化フィルターを定義します。サブスクリプションフィルタは無効化ペイロードに照らして評価されてから、フィルターが `true` と評価された場合、与えられたサブスクリプションを無効にします。引数は `filterJsonObject` です (この引数の詳細については、以下の「*引数: filterJsonObject*」セクションを参照してください)。「[強化されたサブスクリプションのフィルタリング](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-enhanced-filtering.html)」を参照してください。 この拡張関数は、サブスクリプションリゾルバーのレスポンスハンドラーでのみ使用できます。フィルターの作成にも `util.transform.toSubscriptionFilter` を使用することをおすすめします。 **`extensions.invalidateSubscriptions(invalidationJsonObject)`** ミューテーションによるサブスクリプションの無効化を開始するのに使用します。引数は `invalidationJsonObject` です (この引数の詳細については、以下の「*引数: InvalidationJsonObject*」セクションを参照してください)。 この拡張関数はミューテーションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。 1 つのリクエストで使用できるユニークな `extensions.invalidateSubscriptions()` メソッド呼び出しは 5 つまでです。この制限を超えた場合、GraphQL エラーが表示されます。 ## 引数: filterJsonObject JSON オブジェクトは、サブスクリプションフィルターまたは無効化フィルターのいずれかを定義します。これは、`filterGroup` 内のフィルターの配列です。各フィルターは個別のフィルターの集まりです。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 各フィルターには次の 3 つの属性があります。 + `fieldName` – GraphQL スキーマフィールド。 + `operator` – オペレータータイプ。 + `value` – サブスクリプション通知 `fieldName` 値と比較する値。 以下は、これらの属性の割り当ての例です。 ``` { "fieldName" : "severity", "operator" : "le", "value" : context.result.severity } ``` ## 引数: invalidationJsonObject `invalidationJsonObject` では以下が定義されます。 + `subscriptionField` – 無効にする GraphQL スキーマのサブスクリプション。`subscriptionField`で文字列として定義されている 1 つのサブスクリプションは無効とみなされます。 + `payload` — 無効化フィルターがその値に対して `true` と評価された場合に、サブスクリプションを無効化するための入力として使用されるキーと値のペアリスト。 以下の例では、サブスクリプションリゾルバーで定義された無効化フィルターが `payload` 値に対して `true` と評価されたとき、`onUserDelete` サブスクリプションを使用してサブスクライブして接続しているクライアントを無効にします。 ``` export const request = (ctx) => ({ payload: null }); export function response(ctx) { extensions.invalidateSubscriptions({ subscriptionField: 'onUserDelete', payload: { group: 'Developer', type: 'Full-Time' }, }); return ctx.result; } ``` # util.xml の XML ヘルパー `util.xml`には、XML 文字列変換に役立つメソッドが含まれています。 ## util.xml utils リスト **`util.xml.toMap(String) : Object`** XML 文字列を辞書に変換します。 **例 1:** ``` Input: 1 Getting started with GraphQL Output (object): { "posts":{ "post":{ "id":1, "title":"Getting started with GraphQL" } } } ``` **例 2:** ``` Input: 1 Getting started with GraphQL 2 Getting started with AppSync Output (JavaScript object): { "posts":{ "post":[ { "id":1, "title":"Getting started with GraphQL" }, { "id":2, "title":"Getting started with AppSync" } ] } } ``` **`util.xml.toJsonString(String, Boolean?) : String`** XML 文字列を JSON 文字列に変換します。これは、出力が文字列である点を除き、`toMap` に似ています。これは、XML レスポンスを HTTP オブジェクトから JSON に直接変換し、返す場合に便利です。オプションの boolean パラメータを設定して、JSON を文字列でエンコードするかどうかを決定できます。 # DynamoDB のAWS AppSync JavaScript リゾルバー関数リファレンス AWS AppSync DynamoDB 関数を使用すると、受信 [GraphQL](https://graphql.org) リクエストを DynamoDB 呼び出しにマッピングし、DynamoDB レスポンスを GraphQL にマッピングすることで、GraphQL を使用してアカウント内の既存の Amazon DynamoDB テーブルにデータを保存および取得できます。 DynamoDB このセクションでは、サポートされる DynamoDB オペレーションのリクエストハンドラーとレスポンスハンドラーについて説明します。 + [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-getitem.html) - GetItem リクエストでは、DynamoDB 関数に DynamoDB への GetItem リクエストを行うように指示し、DynamoDB 内の項目のキーと、一貫した読み取りを使用するかどうかを指定できます。 + [PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-putitem.html) - PutItem リクエストマッピングドキュメントでは、DynamoDB 関数に DynamoDB への PutItem リクエストを行うように指示し、DynamoDB の項目のキー、項目の全内容 (キーと attributeValues で構成される)、およびオペレーションが成功するための条件を指定できます。 + [UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-updateitem.html) - UpdateItem リクエストでは、DynamoDB 関数に DynamoDB への UpdateItem リクエストを行うように指示し、DynamoDB の項目のキー、DynamoDB の項目を更新する方法を説明する更新式、およびオペレーションが成功するための条件を指定できます。 + [DeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-deleteitem.html) - DeleteItem リクエストでは、DynamoDB 関数に DynamoDB に DeleteItem リクエストを行うように指示し、DynamoDB 内の項目のキーと、オペレーションが成功するための条件を指定できます。 + [Query](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-query.html) - Query リクエストオブジェクトを使用すると、DynamoDB リゾルバーに DynamoDB へのクエリリクエストを行うように指示できます。また、キー式、使用するインデックス、追加のフィルター、返す項目の数、一貫した読み取りを使用するかどうか、クエリの方向 (前方または後方)、ページ分割トークンを指定できます。 + [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-scan.html) - Scan リクエストは、DynamoDB 関数に DynamoDB への Scan リクエストを指示することができ、結果を除外するフィルタ、使用するインデックス、返すアイテムの数、一貫性のある読み取りを使用するかどうか、ページ分割トークン、並列スキャンを指定することができます。 + [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-sync.html) - Sync リクエストオブジェクトを使用すると、DynamoDB テーブルからすべての結果を取得し、最後のクエリ (差分更新) 以降に変更されたデータのみを受け取ることができます。Sync リクエストは、バージョン管理された DynamoDB データソースに対してのみ行うことができます。フィルタを指定して、結果、返す項目の数、ページ分割トークン、および最後の Sync オペレーションが開始された日時を除外できます。 + [BatchGetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-get-item.html) - BatchGetItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchGetItem リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストオブジェクトでは、項目を取得するテーブル名と、各テーブルから取得する項目のキーを指定する必要があります。 + [BatchDeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-delete-item.html) - BatchDeleteItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchWriteItem リクエストで、複数のテーブルから複数の項目を削除するように指定できます。このリクエストオブジェクトでは、項目を削除するテーブル名と、各テーブルから削除する項目のキーを指定する必要があります。 + [BatchPutItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-batch-put-item.html) - BatchPutItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchWriteItem リクエストオブジェクトを使用すると リクエストで、複数のテーブルに複数の項目を配置するように指定できます。このリクエストオブジェクトでは、項目を配置するテーブル名と、各テーブルに配置する完全な項目を指定する必要があります。 + [TransactGetItems](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-get-items.html) - TransactGetItems リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への TransactGetItems リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストオブジェクトでは、項目を取得する各リクエスト項目のテーブル名と、各テーブルから取得する各リクエスト項目のキーを指定する必要があります。 + [TransactWriteItems](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-write-items.html) - TransactWriteItems リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への TransactWriteItems リクエストで、複数のテーブルに複数の項目を書き込むように指定できます。このリクエストオブジェクトでは、各リクエスト項目の宛先テーブル名、実行する各リクエスト項目のオペレーション、および書き込む各リクエスト項目のキーを指定する必要があります。 + [ 型システム (リクエストマッピング) ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-typed-values-request.html) - DynamoDB 型入力が AWS AppSync リクエストに統合される方法について詳しく説明します。 + [型システム (レスポンスマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-typed-values-responses.html) - DynamoDB タイプがレスポンスペイロードで GraphQL または JSON に自動的に変換される方法について詳しく説明します。 + [フィルター](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-filter.html) - クエリおよびスキャンオペレーションのフィルターの詳細について説明します。 + [条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-condition-expressions.html) - PutItem オペレーション、UpdateItem オペレーション、DeleteItem オペレーションの条件式について説明します。 + [トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions.html) - TransactWriteItems オペレーションの条件式について説明します。 + [プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-projections.html) - 読み取りオペレーションで属性を指定する方法について説明します。 # GetItem `GetItem` リクエストでは、 AWS AppSync DynamoDB 関数に DynamoDB への`GetItem`リクエストを行うように指示し、以下を指定できます。 + DynamoDB の項目のキー + 整合性のある読み込みを使用するかどうか `GetItem` リクエストの構造は次のとおりです。 ``` type DynamoDBGetItem = { operation: 'GetItem'; key: { [key: string]: any }; consistentRead?: ConsistentRead; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; ``` 各フィールドの定義は以下のようになります。 ## GetItem フィールド ### GetItem フィールドリスト **`operation`** 実行する DynamoDB の処理。`GetItem` DynamoDB の処理を実行するには、これを `GetItem` に設定する必要があります。この値は必須です。 **`key`** DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 **`consistentRead`** DynamoDB で強力な整合性のある読み込みを実行するかどうかを示します。これはオプションであり、デフォルトは `false` です。 **`projection`** DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。 DynamoDB から返された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキス結果ト (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (レスポンスマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 ## 例 次の例は、GraphQL `getThing(foo: String!, bar: String!)` クエリの関数リクエストハンドラーです。 ``` export function request(ctx) { const {foo, bar} = ctx.args return { operation : "GetItem", key : util.dynamodb.toMapValues({foo, bar}), consistentRead : true } } ``` DynamoDB `GetItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)」を参照してください。 # PutItem `PutItem` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB 関数に DynamoDB への`PutItem`リクエストを行うように指示し、以下を指定できます。 + DynamoDB の項目のキー + 項目の完全なコンテンツ (`key` および `attributeValues` で構成されます) + 処理が成功する条件 `PutItem` リクエストの構造は次のとおりです。 ``` type DynamoDBPutItemRequest = { operation: 'PutItem'; key: { [key: string]: any }; attributeValues: { [key: string]: any}; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; }; ``` 各フィールドの定義は以下のようになります。 ## PutItem フィールド ### PutItem フィールドリスト **`operation`** 実行する DynamoDB の処理。`PutItem` DynamoDB の処理を実行するには、これを `PutItem` に設定する必要があります。この値は必須です。 **`key`** DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 **`attributeValues`** DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。このフィールドはオプションです。 **`condition`** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、`PutItem` リクエストはその項目の既存のエントリを上書きします。条件の詳細については、「[条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)」を参照してください。この値はオプションです。 **`_version`** 項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。 **`customPartitionKey`** 有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。 **`populateIndexFields`** ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。 DynamoDB に書き込まれた項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB に書き込まれた項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (レスポンスマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 ## 例 1 次の例は、GraphQL ミューテーション `updateThing(foo: String!, bar: String!, name: String!, version: Int!)` の関数リクエストハンドラーです。 指定したキーに対応する項目がない場合は、作成されます。指定したキーに対応する項目がすでにある場合は、上書きされます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), }; } ``` ## 例 2 次の例は、GraphQL ミューテーション `updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!)` の関数リクエストハンドラーです。 この例では、DynamoDB に現在ある項目の `version` フィールドに `expectedVersion` が設定されていることを確認します。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, name, expectedVersion } = ctx.args; const values = { name, version: expectedVersion + 1 }; let condition = util.transform.toDynamoDBConditionExpression({ version: { eq: expectedVersion }, }); return { operation: 'PutItem', key: util.dynamodb.toMapValues({ foo, bar }), attributeValues: util.dynamodb.toMapValues(values), condition, }; } ``` DynamoDB `PutItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)」を参照してください。 # UpdateItem `UpdateItem` リクエストでは、 AWS AppSync DynamoDB 関数に DynamoDB への`UpdateItem`リクエストを行うように指示し、以下を指定できます。 + DynamoDB の項目のキー + DynamoDB の項目を更新する方法を示す更新式 + 処理が成功する条件 `UpdateItem` リクエストの構造は次のとおりです。 ``` type DynamoDBUpdateItemRequest = { operation: 'UpdateItem'; key: { [key: string]: any }; update: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; }; ``` 各フィールドの定義は以下のようになります。 ## UpdateItem フィールド ### UpdateItem フィールドリスト **`operation`** 実行する DynamoDB の処理。`UpdateItem` DynamoDB の処理を実行するには、これを `UpdateItem` に設定する必要があります。この値は必須です。 **`key`** DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 **`update`** `update` セクションには、 DynamoDBの項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、「[DynamoDB UpdateExpressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)」のドキュメントを参照してください。このセクションは必須です。 `update` セクションには次の 3 つのコンポーネントがあります。 ** `expression` ** 更新式です。この値は必須です。 ** `expressionNames` ** 式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。 ** `expressionValues` ** 式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この指定は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。 **`condition`** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、`UpdateItem` リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件の詳細については、「[条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)」を参照してください。この値はオプションです。 **`_version`** 項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。 **`customPartitionKey`** 有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。 **`populateIndexFields`** ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。 DynamoDB の更新された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 ## 例 1 次の例は、GraphQL ミューテーション `upvote(id: ID!)` の関数リクエストハンドラーです。 この例では、DynamoDB の項目の `upvotes` フィールドと `version` フィールドが 1 ずつ増加されます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id } = ctx.args; return { operation: 'UpdateItem', key: util.dynamodb.toMapValues({ id }), update: { expression: 'ADD #votefield :plusOne, version :plusOne', expressionNames: { '#votefield': 'upvotes' }, expressionValues: { ':plusOne': { N: 1 } }, }, }; } ``` ## 例 2 次の例は、GraphQL ミューテーション `updateItem(id: ID!, title: String, author: String, expectedVersion: Int!)` の関数リクエストハンドラーです。 これは、引数を確認して、クライアントから入力された引数のみを含む更新式を動的に生成する複雑な例です。たとえば、`title` と `author` を省略すると、それらは更新されません。引数が指定されているが、その値が `null` の場合、そのフィールドは DynamoDB のオブジェクトから削除されます。最後に、この処理内の条件によって、DynamoDB に現在ある項目の `version` フィールドに `expectedVersion` が設定されているかどうかを確認します。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { args: { input: { id, ...values } } } = ctx; const condition = { id: { attributeExists: true }, version: { eq: values.expectedVersion }, }; values.expectedVersion += 1; return dynamodbUpdateRequest({ keys: { id }, values, condition }); } /** * Helper function to update an item * @returns an UpdateItem request */ function dynamodbUpdateRequest(params) { const { keys, values, condition: inCondObj } = params; const sets = []; const removes = []; const expressionNames = {}; const expValues = {}; // Iterate through the keys of the values for (const [key, value] of Object.entries(values)) { expressionNames[`#${key}`] = key; if (value) { sets.push(`#${key} = :${key}`); expValues[`:${key}`] = value; } else { removes.push(`#${key}`); } } let expression = sets.length ? `SET ${sets.join(', ')}` : ''; expression += removes.length ? ` REMOVE ${removes.join(', ')}` : ''; const condition = JSON.parse( util.transform.toDynamoDBConditionExpression(inCondObj) ); return { operation: 'UpdateItem', key: util.dynamodb.toMapValues(keys), condition, update: { expression, expressionNames, expressionValues: util.dynamodb.toMapValues(expValues), }, }; } ``` DynamoDB `UpdateItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)」を参照してください。 # DeleteItem `DeleteItem` リクエストでは、 AWS AppSync DynamoDB 関数に DynamoDB への`DeleteItem`リクエストを行うように指示し、以下を指定できます。 + DynamoDB の項目のキー + 処理が成功する条件 `DeleteItem` リクエストの構造は次のとおりです。 ``` type DynamoDBDeleteItemRequest = { operation: 'DeleteItem'; key: { [key: string]: any }; condition?: ConditionCheckExpression; customPartitionKey?: string; populateIndexFields?: boolean; _version?: number; }; ``` 各フィールドの定義は以下のようになります。 ## DeleteItem フィールド ### DeleteItem フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`DeleteItem` DynamoDB の処理を実行するには、これを `DeleteItem` に設定する必要があります。この値は必須です。 ** `key` ** DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 ** `condition` ** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、`DeleteItem` リクエストによって、現在の状態にかかわらず、項目が削除されます。条件の詳細については、「[条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)」を参照してください。この値はオプションです。 ** `_version` ** 項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。 **`customPartitionKey`** 有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。 **`populateIndexFields`** ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。 DynamoDB から削除された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 ## 例 1 次の例は、GraphQL ミューテーション `deleteItem(id: ID!)` の関数リクエストハンドラーです。この ID に対応する項目がある場合は、削除されます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { return { operation: 'DeleteItem', key: util.dynamodb.toMapValues({ id: ctx.args.id }), }; } ``` ## 例 2 次の例は、GraphQL ミューテーション `deleteItem(id: ID!, expectedVersion: Int!)` の関数リクエストハンドラーです。この ID に対応する項目がある場合は、その `version` フィールドに `expectedVersion` が設定されているときにのみ削除されます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id, expectedVersion } = ctx.args; const condition = { id: { attributeExists: true }, version: { eq: expectedVersion }, }; return { operation: 'DeleteItem', key: util.dynamodb.toMapValues({ id }), condition: util.transform.toDynamoDBConditionExpression(condition), }; } ``` DynamoDB `DeleteItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)」を参照してください。 # クエリ `Query` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`Query`リクエストを行うように指示し、以下を指定できます。 + キー式 + 使用するインデックス + 任意の追加フィルタ + 返す項目の数 + 整合性のある読み込みを使用するかどうか + クエリの方向 (前方または後方) + ページ分割トークン `Query` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBQueryRequest = { operation: 'Query'; query: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; index?: string; nextToken?: string; limit?: number; scanIndexForward?: boolean; consistentRead?: boolean; select?: 'ALL_ATTRIBUTES' | 'ALL_PROJECTED_ATTRIBUTES' | 'SPECIFIC_ATTRIBUTES'; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; ``` 各フィールドの定義は以下のようになります。 ## Query フィールド ### Query フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`Query` DynamoDB の処理を実行するには、これを `Query` に設定する必要があります。この値は必須です。 ** `query` ** `query` セクションには、DynamoDB から取得する項目を指示するキー条件式を指定することができます。キー条件式の記述方法の詳細については、[DynamoDB KeyConditions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)を参照してください。このセクションの指定は必須です。 ** `expression` ** クエリ式です。このフィールドの指定は必須です。 ** `expressionNames` ** 式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。 ** `expressionValues` ** 式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。 ** `filter` ** DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用する追加フィルタです。フィルタの詳細については、「[フィルタ](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)」を参照してください。このフィールドはオプションです。 ** `index` ** クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。 ** `nextToken` ** 前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。 ** `limit` ** 評価する項目の最大数 (一致する項目の数であるとは限りません)。このフィールドはオプションです。 ** `scanIndexForward` ** クエリを前方と後方のどちらに実行するかを示すブール値です。このフィールドはオプションであり、デフォルトは `true` です。 ** `consistentRead` ** DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは `false` です。 ** `select` ** デフォルトでは、 AWS AppSync DynamoDB リゾルバーはインデックスに射影された属性のみを返します。より多くの属性が必要な場合に、このフィールドを設定できます。このフィールドはオプションです。サポートされている値には以下があります。 ** `ALL_ATTRIBUTES` ** 指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。 ** `ALL_PROJECTED_ATTRIBUTES` ** インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は `ALL_ATTRIBUTES` を指定した場合と同等になります。 **`SPECIFIC_ATTRIBUTES`** `projection` の `expression` にリストされている属性のみを返します。この戻り値は、`Select` の値を指定せずに `projection` の `expression` を指定するのと同じです。 **`projection`** DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。 DynamoDB からの結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 結果は以下の構造を持ちます。 ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10 } ``` 各フィールドの定義は以下のようになります。 ** `items` ** DynamoDB クエリで返された項目を含むリストです。 ** `nextToken` ** さらに結果がある場合、`nextToken` には別のリクエストで使用できるページ分割トークンが含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは、異なる関数やリゾルバー間では使用できないことにも注意してください。 ** `scannedCount` ** フィルタ式 (ある場合) が適用される前に、クエリの条件式に一致した項目の数です。 ## 例 次の例は、GraphQL クエリ`getPosts(owner: ID!)` の関数リクエストハンドラーです。 この例では、テーブルのグローバルセカンダリインデックスにクエリが実行され、指定した ID が所有するすべての投稿が返されます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { owner } = ctx.args; return { operation: 'Query', query: { expression: 'ownerId = :ownerId', expressionValues: util.dynamodb.toMapValues({ ':ownerId': owner }), }, index: 'owner-index', }; } ``` DynamoDB `Query` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)」を参照してください。 # Scan `Scan` リクエストでは、 AWS AppSync DynamoDB 関数に DynamoDB への`Scan`リクエストを行うように指示し、以下を指定できます。 + 結果を除外するフィルタ + 使用するインデックス + 返す項目の数 + 整合性のある読み込みを使用するかどうか + ページ分割トークン + 並列スキャン `Scan` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBScanRequest = { operation: 'Scan'; index?: string; limit?: number; consistentRead?: boolean; nextToken?: string; totalSegments?: number; segment?: number; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; ``` 各フィールドの定義は以下のようになります。 ## Scan フィールド ### Scan フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`Scan` DynamoDB の処理を実行するには、これを `Scan` に設定する必要があります。この値は必須です。 ** `filter` ** DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「[フィルタ](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)」を参照してください。このフィールドはオプションです。 ** `index` ** クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。 ** `limit` ** 一度に評価する項目の最大数です。このフィールドはオプションです。 ** `consistentRead` ** DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは `false` です。 ** `nextToken` ** 前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。 ** `select` ** デフォルトでは、 AWS AppSync DynamoDB 関数はインデックスに射影される属性のみを返します。より多くの属性が必要な場合にこのフィールドを設定します。このフィールドはオプションです。サポートされている値には以下があります。 ** `ALL_ATTRIBUTES` ** 指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。 ** `ALL_PROJECTED_ATTRIBUTES` ** インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は `ALL_ATTRIBUTES` を指定した場合と同等になります。 **`SPECIFIC_ATTRIBUTES`** `projection` の `expression` にリストされている属性のみを返します。この戻り値は、`Select` の値を指定せずに `projection` の `expression` を指定するのと同じです。 ** `totalSegments` ** 並列スキャンが実行されるまでにテーブルを分割するセグメントの数です。このフィールドはオプションですが、`segment` を指定した場合には指定する必要があります。 ** `segment` ** 並列スキャンの実行時のこの処理でのテーブルセグメントです。このフィールドはオプションですが、`totalSegments` を指定した場合には指定する必要があります。 **`projection`** DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。 DynamoDB スキャンにより返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 結果は以下の構造を持ちます。 ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10 } ``` 各フィールドの定義は以下のようになります。 ** `items` ** DynamoDB スキャンにより返された項目を含むリストです。 ** `nextToken` ** さらに結果がある場合、 には、別のリクエストで使用できるページ分割トークン`nextToken`が含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なる関数間では使用できません。 ** `scannedCount` ** フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。 ## 例 1 次の例は、GraphQLクエリ: `allPosts` の関数リクエストハンドラーです。 この例では、テーブル内のすべてのエントリが返されます。 ``` export function request(ctx) { return { operation: 'Scan' }; } ``` ## 例 2 次の例は、GraphQLクエリ: `postsMatching(title: String!)` の関数リクエストハンドラーです。 この例では、タイトルが `title` 引数で始まるテーブル内のすべてのエントリが返されます。 ``` export function request(ctx) { const { title } = ctx.args; const filter = { filter: { beginsWith: title } }; return { operation: 'Scan', filter: JSON.parse(util.transform.toDynamoDBFilterExpression(filter)), }; } ``` DynamoDB `Scan` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)」を参照してください。 # 同期 `Sync` リクエストオブジェクトを使用すると、DynamoDB テーブルからすべての結果を取得し、最後のクエリ (差分更新) 以降に変更されたデータのみを受け取ることができます。`Sync` リクエストは、バージョン管理された DynamoDB データソースに対してのみ実行できます。以下を指定できます。 + 結果を除外するフィルタ + 返す項目の数 + ページ分割トークン + 最後の `Sync` オペレーションが開始された日時 `Sync` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBSyncRequest = { operation: 'Sync'; basePartitionKey?: string; deltaIndexName?: string; limit?: number; nextToken?: string; lastSync?: number; filter?: { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: any }; }; }; ``` 各フィールドの定義は以下のようになります。 ## Sync フィールド ### Sync フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`Sync` の処理を実行するには、これに `Sync` を設定する必要があります。この値は必須です。 ** `filter` ** DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「[フィルタ](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)」を参照してください。このフィールドはオプションです。 ** `limit` ** 一度に評価する項目の最大数です。このフィールドはオプションです。省略した場合、デフォルトの制限は `100` 項目に設定されます。このフィールドの最大値は `1000` 項目です。 ** `nextToken` ** 前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。 ** `lastSync` ** 最後に成功した `Sync` オペレーションが開始されたエポックミリ秒単位の時刻。指定すると、`lastSync` 以降に変更された項目のみが返されます。このフィールドはオプションです。最初の `Sync` オペレーションからすべてのページを取得した後にのみ入力する必要があります。省略した場合は、*ベース*テーブルの結果が返されます。それ以外の場合は、*差分*テーブルの結果が返されます。 **`basePartitionKey`** `Sync` オペレーションを実行する際に使用される*ベース*テーブルのパーティションキー。このフィールドにより、テーブルがカスタムパーティションキーを使用している場合に `Sync` オペレーションを実行できます。これはオプションのフィールドです。 **`deltaIndexName`** `Sync` オペレーションに使用されるインデックス。このインデックスは、テーブルがカスタムパーティションキーを使用する場合に、デルタストアテーブル全体で `Sync` オペレーション作を有効にするために必要です。`Sync` オペレーションは GSI (`gsi_ds_pk` と `gsi_ds_sk` で作成) 上で実行されます。このフィールドはオプションです。 DynamoDB 同期により返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、コンテキスト結果 (`context.result`) で参照できます。 DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)」を参照してください。 JavaScript リゾルバーの詳細については、「[JavaScript リゾルバーの概要](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)」を参照してください。 結果は以下の構造を持ちます。 ``` { items = [ ... ], nextToken = "a pagination token", scannedCount = 10, startedAt = 1550000000000 } ``` 各フィールドの定義は以下のようになります。 ** `items` ** 同期により返された項目を含むリストです。 ** `nextToken` ** さらに結果がある場合、 には、別のリクエストで使用できるページ分割トークン`nextToken`が含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なる関数間では使用できません。 ** `scannedCount` ** フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。 ** `startedAt` ** エポックミリ秒単位の時刻ですが、同期オペレーションが開始されれば、ローカルに保存して別のリクエストで `lastSync` の引数として使用することができます。ページ分割トークンがリクエストに含まれている場合、この値は、結果の最初のページのリクエストによって返されたものと同じになります。 ## 例 次の例は、GraphQLクエリ: `syncPosts(nextToken: String, lastSync: AWSTimestamp)` の関数リクエストハンドラーです。 この例では、`lastSync` を省略すると、ベーステーブルのすべてのエントリが返されます。`lastSync` が指定されている場合は、`lastSync` 以降に変更された差分同期テーブルのエントリのみが返されます。 ``` export function request(ctx) { const { nextToken, lastSync } = ctx.args; return { operation: 'Sync', limit: 100, nextToken, lastSync }; } ``` # BatchGetItem `BatchGetItem` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB 関数に、複数のテーブルにまたがる可能性のある複数の項目を取得するように DynamoDB に`BatchGetItem`リクエストするように指示できます。このリクエストオブジェクトでは、以下の情報を指定する必要があります。 + 項目を取得するテーブルの名前 + 各テーブルから取得する項目のキー DynamoDB の `BatchGetItem` 制限が適用されるため、**条件式を指定することはできません**。 `BatchGetItem` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBBatchGetItemRequest = { operation: 'BatchGetItem'; tables: { [tableName: string]: { keys: { [key: string]: any }[]; consistentRead?: boolean; projection?: { expression: string; expressionNames?: { [key: string]: string }; }; }; }; }; ``` 各フィールドの定義は以下のようになります。 ## BatchGetItem フィールド ### BatchGetItem フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`BatchGetItem` DynamoDB の処理を実行するには、これを `BatchGetItem` に設定する必要があります。この値は必須です。 ** `tables` ** 項目を取得する DynamoDB テーブル。値は、キーとしてテーブル名が指定されているマップです。1 つ以上のテーブルを指定する必要があります。この `tables` の値は必須です。 ** `keys` ** 取り出す項目のプライマリキーを表す DynamoDB キーのリスト。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。 ** `consistentRead` ** *GetItem* 処理の実行時に整合性のある読み込みを使用するかどうか。この値はオプションであり、デフォルトは *false* です。 **`projection`** DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。 覚えておくべきポイント: + 項目がテーブルから取得されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。 + 呼び出し結果は、リクエストオブジェクト内で提供された順序に基づいて、テーブル別にソートされます。 + `BatchGetItem` 内の各 `Get` コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。 + `BatchGetItem` は 100 キーに制限されています。 次の例の関数リクエストハンドラーの場合: ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'BatchGetItem', tables: { authors: [util.dynamodb.toMapValues({ authorId })], posts: [util.dynamodb.toMapValues({ authorId, postId })], }, }; } ``` `ctx.result` で使用可能な呼び出し結果は以下のとおりです。 ``` { "data": { "authors": [null], "posts": [ // Was retrieved { "authorId": "a1", "postId": "p2", "postTitle": "title", "postDescription": "description", } ] }, "unprocessedKeys": { "authors": [ // This item was not processed due to an error { "authorId": "a1" } ], "posts": [] } } ``` `ctx.error` にエラーに関する詳細が含まれています。**data** キー、**unprocessedKeys** キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedKeys** ブロックに挿入されます。 # BatchDeleteItem `BatchDeleteItem` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB 関数に、複数のテーブルにまたがる可能性のある複数の項目を削除するよう DynamoDB に`BatchWriteItem`リクエストするように指示できます。このリクエストオブジェクトでは、以下の情報を指定する必要があります。 + 項目を削除するテーブルの名前 + 各テーブルから削除する項目のキー DynamoDB の `BatchWriteItem` 制限が適用されるため、**条件式を指定することはできません**。 `BatchDeleteItem` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBBatchDeleteItemRequest = { operation: 'BatchDeleteItem'; tables: { [tableName: string]: { [key: string]: any }[]; }; }; ``` 各フィールドの定義は以下のようになります。 ## BatchDeleteItem フィールド ### BatchDeleteItem フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`BatchDeleteItem` DynamoDB の処理を実行するには、これを `BatchDeleteItem` に設定する必要があります。この値は必須です。 ** `tables` ** 項目を削除する DynamoDB テーブル。各テーブルは、削除する項目のプライマリキーを表す DynamoDB キーのリストです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。1 つ以上のテーブルを指定する必要があります。値 が必要です。 覚えておくべきポイント: + `DeleteItem` オペレーションとは対照的に、完全に削除された項目はレスポンスで返されません。渡されたキーのみが返されます。 + 項目がテーブルから削除されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。 + 呼び出し結果は、リクエストオブジェクト内で提供された順序に基づいて、テーブル別にソートされます。 + `Delete` 内部の各 `BatchDeleteItem` コマンドはアトミックです。ただし、バッチは部分的に処理できます。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。 + `BatchDeleteItem` は 25 キーに制限されています。 + このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。 次の例の関数リクエストハンドラーの場合: ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'BatchDeleteItem', tables: { authors: [util.dynamodb.toMapValues({ authorId })], posts: [util.dynamodb.toMapValues({ authorId, postId })], }, }; } ``` `ctx.result` で使用可能な呼び出し結果は以下のとおりです。 ``` { "data": { "authors": [null], "posts": [ // Was deleted { "authorId": "a1", "postId": "p2" } ] }, "unprocessedKeys": { "authors": [ // This key was not processed due to an error { "authorId": "a1" } ], "posts": [] } } ``` `ctx.error` にエラーに関する詳細が含まれています。**data** キー、**unprocessedKeys** キー、および関数リクエストオブジェクトで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedKeys** ブロックに挿入されます。 # BatchPutItem `BatchPutItem` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB 関数に、複数のテーブルにまたがる可能性のある複数の項目を配置するように DynamoDB に`BatchWriteItem`リクエストするように指示できます。このリクエストオブジェクトでは、以下の情報を指定する必要があります。 + 項目を挿入するテーブルの名前 + 各テーブルに挿入するすべての項目 DynamoDB の `BatchWriteItem` 制限が適用されるため、**条件式を指定することはできません**。 `BatchPutItem` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBBatchPutItemRequest = { operation: 'BatchPutItem'; tables: { [tableName: string]: { [key: string]: any}[]; }; }; ``` 各フィールドの定義は以下のようになります。 ## BatchPutItem フィールド ### BatchPutItem フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`BatchPutItem` DynamoDB の処理を実行するには、これを `BatchPutItem` に設定する必要があります。この値は必須です。 ** `tables` ** 項目を挿入する DynamoDB テーブル。各テーブルエントリは、この特定のテーブルに挿入する DynamoDB 項目のリストを表します。1 つ以上のテーブルを指定する必要があります。この値は必須です。 覚えておくべきポイント: + 完全に挿入された項目がレスポンスに返されます (正常に挿入された場合)。 + 項目がテーブルに挿入されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。 + 挿入された項目は、リクエストオブジェクト内で提供された順序に基づいて、テーブル別にソートされます。 + `Put` 内の各 `BatchPutItem` コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。 + `BatchPutItem` は 25 項目に制限されています。 + このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。 次の例の関数リクエストハンドラーの場合: ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId, name, title } = ctx.args; return { operation: 'BatchPutItem', tables: { authors: [util.dynamodb.toMapValues({ authorId, name })], posts: [util.dynamodb.toMapValues({ authorId, postId, title })], }, }; } ``` `ctx.result` で使用可能な呼び出し結果は以下のとおりです。 ``` { "data": { "authors": [ null ], "posts": [ // Was inserted { "authorId": "a1", "postId": "p2", "title": "title" } ] }, "unprocessedItems": { "authors": [ // This item was not processed due to an error { "authorId": "a1", "name": "a1_name" } ], "posts": [] } } ``` `ctx.error` にエラーに関する詳細が含まれています。**data** キー、**The keys data, unprocessedItems** キー、およびリクエストオブジェクトで渡された各テーブルキーは呼び出し結果に必ずあります。挿入された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedItems** ブロックに挿入されます。 # TransactGetItems `TransactGetItems` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB 関数に、複数のテーブルにまたがる可能性のある複数の項目を取得するように DynamoDB に`TransactGetItems`リクエストするように指示できます。このリクエストオブジェクトでは、以下の情報を指定する必要があります。 + 項目の取得元となる各リクエスト項目のテーブル名 + 各テーブルから取得する各リクエスト項目のキー DynamoDB の `TransactGetItems` 制限が適用されるため、**条件式を指定することはできません**。 `TransactGetItems` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBTransactGetItemsRequest = { operation: 'TransactGetItems'; transactItems: { table: string; key: { [key: string]: any }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }[]; }; }; ``` 各フィールドの定義は以下のようになります。 ## TransactGetItems フィールド ### TransactGetItems フィールドリスト ** `operation` ** 実行する DynamoDB の処理。`TransactGetItems` DynamoDB の処理を実行するには、これを `TransactGetItems` に設定する必要があります。この値は必須です。 ** `transactItems` ** 含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この `transactItems` の値は必須です。 ** `table` ** 項目の取得元となる DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。 ** `key` ** 取り出す項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。 **`projection`** DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。 覚えておくべきポイント: + トランザクションが成功すると、`items` ブロック内で取得された項目の順序はリクエスト項目の順序と同じになります。 + トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。 + リクエスト項目を取得できなくても、エラーではありません。代わりに、*null*要素が対応する位置の*項目*ブロックに表示されます。 + トランザクションのエラーが *TransactionCanceledException* である場合、`cancellationReasons` ブロックに入力されます。`cancellationReasons` ブロック内のキャンセル理由の順序は、リクエスト項目の順序と同じになります。 + `TransactGetItems` のリクエスト項目数は 100 個に制限されています。 次の例の関数リクエストハンドラーの場合: ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId } = ctx.args; return { operation: 'TransactGetItems', transactItems: [ { table: 'posts', key: util.dynamodb.toMapValues({ postId }), }, { table: 'authors', key: util.dynamodb.toMapValues({ authorId }), }, ], }; } ``` トランザクションが成功し、最初にリクエストされた項目だけが取得された場合、`ctx.result` で使用できる呼び出し結果は次のようになります。 ``` { "items": [ { // Attributes of the first requested item "post_id": "p1", "post_title": "title", "post_description": "description" }, // Could not retrieve the second requested item null, ], "cancellationReasons": null } ``` 最初のリクエスト項目によって発生した *TransactionCanceledException* が原因でトランザクションが失敗した場合、`ctx.result` で使用可能な呼び出し結果は次のようになります。 ``` { "items": null, "cancellationReasons": [ { "type":"Sample error type", "message":"Sample error message" }, { "type":"None", "message":"None" } ] } ``` `ctx.error` にエラーに関する詳細が含まれています。キー **items** と **cancellationReasons** は、`ctx.result` にあることが保証されています。 # TransactWriteItems `TransactWriteItems` リクエストオブジェクトを使用すると、 AWS AppSync DynamoDB 関数に、複数のテーブルに複数の項目を書き込むように DynamoDB に`TransactWriteItems`リクエストするように指示できます。このリクエストオブジェクトでは、以下の情報を指定する必要があります。 + 各リクエスト項目の書き込み先テーブル名 + 実行する各リクエスト項目のオペレーション。サポートされているオペレーションには、*PutItem*、*UpdateItem*、*DeleteItem*、および *ConditionCheck* の 4 種類があります。 + 書き込む各リクエスト項目のキー DynamoDB の `TransactWriteItems` 制限が適用されます。 `TransactWriteItems` リクエストオブジェクトのノードの構造は次のとおりです。 ``` type DynamoDBTransactWriteItemsRequest = { operation: 'TransactWriteItems'; transactItems: TransactItem[]; }; type TransactItem = | TransactWritePutItem | TransactWriteUpdateItem | TransactWriteDeleteItem | TransactWriteConditionCheckItem; type TransactWritePutItem = { table: string; operation: 'PutItem'; key: { [key: string]: any }; attributeValues: { [key: string]: string}; condition?: TransactConditionCheckExpression; }; type TransactWriteUpdateItem = { table: string; operation: 'UpdateItem'; key: { [key: string]: any }; update: DynamoDBExpression; condition?: TransactConditionCheckExpression; }; type TransactWriteDeleteItem = { table: string; operation: 'DeleteItem'; key: { [key: string]: any }; condition?: TransactConditionCheckExpression; }; type TransactWriteConditionCheckItem = { table: string; operation: 'ConditionCheck'; key: { [key: string]: any }; condition?: TransactConditionCheckExpression; }; type TransactConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; returnValuesOnConditionCheckFailure: boolean; }; ``` ## TransactWriteItems フィールド ### TransactWriteItems フィールドリスト **各フィールドの定義は以下のようになります。** ** `operation` ** 実行する DynamoDB の処理。`TransactWriteItems` DynamoDB の処理を実行するには、これを `TransactWriteItems` に設定する必要があります。この値は必須です。 ** `transactItems` ** 含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この `transactItems` の値は必須です。 `PutItem` の場合、各フィールドの定義は以下のようになります。 ** `table` ** 送信先のの DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。 ** `operation` ** 実行する DynamoDB の処理。`PutItem` DynamoDB の処理を実行するには、これを `PutItem` に設定する必要があります。この値は必須です。 ** `key` ** 配置する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 ** `attributeValues` ** DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。このフィールドはオプションです。 ** `condition` ** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、`PutItem` リクエストはその項目の既存のエントリを上書きします。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)」を参照してください。この値はオプションです。 `UpdateItem` の場合、各フィールドの定義は以下のようになります。 ** `table` ** 更新する DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。 ** `operation` ** 実行する DynamoDB の処理。`UpdateItem` DynamoDB の処理を実行するには、これを `UpdateItem` に設定する必要があります。この値は必須です。 ** `key` ** 更新する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 ** `update` ** `update` セクションには、 DynamoDBの項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、「[DynamoDB UpdateExpressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)」のドキュメントを参照してください。このセクションは必須です。 ** `condition` ** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、`UpdateItem` リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)」を参照してください。この値はオプションです。 `DeleteItem` の場合、各フィールドの定義は以下のようになります。 ** `table` ** 項目を削除する DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。 ** `operation` ** 実行する DynamoDB の処理。`DeleteItem` DynamoDB の処理を実行するには、これを `DeleteItem` に設定する必要があります。この値は必須です。 ** `key` ** 削除する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 ** `condition` ** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、`DeleteItem` リクエストによって、現在の状態にかかわらず、項目が削除されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)」を参照してください。この値はオプションです。 `ConditionCheck` の場合、各フィールドの定義は以下のようになります。 ** `table` ** 条件をチェックする DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。 ** `operation` ** 実行する DynamoDB の処理。`ConditionCheck` DynamoDB の処理を実行するには、これを `ConditionCheck` に設定する必要があります。この値は必須です。 ** `key` ** 条件チェックする項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この値は必須です。 ** `condition` ** DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)」を参照してください。この値は必須です。 覚えておくべきポイント: + リクエスト項目のキーのみがレスポンスに返されます (正常に挿入された場合)。キーの順序は、リクエスト項目の順序と同じです。 + トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。 + 同じ項目をターゲットにできるリクエスト項目が 2 つありません。それ以外の場合は、*TransactionCanceledException* エラーが発生します。 + トランザクションのエラーが *TransactionCanceledException* である場合、`cancellationReasons` ブロックに入力されます。リクエスト項目の条件チェックが失敗し、**かつ** `returnValuesOnConditionCheckFailure` を `false` に指定しなかった場合、テーブルに存在する項目が取得され、`item` で `cancellationReasons` ブロックの対応する位置に保存されます。 + `TransactWriteItems` のリクエスト項目数は 100 個に制限されています。 + このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。 次の例の関数リクエストハンドラーの場合: ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { authorId, postId, title, description, oldTitle, authorName } = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'PutItem', key: util.dynamodb.toMapValues({ postId }), attributeValues: util.dynamodb.toMapValues({ title, description }), condition: util.transform.toDynamoDBConditionExpression({ title: { eq: oldTitle }, }), }, { table: 'authors', operation: 'UpdateItem', key: util.dynamodb.toMapValues({ authorId }), update: { expression: 'SET authorName = :name', expressionValues: util.dynamodb.toMapValues({ ':name': authorName }), }, }, ], }; } ``` トランザクションが成功した場合、`ctx.result` で使用できる呼び出し結果は次のようになります。 ``` { "keys": [ // Key of the PutItem request { "post_id": "p1", }, // Key of the UpdateItem request { "author_id": "a1" } ], "cancellationReasons": null } ``` `PutItem` リクエストの条件チェックに失敗したためにトランザクションが失敗した場合、 で使用できる呼び出し結果は次のようになります。 ``` { "keys": null, "cancellationReasons": [ { "item": { "post_id": "p1", "post_title": "Actual old title", "post_description": "Old description" }, "type": "ConditionCheckFailed", "message": "The condition check failed." }, { "type": "None", "message": "None" } ] } ``` `ctx.error` にエラーに関する詳細が含まれています。**keys** および **cancellationReasons** が `ctx.result` に存在することが保証されています。 # 型システム (リクエストマッピング) AWS AppSync DynamoDB 関数を使用して DynamoDB テーブルを呼び出す場合、 AWS AppSync はその呼び出しで使用する各値のタイプを知る必要があります。これは、DynamoDB が GraphQL や JSON よりも多くのタイプのプリミティブ (セットやバイナリデータなど) をサポートしているためです。 AWS AppSync は、GraphQL と DynamoDB 間の変換時にいくつかのヒントを必要とします。そうしないと、テーブル内のデータの構造についていくつかの仮定を行う必要があります。 DynamoDB のデータ型の詳細については、DynamoDB の「[データ型記述子](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors)」および「[データ型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)」の各ドキュメントを参照してください。 DynamoDB の値は、単一のキーと値のペアを含む JSON オブジェクトで表されます。キーは DynamoDB の型を指定し、値はその値自身を指定します。次の例では、キー `S` は値が文字列であることを示し、値 `identifier` がその文字列値です。 ``` { "S" : "identifier" } ``` JSON オブジェクトは複数のキーと値のペアを持つことはできません。複数のキーと値のペアが指定されている場合、リクエストオブジェクトは解析されません。 DynamoDB の値は、値を指定する必要がある場合にはリクエストオブジェクトのどこかで使用されます。これが必要になる箇所には、`key` セクションと `attributeValue` セクション、および式セクションの `expressionValues` セクションが含まれています。次の例では、DynamoDB の文字列値 `identifier` が、(おそらくは `GetItem` リクエストオブジェクトの) `key` セクションの `id` フィールドに割り当てられています。 ``` "key" : { "id" : { "S" : "identifier" } } ``` **サポートされているタイプ** AWS AppSync は、次の DynamoDB スカラー、ドキュメント、およびセットタイプをサポートしています。 **文字列型 `S` ** 単一の文字列値です。DynamoDB の文字列値は次のように表されます。 ``` { "S" : "some string" } ``` 以下は使用例です。 ``` "key" : { "id" : { "S" : "some string" } } ``` **文字列セット型 `SS` ** 1 組の文字列値です。DynamoDB の文字列セット値は次のように表されます。 ``` { "SS" : [ "first value", "second value", ... ] } ``` 以下は使用例です。 ``` "attributeValues" : { "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] } } ``` **数値型 `N` ** 単一の数値です。DynamoDB の数値は次のように表されます。 ``` { "N" : 1234 } ``` 以下は使用例です。 ``` "expressionValues" : { ":expectedVersion" : { "N" : 1 } } ``` **数値セット型 `NS` ** 1 組の数値です。DynamoDB の数値セット値は次のように表されます。 ``` { "NS" : [ 1, 2.3, 4 ... ] } ``` 以下は使用例です。 ``` "attributeValues" : { "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] } } ``` **バイナリ型 `B` ** バイナリ値です。DynamoDB のバイナリ値は次のように表されます。 ``` { "B" : "SGVsbG8sIFdvcmxkIQo=" } ``` 値は実際には文字列であり、文字列はバイナリデータの base64 でエンコードされた表現です。 AWS AppSync はこの文字列をバイナリ値にデコードしてから DynamoDB に送信します。 AWS AppSync は RFC 2045 で定義されている base64 デコードスキームを使用します。base64 アルファベットにない文字は無視されます。 以下は使用例です。 ``` "attributeValues" : { "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" } } ``` **バイナリセット型 `BS` ** 1 組のバイナリ値です。DynamoDB のバイナリセット値は次のように表されます。 ``` { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] } ``` 値は実際には文字列であり、文字列はバイナリデータの base64 でエンコードされた表現です。 AWS AppSync はこの文字列をバイナリ値にデコードしてから DynamoDB に送信します。 AWS AppSync は RFC 2045 で定義されている base64 デコードスキームを使用します。base64 アルファベットにない文字は無視されます。 以下は使用例です。 ``` "attributeValues" : { "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] } } ``` **ブール型 `BOOL` ** ブール値。DynamoDB のブール値は次のように表されます。 ``` { "BOOL" : true } ``` 有効な値は、`true` と `false` のみです。 以下は使用例です。 ``` "attributeValues" : { "orderComplete" : { "BOOL" : false } } ``` **リスト型 `L` ** サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は次のように表されます。 ``` { "L" : [ ... ] } ``` この値は複合値です。リストには、サポートされる DynamoDB の値 (他のリストも含む) が 0 個以上入ります。このリストには、異なる型を混在させることもできます。 以下は使用例です。 ``` { "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] } ``` **マップ型 `M` ** サポートされる他の DynamoDB の値の、キーと値のペアの順序付けされていない集合を表します。DynamoDB のマップ値は次のように表されます。 ``` { "M" : { ... } } ``` マップには 0 個以上のキーと値のペアが入ります。キーは文字列である必要があり、値には、サポートされている DynamoDB の任意の値 (他のマップを含む) が使用できます。このマップには、異なる型を混在させることもできます。 以下は使用例です。 ``` { "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } } ``` **Null 型 `NULL` ** null 値です。DynamoDB の Null 値は次のように表されます。 ``` { "NULL" : null } ``` 以下は使用例です。 ``` "attributeValues" : { "phoneNumbers" : { "NULL" : null } } ``` 各タイプの詳細については、[DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)を参照してください。 # 型システム (レスポンスマッピング) DynamoDB からレスポンスを受信すると、 AWS AppSync はそれを GraphQL プリミティブ型と JSON プリミティブ型に自動的に変換します。DynamoDB の各属性はデコードされ、レスポンスハンドラーのコンテキストで返されます。 たとえば、DynamoDB が以下を返したとします。 ``` { "id" : { "S" : "1234" }, "name" : { "S" : "Nadia" }, "age" : { "N" : 25 } } ``` パイプラインリゾルバーから結果が返されると、 AWS AppSync はそれを次のように GraphQL および JSON タイプに変換します。 ``` { "id" : "1234", "name" : "Nadia", "age" : 25 } ``` このセクションでは、 AWS AppSync が次の DynamoDB スカラー、ドキュメント、およびセットタイプを変換する方法について説明します。 **文字列型 `S` ** 単一の文字列値です。DynamoDB 文字列値が文字列として返されます。 たとえば、DynamoDB が次の DynamoDB の文字列値を返したとします。 ``` { "S" : "some string" } ``` AWS AppSync はこれを文字列に変換します。 ``` "some string" ``` **文字列セット型 `SS` ** 1 組の文字列値です。DynamoDB 文字列セット値が文字列のリストとして返されます。 たとえば、DynamoDB が次の DynamoDB 文字列セット値を返したとします。 ``` { "SS" : [ "first value", "second value", ... ] } ``` AWS AppSync はこれを文字列のリストに変換します。 ``` [ "+1 555 123 4567", "+1 555 234 5678" ] ``` **数値型 `N` ** 単一の数値です。DynamoDB 数値が数字として返されます。 たとえば、DynamoDB が次の DynamoDB の数値を返したとします。 ``` { "N" : 1234 } ``` AWS AppSync はこれを数値に変換します。 ``` 1234 ``` **数値セット型 `NS` ** 1 組の数値です。DynamoDB 数値セットが数字のリストとして返されます。 たとえば、DynamoDB が次の DynamoDB の数値セット値を返したとします。 ``` { "NS" : [ 67.8, 12.2, 70 ] } ``` AWS AppSync はこれを数値のリストに変換します。 ``` [ 67.8, 12.2, 70 ] ``` **バイナリ型 `B` ** バイナリ値です。DynamoDB のバイナリ値は、その値を Base64 で表した文字列として返されます。 たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。 ``` { "B" : "SGVsbG8sIFdvcmxkIQo=" } ``` AWS AppSync は、値を base64 で表現した文字列に変換します。 ``` "SGVsbG8sIFdvcmxkIQo=" ``` バイナリデータは、[RFC 4648](https://tools.ietf.org/html/rfc4648) と [RFC 2045](https://tools.ietf.org/html/rfc2045) で指定されているようにして Base64 エンコーディングスキームにエンコードされます。 **バイナリセット型 `BS` ** 1 組のバイナリ値です。DynamoDB のバイナリセット値は、その値を Base64 で表した文字列のリストとして返されます。 たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。 ``` { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] } ``` AWS AppSync は、値を base64 で表現した文字列のリストに変換します。 ``` [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] ``` バイナリデータは、[RFC 4648](https://tools.ietf.org/html/rfc4648) と [RFC 2045](https://tools.ietf.org/html/rfc2045) で指定されているようにして Base64 エンコーディングスキームにエンコードされます。 **ブール型 `BOOL` ** ブール値。DynamoDB ブール値がブールとして返されます。 たとえば、DynamoDB が次の DynamoDB のブール値を返したとします。 ``` { "BOOL" : true } ``` AWS AppSync はこれをブール値に変換します。 ``` true ``` **リスト型 `L` ** サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は値のリストとして返され、内部のそれぞれの値も変換されます。 たとえば、DynamoDB が次の DynamoDB の文字列値を返したとします。 ``` { "L" : [ { "S" : "A string value" }, { "N" : 1 }, { "SS" : [ "Another string value", "Even more string values!" ] } ] } ``` AWS AppSync はこれを変換された値のリストに変換します。 ``` [ "A string value", 1, [ "Another string value", "Even more string values!" ] ] ``` **マップ型 `M` ** サポートされるその他の DynamoDB の値のキー/値の集合です。DynamoDB のマップ値は JSON オブジェクトとして返されます。それぞれのキー/値も変換されます。 たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。 ``` { "M" : { "someString" : { "S" : "A string value" }, "someNumber" : { "N" : 1 }, "stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] } } } ``` AWS AppSync はこれを JSON オブジェクトに変換します。 ``` { "someString" : "A string value", "someNumber" : 1, "stringSet" : [ "Another string value", "Even more string values!" ] } ``` **Null 型 `NULL` ** null 値です。 たとえば、DynamoDB が次の DynamoDB のブール値を返したとします。 ``` { "NULL" : null } ``` AWS AppSync はこれを null に変換します。 ``` null ``` # フィルター `Query` 処理と `Scan` 処理を使用して DynamoDB のオブジェクトにクエリを実行する場合、オプションで、結果を評価する `filter` を指定して、必要な値のみを返すことができます。 `Query` または `Scan` リクエストの filter プロパティの構造は以下のとおりです。 ``` type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; }; ``` 各フィールドの定義は以下のようになります。 ** `expression` ** クエリ式です。フィルタ式の記述方法の詳細については、「[DynamoDB QueryFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html)」および「[DynamoDB ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html)」の各ドキュメントを参照してください。このフィールドの指定は必須です。 ** `expressionNames` ** 式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは、`expression` で使用される名前のプレースホルダーに対応します。値は、DynamoDB の項目の属性名に対応する文字列である必要があります。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。 ** `expressionValues` ** 式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この指定は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。 ## 例 次の例は、リクエストのフィルターセクションです。ここでは、DynamoDB から取得されたエントリのうち、タイトルが `title` 引数で始まるもののみが返されます。 ここでは、`util.transform.toDynamoDBFilterExpression` を使用してオブジェクトから自動的にフィルターを作成します。 ``` const filter = util.transform.toDynamoDBFilterExpression({ title: { beginsWith: 'far away' }, }); const request = {}; request.filter = JSON.parse(filter); ``` これにより、以下のフィルターが生成されます。 ``` { "filter": { "expression": "(begins_with(#title,:title_beginsWith))", "expressionNames": { "#title": "title" }, "expressionValues": { ":title_beginsWith": { "S": "far away" } } } } ``` # 条件式 `PutItem`、`UpdateItem`、および `DeleteItem` の各 DynamoDB 処理を使用して DynamoDB のオブジェクトをミューテーションする場合、オプションで、処理を実行する前に、DynamoDB にある既存のオブジェクトの状態に基づいてリクエストが成功するかどうかを制御する条件式を指定することができます。 AWS AppSync DynamoDB 関数を使用すると、`PutItem`、、`UpdateItem`および `DeleteItem`リクエストオブジェクトで条件式を指定できます。また、条件が失敗し、オブジェクトが更新されなかった場合に従う戦略も指定できます。 ## 例 1 以下の `PutItem` リクエストオブジェクトには条件式がありません。その結果、同じキーに対応する項目がすでにある場合でも、項目は DynamoDB に挿入され、それにより既存の項目が上書きされます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), }; } ``` ## 例 2 次の `PutItem` オブジェクトには条件式があります。この場合、同じキーの項目が DynamoDB に存在*しない*場合のみ処理が成功します。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { foo, bar, ...values} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues(values), condition: { expression: "attribute_not_exists(id)" } }; } ``` デフォルトでは、条件チェックが失敗した場合、 AWS AppSync DynamoDB 関数はミューテーションにエラーを提供します。 ただし、 AWS AppSync DynamoDB 関数には、開発者が一般的なエッジケースを処理するのに役立ついくつかの追加機能があります。 + AWS AppSync DynamoDB 関数は、DynamoDB の現在の値が目的の結果と一致すると判断できる場合、オペレーションを成功したかのように扱います。 + エラーを返す代わりに、カスタム Lambda 関数を呼び出して、 AWS AppSync DynamoDB 関数が失敗を処理する方法を決定するように関数を設定できます。 これらの詳細については、「[条件チェックでのエラーを処理する](#condition-check)」セクションを参照してください。 DynamoDB の条件式の詳細については、「[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)」を参照してください。 ## 条件を指定する `PutItem`、`UpdateItem`、および `DeleteItem` の各リクエストオブジェクトはすべて、オプションで `condition` セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。 `condition` セクションは以下の構造を持ちます。 ``` type ConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string}; expressionValues?: { [key: string]: any}; equalsIgnore?: string[]; consistentRead?: boolean; conditionalCheckFailedHandler?: { strategy: 'Custom' | 'Reject'; lambdaArn?: string; }; }; ``` 以下のフィールドに条件を指定します。 ** `expression` ** 更新式そのものを指定します。条件式の記述方法の詳細については、[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)を参照してください。このフィールドの指定は必須です。 ** `expressionNames` ** 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは *expression* で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、*expression* で使用される式の属性名のプレースホルダーのみを入力します。 ** `expressionValues` ** 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。 残りのフィールドは、 AWS AppSync DynamoDB 関数に条件チェックの失敗を処理する方法を指示します。 ** `equalsIgnore` ** `PutItem` オペレーションの使用時に条件チェックが失敗すると、 AWS AppSync DynamoDB 関数は、DynamoDB の現在の項目と、書き込みを試みた項目を比較します。これらが同じ場合、処理は成功として扱われます。`equalsIgnore` フィールドを使用して、 AWS AppSync がその比較を実行するときに無視する属性のリストを指定できます。たとえば、唯一の違いが `version` 属性である場合、オペレーションは成功として扱われます。このフィールドはオプションです。 ** `consistentRead` ** 条件チェックが失敗すると、 AWS AppSync は強力な整合性のある読み込みを使用して DynamoDB から項目の現在の値を取得します。このフィールドを使用して、結果整合性のある読み込みを代わりに使用するよう AWS AppSync DynamoDB の関数に指示することができます。このフィールドはオプションであり、デフォルトは `true` です。 ** `conditionalCheckFailedHandler` ** このセクションでは、DynamoDB の現在の値と予想される結果を比較した後、 AWS AppSync DynamoDB 関数が条件チェックの失敗を処理する方法を指定できます。このセクションはオプションです。省略した場合、デフォルトの処理は `Reject` です。 ** `strategy` ** AWS AppSync DynamoDB 関数が DynamoDB の現在の値を期待される結果と比較した後に実行する戦略。このフィールドは必須であり、以下を値を設定できます。 ** `Reject` ** ミューテーションは失敗し、GraphQL レスポンスにエラーが追加されます。 ** `Custom` ** AWS AppSync DynamoDB 関数は、カスタム Lambda 関数を呼び出して、条件チェックの失敗を処理する方法を決定します。`strategy` が `Custom` に設定されている場合、`lambdaArn` フィールドには、呼び出す Lambda 関数の ARN が含まれている必要があります。 ** `lambdaArn` ** AWS AppSync DynamoDB の関数が、条件チェックで検出されたエラーを処理する方法を決定するために呼び出す Lambda 関数の ARN です。このフィールドは、`strategy` が `Custom` に設定されている場合のみ指定する必要があります。この機能の使用方法の詳細については、「[条件チェックでのエラーを処理する](#condition-check)」を参照してください。 ## 条件チェックでのエラーを処理する 条件チェックが失敗すると、 AWS AppSync DynamoDB 関数は `util.appendError`ユーティリティを使用して、ミューテーションのエラーとオブジェクトの現在の値を渡すことができます。ただし、 AWS AppSync DynamoDB 関数には、開発者が一般的なエッジケースを処理するのに役立ついくつかの追加機能があります。 + AWS AppSync DynamoDB 関数は、DynamoDB の現在の値が目的の結果と一致すると判断できる場合、オペレーションを成功したかのように扱います。 + エラーを返す代わりに、カスタム Lambda 関数を呼び出して、 AWS AppSync DynamoDB 関数が失敗を処理する方法を決定するように関数を設定できます。 このプロセスのフローチャートは次のとおりです。 ![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png) ### 必要な結果をチェックする 条件チェックが失敗すると、 AWS AppSync DynamoDB 関数は `GetItem` DynamoDB リクエストを実行して、DynamoDB から項目の現在の値を取得します。デフォルトでは、強力な整合性のある読み込みを使用しますが、`condition` ブロックの `consistentRead` フィールドを使用してこれを設定し、この値を期待した結果と比較することができます。 + `PutItem` オペレーションの場合、 AWS AppSync DynamoDB 関数は、現在の値を書き込みを試みた値と比較します。ただし、 にリストされている属性は比較`equalsIgnore`から除外されます。項目が同じ場合は、処理は成功として扱われ、DynamoDB から取得された項目が返されます。それ以外の場合は、設定された処理に従います。 たとえば、`PutItem` リクエストオブジェクトが以下のようになっているとします。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { id, name, version} = ctx.args return { operation: 'PutItem', key: util.dynamodb.toMapValues({foo, bar}), attributeValues: util.dynamodb.toMapValues({ name, version: version+1 }), condition: { expression: "version = :expectedVersion", expressionValues: util.dynamodb.toMapValues({':expectedVersion': version}), equalsIgnore: ['version'] } }; } ``` 現在、DynamoDB にある項目は以下のようになりました。 ``` { "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } } ``` AWS AppSync DynamoDB 関数は、書き込もうとした項目を現在の値と比較し、唯一の違いは `version`フィールドであったことを確認しますが、 `version`フィールドを無視するように設定されているため、オペレーションは成功として扱われ、DynamoDB から取得した項目を返します。 + `DeleteItem` オペレーションの場合、 AWS AppSync DynamoDB 関数は項目が DynamoDB から返されたことを確認します。項目が返されなかった場合、処理は成功として扱われます。それ以外の場合は、設定された処理に従います。 + `UpdateItem` オペレーションの場合、 AWS AppSync DynamoDB 関数には、現在 DynamoDB にある項目が期待される結果と一致するかどうかを判断するのに十分な情報がないため、設定された戦略に従います。 DynamoDB のオブジェクトの現在の状態が予想される結果と異なる場合、 AWS AppSync DynamoDB 関数は設定された戦略に従ってミューテーションを拒否するか、Lambda 関数を呼び出して次に何をするかを決定します。 ### 「reject」の戦略に従う `Reject` 戦略に従うと、 AWS AppSync DynamoDB 関数はミューテーションのエラーを返します。 たとえば、次のミューテーションリクエストが指定されたとします。 ``` mutation { updatePerson(id: 1, name: "Steve", expectedVersion: 1) { Name theVersion } } ``` DynamoDB から返された項目が以下のようになっているとします。 ``` { "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } } ``` この関数レスポンスハンドラーは次のようになります。 ``` import { util } from '@aws-appsync/utils'; export function response(ctx) { const { version, ...values } = ctx.result; const result = { ...values, theVersion: version }; if (ctx.error) { if (error) { return util.appendError(error.message, error.type, result, null); } } return result } ``` GraphQL レスポンスは以下のようになります。 ``` { "data": null, "errors": [ { "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)" "errorType": "DynamoDB:ConditionalCheckFailedException", ... } ] } ``` また、返されたオブジェクトのフィールドすべてが他のリゾルバーによって入力され、そのミューテーションが成功した場合、オブジェクトが `error` セクションに返されたときに、それらのフィールドは解決されません。 ### 「custom」戦略に従う `Custom` 戦略に従うと、 AWS AppSync DynamoDB 関数は Lambda 関数を呼び出して、次に何をするかを決定します。Lambda 関数は以下のオプションのいずれかを選択します。 + ミューテーション を `reject` する これにより、 AWS AppSync DynamoDB 関数は、設定された戦略が であるかのように動作し`Reject`、前のセクションで説明したように、ミューテーションのエラーと DynamoDB 内のオブジェクトの現在の値を返します。 + ミューテーション を `discard` する これにより、 AWS AppSync DynamoDB 関数は条件チェックの失敗を黙って無視し、DynamoDB の値を返します。 + ミューテーション を `retry` する これにより、 AWS AppSync DynamoDB 関数に新しいリクエストオブジェクトでミューテーションを再試行するように指示します。 **Lambda 呼び出しリクエスト** AWS AppSync DynamoDB 関数は、 で指定された Lambda 関数を呼び出します`lambdaArn`。また、データソースに設定されたものと同じ `service-role-arn` を使用します。呼び出しのペイロードは以下の構造を持ちます。 ``` { "arguments": { ... }, "requestMapping": {... }, "currentValue": { ... }, "resolver": { ... }, "identity": { ... } } ``` 各フィールドの定義は以下のようになります。 ** `arguments` ** GraphQL ミューテーションの引数です。これは、`context.arguments` のリクエストオブジェクトで使用できる引数と同じです。 ** `requestMapping` ** このオペレーションのリクエストオブジェクト。 ** `currentValue` ** DynamoDB のオブジェクトの現在値。 ** `resolver` ** AWS AppSync リゾルバーまたは関数に関する情報。 ** `identity` ** 呼び出し元に関する情報。これは、`context.identity` のリクエストオブジェクトで使用できる識別情報と同じです。 完全なペイロードの例を次に示します。 ``` { "arguments": { "id": "1", "name": "Steve", "expectedVersion": 1 }, "requestMapping": { "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : { "S" : "1" } }, "attributeValues" : { "name" : { "S" : "Steve" }, "version" : { "N" : 2 } }, "condition" : { "expression" : "version = :expectedVersion", "expressionValues" : { ":expectedVersion" : { "N" : 1 } }, "equalsIgnore": [ "version" ] } }, "currentValue": { "id" : { "S" : "1" }, "name" : { "S" : "Steve" }, "version" : { "N" : 8 } }, "resolver": { "tableName": "People", "awsRegion": "us-west-2", "parentType": "Mutation", "field": "updatePerson", "outputType": "Person" }, "identity": { "accountId": "123456789012", "sourceIp": "x.x.x.x", "user": "AIDAAAAAAAAAAAAAAAAAA", "userArn": "arn:aws:iam::123456789012:user/appsync" } } ``` **Lambda 呼び出しレスポンス** Lambda 関数は、呼び出しペイロードを検査し、ビジネスロジックを適用して、 AWS AppSync DynamoDB 関数が障害を処理する方法を決定できます。条件チェックで検出されたエラーを処理するために、以下の 3 つのオプションが指定できます。 + ミューテーション を `reject` する このオプションのレスポンスペイロードは次の構造を持ちます。 ``` { "action": "reject" } ``` これにより、 AWS AppSync DynamoDB 関数は、設定された戦略が であるかのように動作し`Reject`、上記のセクションで説明したように、ミューテーションのエラーと DynamoDB 内のオブジェクトの現在の値を返します。 + ミューテーション を `discard` する このオプションのレスポンスペイロードは次の構造を持ちます。 ``` { "action": "discard" } ``` これにより、 AWS AppSync DynamoDB 関数は条件チェックの失敗を黙って無視し、DynamoDB の値を返します。 + ミューテーション を `retry` する このオプションのレスポンスペイロードは次の構造を持ちます。 ``` { "action": "retry", "retryMapping": { ... } } ``` これにより、 AWS AppSync DynamoDB 関数に新しいリクエストオブジェクトでミューテーションを再試行するように指示します。`retryMapping` セクションの構造は DynamoDB の処理によって異なり、その処理の完全なリクエストオブジェクトのサブセットとなります。 `PutItem` の場合、`retryMapping` セクションは次の構造を持ちます。`attributeValues` フィールドについては、「[PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-putitem)」を参照してください。 ``` { "attributeValues": { ... }, "condition": { "equalsIgnore" = [ ... ], "consistentRead" = true } } ``` `UpdateItem` の場合、`retryMapping` セクションは次の構造を持ちます。`update` セクションについては、「[UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem)」を参照してください。 ``` { "update" : { "expression" : "someExpression" "expressionNames" : { "#foo" : "foo" }, "expressionValues" : { ":bar" : ... typed value } }, "condition": { "consistentRead" = true } } ``` `DeleteItem` の場合、`retryMapping` セクションは次の構造を持ちます。 ``` { "condition": { "consistentRead" = true } } ``` 使用する別の処理やキーを指定する方法はありません。 AWS AppSync DynamoDB の関数は、同じオブジェクトに対する同じ処理の再試行のみが可能です。また、`condition` セクションでは `conditionalCheckFailedHandler` は指定できません。再試行が失敗した場合、 AWS AppSync DynamoDB 関数は `Reject`戦略に従います。 以下は、失敗した `PutItem` リクエストを処理する Lambda 関数の例です。ビジネスロジックは呼び出し元を調べます。呼び出し元が `jeffTheAdmin` の場合は、リクエストを再試行して、現在 DynamoDB にある項目の `version` と `expectedVersion` を更新します。それ以外の場合は、ミューテーションを拒否します。 ``` exports.handler = (event, context, callback) => { console.log("Event: "+ JSON.stringify(event)); // Business logic goes here. var response; if ( event.identity.user == "jeffTheAdmin" ) { response = { "action" : "retry", "retryMapping" : { "attributeValues" : event.requestMapping.attributeValues, "condition" : { "expression" : event.requestMapping.condition.expression, "expressionValues" : event.requestMapping.condition.expressionValues } } } response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 } response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version } else { response = { "action" : "reject" } } console.log("Response: "+ JSON.stringify(response)) callback(null, response) }; ``` # トランザクション条件式 トランザクション条件式は、`TransactWriteItems` の 4 つのタイプのオペレーション (`PutItem`、`DeleteItem`、`UpdateItem`、`ConditionCheck`) すべてに対応するリクエストで使用できます。 `PutItem`、`DeleteItem`、および `UpdateItem` の場合、トランザクション条件式はオプションです。`ConditionCheck` の場合、トランザクション条件式が必要です。 ## 例 1 次のトランザクション `DeleteItem` 関数リクエストハンドラーには条件式がありません。その結果、DynamoDB の項目が削除されます。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { postId } = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'DeleteItem', key: util.dynamodb.toMapValues({ postId }), } ], }; } ``` ## 例 2 次のトランザクション `DeleteItem` 関数リクエストハンドラーには、その投稿の作成者が特定の名前に等しい場合にのみオペレーションが成功できるトランザクション条件式があります。 ``` import { util } from '@aws-appsync/utils'; export function request(ctx) { const { postId, authorName} = ctx.args; return { operation: 'TransactWriteItems', transactItems: [ { table: 'posts', operation: 'DeleteItem', key: util.dynamodb.toMapValues({ postId }), condition: util.transform.toDynamoDBConditionExpression({ authorName: { eq: authorName }, }), } ], }; } ``` 条件チェックが失敗すると、`TransactionCanceledException` が発生し、エラーの詳細が `ctx.result.cancellationReasons` で返されます。デフォルトでは、その条件チェックの失敗となった DynamoDB の古い項目は `ctx.result.cancellationReasons` で返されます。 ## 条件を指定する `PutItem`、`UpdateItem`、および `DeleteItem` の各リクエストオブジェクトはすべて、オプションで `condition` セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。`ConditionCheck` では、`condition` セクションを指定する必要があります。トランザクション全体が成功するためには、条件が true でなければなりません。 `condition` セクションは以下の構造を持ちます。 ``` type TransactConditionCheckExpression = { expression: string; expressionNames?: { [key: string]: string }; expressionValues?: { [key: string]: string }; returnValuesOnConditionCheckFailure: boolean; }; ``` 以下のフィールドに条件を指定します。 ** `expression` ** 更新式そのものを指定します。条件式の記述方法の詳細については、[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)を参照してください。このフィールドの指定は必須です。 ** `expressionNames` ** 式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは *expression* で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、*expression* で使用される式の属性名のプレースホルダーのみを入力します。 ** `expressionValues` ** 式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。 ** `returnValuesOnConditionCheckFailure` ** 条件チェックが失敗した場合に、DynamoDB の項目を取得し直すかどうかを指定します。取得された項目は `ctx.result.cancellationReasons[].item` にあります。ここで `` は、条件チェックに失敗したリクエスト項目のインデックスです。この値のデフォルト値は true です。 # 計画 `GetItem`、`Scan`、`Query`、`BatchGetItem` および `TransactGetItems` オペレーションを使用して DynamoDB のオブジェクトを読み取る場合、必要な属性を識別するプロジェクションをオプションで指定できます。projection プロパティの構造は以下のとおりです。これらはフィルタに似ています。 ``` type DynamoDBExpression = { expression: string; expressionNames?: { [key: string]: string} }; ``` 各フィールドの定義は以下のようになります。 ** `expression` ** プロジェクション式、これは文字列です。1 つの属性を取得するには、名前を指定します。複数の属性の場合、名前をカンマで区切る必要があります。プロジェクション式の記述の詳細については、「[DynamoDB プロジェクション式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)」のドキュメントを参照してください。このフィールドは必須です。 ** `expressionNames` ** 式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは、`expression` で使用される名前のプレースホルダーに対応します。値は、DynamoDB の項目の属性名に対応する文字列である必要があります。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。`expressionNames` の詳細については、「[Amazon DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html)」を参照してください。 ## 例 1 次の例は、DynamoDB から属性 `author` と `id` だけが返される JavaScript 関数のプロジェクションセクションです。 ``` projection : { expression : "#author, id", expressionNames : { "#author" : "author" } } ``` **ヒント** [SelectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html#aws-appsync-resolver-context-reference-info-js) を使用して GraphQL リクエストセレクションセットにアクセスできます。このフィールドでは、要件に応じてプロジェクション式を動的にフレーミングできます。 **注記** `Query` と `Scan` のオペレーションでプロジェクション式を使用する場合、`select` の値は `SPECIFIC_ATTRIBUTES` でなければなりません。詳細については、「[DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)」を参照してください。 # OpenSearch のAWS AppSync JavaScript リゾルバー関数リファレンス Amazon OpenSearch Service の AWS AppSync リゾルバーを使用すると、GraphQL を使用して、アカウントの既存の OpenSearch Service ドメインにデータを保存および取得できます。リゾルバーにより、受信した GraphQL リクエストを OpenSearch Service リクエストにマッピングし、その後 OpenSearch Service のレスポンスを GraphQL にマッピングすることができます。このセクションでは、サポートされている OpenSearch Service オペレーションの関数リクエストハンドラーとレスポンスハンドラーについて説明します。 ## リクエスト ほとんどの OpenSearch Service リクエストオブジェクトは構造が共通しており、変更されるのはほんのわずかです。次の例では、OpenSearch Service ドメインに対して検索を実行します。ここでは、ドキュメントは `post` タイプで `id` にインデックスが作成されます。検索パラメータは `body` セクションで定義され、`query` フィールドで定義されている多くの一般的なクエリの句を使用します。この例では `"Nadia"`、または `"Bailey"`、あるいはその両方を、ドキュメントの `author` フィールドに含むドキュメントを検索します。 ``` export function request(ctx) { return { operation: 'GET', path: '/id/post/_search', params: { headers: {}, queryString: {}, body: { from: 0, size: 50, query: { bool: { should: [ { match: { author: 'Nadia' } }, { match: { author: 'Bailey' } }, ], }, }, }, }, }; } ``` ## 応答 他のデータソースと同様に、OpenSearch Service は GraphQL に変換する必要があるレスポンスを AWS AppSync に送信します。 ほとんどの GraphQL クエリは OpenSearch Service レスポンスから `_source` フィールドを探しています。個別のドキュメントまたはドキュメントのリストを返す検索を行うことができるので、OpenSearch Service で使用される、2 つの共通レスポンスマッピングテンプレートがあります。 **結果のリスト** ``` export function response(ctx) { const entries = []; for (const entry of ctx.result.hits.hits) { entries.push(entry['_source']); } return entries; } ``` **個別項目** ``` export function response(ctx) { return ctx.result['_source'] } ``` ## `operation` フィールド **注記** これは、リクエストハンドラーにのみ適用されます。 AWS AppSync が OpenSearch Service ドメインに送信する HTTP メソッドまたは動詞 (GET、POST、PUT、HEAD、DELETE)。キーと値の両方が文字列である必要があります。 ``` "operation" : "PUT" ``` ## `path` フィールド **注記** これは、リクエストハンドラーにのみ適用されます。 AWS AppSync からの OpenSearch Service リクエストの検索パス。これはオペレーションの HTTP 動作に対する URL を作成します。キーと値の両方が文字列である必要があります。 ``` "path" : "/indexname/type" "path" : "/indexname/type/_search" ``` マッピングテンプレートが評価されると、このパスは、OpenSearch Service ドメインが含まれる HTTP リクエストの一部として送信されます。たとえば、前の例では次のように変換される可能性があります。 ``` GET https://opensearch-domain-name.REGION.es.amazonaws.com/indexname/type/_search ``` ## `params` フィールド **注記** これは、リクエストハンドラーにのみ適用されます。 検索実行時のアクションを指定するために使用され、一般に、**query** 値を **body** 内に設定します。ただし、レスポンスのフォーマットなど、他のいくつかの機能を設定できます。 + **ヘッダ** ヘッダー情報は、キーと値のペアです。キーと値の両方が文字列である必要があります。例えば、次のようになります。 ``` "headers" : { "Content-Type" : "application/json" } ``` **注記** AWS AppSync は現在、 として JSON のみをサポートしています`Content-Type`。 + **queryString** 一般的なオプション (JSON レスポンスのコードフォーマットなど) を指定するキーと値のペア。キーと値の両方が文字列である必要があります。たとえば、整形表示の JSON を取得する場合は、次を使用します。 ``` "queryString" : { "pretty" : "true" } ``` + **body** これはリクエストの主要部分であり、 AWS AppSync が OpenSearch Service ドメインに対して適切な形式の検索リクエストを作成できるようにします。キーはオブジェクトで構成される文字列である必要があります。2 つのデモを以下に示します。 **例 1** 都市が「seattle」に一致するすべてのドキュメントを返します。 ``` export function request(ctx) { return { operation: 'GET', path: '/id/post/_search', params: { headers: {}, queryString: {}, body: { from: 0, size: 50, query: { match: { city: 'seattle' } } }, }, }; } ``` **例 2** 都市または州が「washington」に一致するすべてのドキュメントを返します。 ``` export function request(ctx) { return { operation: 'GET', path: '/id/post/_search', params: { headers: {}, queryString: {}, body: { from: 0, size: 50, query: { multi_match: { query: 'washington', fields: ['city', 'state'] }, }, }, }, }; } ``` ## 渡す変数 **注記** これは、リクエストハンドラーにのみ適用されます。 リクエストハンドラーの評価の一部として変数を渡すこともできます。たとえば、次のような GraphQL クエリがあるとします。 ``` query { searchForState(state: "washington"){ ... } } ``` 関数リクエストハンドラーは次のようになります。 ``` export function request(ctx) { return { operation: 'GET', path: '/id/post/_search', params: { headers: {}, queryString: {}, body: { from: 0, size: 50, query: { multi_match: { query: ctx.args.state, fields: ['city', 'state'] }, }, }, }, }; } ``` # Lambda のAWS AppSync JavaScript リゾルバー関数リファレンス AWS AppSync 関数とリゾルバーを使用して、 アカウントにある Lambda 関数を呼び出すことができます。クライアントに返す前に、リクエストペイロードと Lambda 関数からのレスポンスを調整することができます。実行する操作のタイプをリクエストオブジェクトで指定することもできます。このセクションでは、サポートされる Lambda 操作に対するリクエストについて説明します。 ## オブジェクトをリクエストする Lambda リクエストオブジェクトは、Lambda 関数に関連するフィールドを処理します。 ``` export type LambdaRequest = { operation: 'Invoke' | 'BatchInvoke'; invocationType?: 'RequestResponse' | 'Event'; payload: unknown; }; ``` 以下は、ペイロードデータが GraphQL スキーマの `getPost` フィールドであり、コンテキストの引数を含む `invoke` オペレーションを使用する例です。 ``` export function request(ctx) { return { operation: 'Invoke', payload: { field: 'getPost', arguments: ctx.args }, }; } ``` マッピングドキュメント全体は、使用する Lambda 関数に入力として渡されます。これにより、先ほどのサンプルは以下のようになります。 ``` { "operation": "Invoke", "payload": { "field": "getPost", "arguments": { "input": { "id": "postId1", } } } } ``` ### 運用 Lambda データソースでは、`operation` フィールドで 2 つのオペレーションである `Invoke` と `BatchInvoke` を定義できます。`Invoke` オペレーションは、GraphQL フィールドリゾルバーごとに Lambda 関数を呼び出すことを AWS AppSync に知らせます。 `BatchInvoke` は、現在の GraphQL フィールドのリクエストをバッチ処理するように AWS AppSync に指示します。`operation` フィールドは必須です。 `Invoke` では、解決されたリクエストは Lambda 関数の入力ペイロードと一致します。上記の例を変更してみましょう。 ``` export function request(ctx) { return { operation: 'Invoke', payload: { field: 'getPost', arguments: ctx.args }, }; } ``` これは解決され、Lambda 関数に渡されます。この関数は次のようになります。 ``` { "operation": "Invoke", "payload": { "arguments": { "id": "postId1" } } } ``` `BatchInvoke` では、リクエストはバッチ内のすべてのフィールドリゾルバーに適用されます。簡潔にするために、 AWS AppSync はすべてのリクエスト`payload`値を、リクエストオブジェクトに一致する単一のオブジェクトのリストにマージします。以下のリクエストハンドラーの例ではマージを示しています。 ``` export function request(ctx) { return { operation: 'Invoke', payload: ctx, }; } ``` このリクエストは評価され、次のマッピングドキュメントに解決されます。 ``` { "operation": "BatchInvoke", "payload": [ {...}, // context for batch item 1 {...}, // context for batch item 2 {...} // context for batch item 3 ] } ``` `payload` リストの各要素は、1 回のバッチ項目に対応しています。また、Lambda 関数はリスト形式のレスポンスを返すことが予期され、次のように、各項目はリクエストで送信された順序になります。 ``` [ { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1 { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2 { "data": {...}, "errorMessage": null, "errorType": null } // result for batch item 3 ] ``` ### ペイロード `payload` フィールドは、任意のデータを Lambda 関数に渡す際に使用されるコンテナです。`operation` フィールドが `BatchInvoke` に設定されている場合、 AWS AppSync は既存の `payload` 値をリストにまとめます。`payload` フィールドはオプションです。 ### 呼び出しタイプ Lambda データソースでは、2 つの呼び出しタイプ `RequestResponse` と `Event` を定義できます。呼び出しタイプは、[Lambda API](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html) で定義されている呼び出しタイプと同義です。`RequestResponse` 呼び出しタイプ lets AWS AppSync は Lambda 関数を同期的に呼び出してレスポンスを待ちます。`Event` 呼び出しにより、Lambda 関数を非同期的に呼び出すことができます。Lambda が `Event` 呼び出しタイプのリクエストを処理する方法の詳細については、「[非同期呼び出し](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html)」を参照してください。`invocationType` フィールドはオプションです。このフィールドがリクエストに含まれていない場合、 AWS AppSync はデフォルトで`RequestResponse`呼び出しタイプになります。 `invocationType` フィールドでは、解決されたリクエストは Lambda 関数の入力ペイロードと一致します。上記の例を変更してみましょう。 ``` export function request(ctx) { return { operation: 'Invoke', invocationType: 'Event', payload: { field: 'getPost', arguments: ctx.args }, }; } ``` これは解決され、Lambda 関数に渡されます。この関数は次のようになります。 ``` { "operation": "Invoke", "invocationType": "Event", "payload": { "arguments": { "id": "postId1" } } } ``` `BatchInvoke` オペレーションを`Event`呼び出しタイプフィールドと組み合わせて使用すると、 AWS AppSync は上記の同じ方法でフィールドリゾルバーをマージし、リクエストは を値`payload`のリストとする非同期イベントとして Lambda 関数に渡されます。`Event` 呼び出しタイプのリクエストからのレスポンスは、レスポンスハンドラーのない `null` 値になります。 ``` { "data": { "field": null } } ``` `Event` 呼び出しタイプのリゾルバーのリゾルバーキャッシュは、キャッシュヒットがあった場合に Lambda に送信されないため、無効にすることをお勧めします。 ## レスポンスオブジェクト 他のデータソースと同様に、Lambda 関数は GraphQL タイプに変換する必要があるレスポンスを AWS AppSync に送信します。Lambda 関数の結果は、`context` result プロパティに含まれます (`context.result`)。 Lambda 関数のレスポンスの形状と GraphQL タイプの形状が正確に一致する場合は、以下の関数レスポンスハンドラーを使用して、レスポンスを転送できます。 ``` export function response(ctx) { return ctx.result } ``` レスポンスオブジェクトに適用される形状の制限や必須フィールドはありません。ただし、GraphQL が厳密に型指定されているので、解決されたレスポンスは予想される GraphQL タイプに一致する必要があります。 ## Lambda 関数のバッチ処理されたレスポンス `operation` フィールドが に設定されている場合`BatchInvoke`、 AWS AppSync は Lambda 関数から返される項目のリストを想定します。 AWS AppSync が各結果を元のリクエスト項目にマッピングするには、レスポンスリストのサイズと順序が一致している必要があります。レスポンスリストに `null` 項目がある場合も有効です。その場合、`ctx.result` が *null* に設定されます。 # EventBridge データソースのAWS AppSync JavaScript リゾルバー関数リファレンス EventBridge データソースで使用される AWS AppSync リゾルバー関数のリクエストとレスポンスにより、Amazon EventBridge バスにカスタムイベントを送信できます。 ## リクエスト リクエストハンドラーを使用すると、複数のカスタムイベントを EventBridge イベントバスに送信できます。 ``` export function request(ctx) { return { "operation" : "PutEvents", "events" : [{}] } } ``` EventBridge `PutEvents` リクエストには以下のタイプ定義があります。 ``` type PutEventsRequest = { operation: 'PutEvents' events: { source: string detail: { [key: string]: any } detailType: string resources?: string[] time?: string // RFC3339 Timestamp format }[] } ``` ## 応答 `PutEvents` 操作が成功すると、EventBridge からのレスポンスが `ctx.result` に含まれます。 ``` export function response(ctx) { if(ctx.error) util.error(ctx.error.message, ctx.error.type, ctx.result) else return ctx.result } ``` `InternalExceptions` や `Timeouts` などの `PutEvents` 操作の実行中に発生したエラーは、`ctx.error` に表示されます。EventBridge の一般的なエラーのリストについては、[EventBridge の一般的なエラーのリファレンス](https://docs.aws.amazon.com/eventbridge/latest/APIReference/CommonErrors.html)を参照してください。 `result` には以下のタイプ定義があります。 ``` type PutEventsResult = { Entries: { ErrorCode: string ErrorMessage: string EventId: string }[] FailedEntryCount: number } ``` + **エントリ** 取り込まれたイベントは、成功と失敗の両方の結果になります。取り込みが成功すると、エントリには `EventID` が含まれます。それ以外の場合は、`ErrorCode` と `ErrorMessage` を使用してエントリの問題を特定できます。 各レコードの応答要素のインデックスは、リクエスト配列のインデックスと同じです。 + **FailedEntryCount** 失敗したエントリの数。この値は整数として表されます。 `PutEvents` のレスポンスの詳細については、「[PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html#API_PutEvents_ResponseElements)」を参照してください。 **サンプルレスポンスの例: 1** 次の例は、2 つのイベントが成功する `PutEvents` 操作です。 ``` { "Entries" : [ { "EventId": "11710aed-b79e-4468-a20b-bb3c0c3b4860" }, { "EventId": "d804d26a-88db-4b66-9eaf-9a11c708ae82" } ], "FailedEntryCount" : 0 } ``` **サンプルレスポンスの例: 2** 次の例は、3 つのイベント (2 つの成功、1 つの失敗) がある `PutEvents` 操作です。 ``` { "Entries" : [ { "EventId": "11710aed-b79e-4468-a20b-bb3c0c3b4860" }, { "EventId": "d804d26a-88db-4b66-9eaf-9a11c708ae82" }, { "ErrorCode" : "SampleErrorCode", "ErrorMessage" : "Sample Error Message" } ], "FailedEntryCount" : 1 } ``` ## `PutEvents` フィールド `PutEvents` には、次のマッピングテンプレートフィールドが含まれています。 + **バージョン** すべてのリクエストマッピングテンプレートに共通で、`version` フィールドはテンプレートが使用するバージョンを定義します。このフィールドは必須です。値 `2018-05-29` は、EventBridge マッピングテンプレートでサポートされている唯一のバージョンです。 + **操作** サポートされている操作は `PutEvents` のみです。この操作により、カスタムイベントをイベントバスに追加できます。 + **イベント** イベントバスに追加されるイベントの配列。この配列には 1～10 個の項目が割り当てられている必要があります。 `Event` オブジェクトには以下のフィールドがあります。 + `"source"`: イベントのソースを識別する文字列。 + `"detail"`: イベントに関する情報をアタッチするのに使用できる JSON オブジェクト。このフィールドは空のマップ (`{ }`) でもかまいません。 + `"detailType`: イベントの種類を識別する文字列。 + `"resources"`: イベントに関わるリソースを識別する文字列の JSON 配列 このフィールドは、空白の配列でもかまいません。 + `"time"`: 文字列として提供されるイベントのタイムスタンプ。これは [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.txt) タイムスタンプ形式に従う必要があります。 以下のスニペットは有効な `Event` オブジェクトの例です。 **例 1** ``` { "source" : "source1", "detail" : { "key1" : [1,2,3,4], "key2" : "strval" }, "detailType" : "sampleDetailType", "resources" : ["Resouce1", "Resource2"], "time" : "2022-01-10T05:00:10Z" } ``` **例 2** ``` { "source" : "source1", "detail" : {}, "detailType" : "sampleDetailType" } ``` **例 3** ``` { "source" : "source1", "detail" : { "key1" : 1200 }, "detailType" : "sampleDetailType", "resources" : [] } ``` # `None` データソースのAWS AppSync JavaScript リゾルバー関数リファレンス データソースタイプ None の AWS AppSync リゾルバー関数のリクエストとレスポンスを使用すると、 AWS AppSync **ローカルオペレーションのリクエストをシェイプできます。 ## リクエスト リクエストハンドラーはシンプルで、`payload` フィールド経由で可能な限り多くのコンテキスト情報を渡すことができます。 ``` type NONERequest = { payload: any; }; ``` 以下に示しているのは、ペイロードにフィールド引数を渡すようにした例です。 ``` export function request(ctx) { return { payload: context.args }; } ``` `payload` フィールドの値は関数応答ハンドラーに転送され、`context.result` で使用できるようになります。 ## ペイロード `payload` フィールドは任意のデータを渡すためのコンテナで、そのデータを関数レスポンスハンドラーに渡すことができます。 `payload` フィールドはオプションです。 ## 応答 データソースがないため、`payload` フィールドの値が関数レスポンスハンドラーに転送され、`context.result` プロパティに設定されます。 `payload` フィールド値の形状と GraphQL タイプの形状が正確に一致する場合、以下のレスポンスハンドラーを使用して、レスポンスを転送できます。 ``` export function response(ctx) { return ctx.result; } ``` 返されたレスポンスに適用される形状の制限や必須フィールドはありません。ただし、GraphQL が厳密に型指定されているので、解決されたレスポンスは予想される GraphQL タイプに一致する必要があります。 # HTTP のAWS AppSync JavaScript リゾルバー関数リファレンス AWS AppSync HTTP リゾルバー関数を使用すると、 AWS AppSync から任意の HTTP エンドポイントにリクエストを送信し、HTTP エンドポイントから AWS AppSync にレスポンスを返すことができます。リクエストハンドラーを使用して、呼び出されるオペレーションの特性に関して、 AWS AppSync にヒントを渡すこともできます。このセクションでは、サポートされる HTTP リゾルバーの異なる設定について説明します。 ## リクエスト ``` type HTTPRequest = { method: 'PUT' | 'POST' | 'GET' | 'DELETE' | 'PATCH'; params?: { query?: { [key: string]: any }; headers?: { [key: string]: string }; body?: any; }; resourcePath: string; }; ``` 以下のスニペットは、`text/plain` 本文のある HTTP POST リクエストの例です。 ``` export function request(ctx) { return { method: 'POST', params: { headers: { 'Content-Type': 'text/plain' }, body: 'this is an example of text body', }, resourcePath: '/', }; } ``` ## [メソッド] **注記** これは、リクエストハンドラーにのみ適用されます。 AWS AppSync が HTTP エンドポイントに送信する HTTP メソッドまたは動詞 (GET、POST、PUT、PATCH、DELETE)。 ``` "method": "PUT" ``` ## ResourcePath **注記** これは、リクエストハンドラーにのみ適用されます。 アクセス対象のリソースパスです。リソースパスは、HTTP データソースのエンドポイントとともに、 AWS AppSync サービスがリクエストを行う URL を形成します。 ``` "resourcePath": "/v1/users" ``` リクエストが評価されると、このパスは、HTTP エンドポイントが含まれる HTTP リクエストの一部として送信されます。たとえば、前の例では次のように変換される可能性があります。 ``` PUT /v1/users ``` ## Params フィールド **注記** これは、リクエストハンドラーにのみ適用されます。 検索実行時のアクションを指定するために使用され、一般に、**query** 値を **body** 内に設定します。ただし、レスポンスのフォーマットなど、他のいくつかの機能を設定できます。 ** **ヘッダ** ** ヘッダー情報は、キーと値のペアです。キーと値の両方が文字列である必要があります。 例: ``` "headers" : { "Content-Type" : "application/json" } ``` 現在サポートされている `Content-Type` ヘッダーは以下のとおりです。 ``` text/* application/xml application/json application/soap+xml application/x-amz-json-1.0 application/x-amz-json-1.1 application/vnd.api+json application/x-ndjson ``` 以下の HTTP ヘッダーを設定することはできません。 ``` HOST CONNECTION USER-AGENT EXPECTATION TRANSFER_ENCODING CONTENT_LENGTH ``` ** query**** ** 一般的なオプション (JSON レスポンスのコードフォーマットなど) を指定するキーと値のペア。キーと値の両方が文字列である必要があります。次の例では、`?type=json` としてクエリ文字列を送信する方法を示しています。 ``` "query" : { "type" : "json" } ``` ** **body** ** ボディには、設定の際に選択する HTTP リクエストボディが含まれています。リクエストボディは、コンテンツタイプが charset に指定されている場合を除き、常に UTF-8 でエンコードされた文字列です。 ``` "body":"body string" ``` ## 応答 例を参照してください。[こちらへ](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-http-resolvers-js.html)。 # Amazon RDS のAWS AppSync JavaScript リゾルバー関数リファレンス AWS AppSync RDS 関数とリゾルバーを使用すると、デベロッパーは RDS Data API を使用して Amazon Aurora クラスターデータベースにSQLクエリを送信し、これらのクエリの結果を取得できます。 AWS AppSyncの`rds`モジュール`sql`タグ付きテンプレートを使用するか、`rds`モジュールの `select`、`insert`、、および `remove`ヘルパー関数を使用して`update`、Data API に送信されるSQLステートメントを記述できます。 は、RDS Data Service の [https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_ExecuteStatement.html)アクション AWS AppSync を利用して、データベースに対して SQL ステートメントを実行します。 **トピック** + [SQL タグ付きテンプレート](#sql-tagged-templates) + [ステートメントの作成](#creating-statements) + [データの取得](#retrieving-data) + [ユーティリティ関数](#utility-functions) + [SQL SELECT](#utility-functions-select) + [SQL INSERT](#utility-functions-insert) + [SQL UPDATE](#utility-functions-update) + [SQL DELETE](#utility-functions-delete) + [キャスティング](#casting) ## SQL タグ付きテンプレート AWS AppSyncの`sql`タグ付けされたテンプレートを使用すると、テンプレート式を使用して実行時に動的値を受信できる静的ステートメントを作成できます。 は式値から変数マップ AWS AppSync を構築して、Amazon Aurora Serverless Data API に送信される[https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html)クエリを構築します。この方法では、実行時に渡される動的な値によって元のステートメントを変更することができないため、意図しない実行が発生する可能性があります。動的な値はすべてパラメータとして渡され、元のステートメントを変更することはできず、データベースによって実行されることもありません。これにより、クエリが SQL インジェクション攻撃を受けにくくなります。 **注記** いずれの場合も、SQL ステートメントを作成するときは、セキュリティガイドラインに従って、入力として受け取ったデータを適切に処理する必要があります。 **注記** `sql` タグ付きテンプレートは変数値の受け渡しのみをサポートします。式を使用して列名やテーブル名を動的に指定することはできません。ただし、ユーティリティ関数を使用して動的ステートメントを作成することはできます。 次の例では、実行時に GraphQL クエリで動的に設定される `col` 引数の値に基づいてフィルタリングするクエリを作成します。この値は、タグ式を使用してのみステートメントに追加できます。 ``` import { sql, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const query = sql` SELECT * FROM table WHERE column = ${ctx.args.col}` ; return createMySQLStatement(query); } ``` すべての動的な値を変数マップに渡すことで、データベースエンジンに依存して値を安全に処理し、サニタイズします。 ## ステートメントの作成 関数とリゾルバーは、MySQL データベースと PostgreSQL データベースとやり取りできます。`createMySQLStatement` と `createPgStatement` をそれぞれ使用してステートメントを作成します。例えば、`createMySQLStatement` は MySQL クエリを作成できます。これらの関数は最大 2 つのステートメントを受け付けるので、リクエストですぐに結果を取得する必要がある場合に便利です。MySQL では、以下のことが可能です。 ``` import { sql, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { id, text } = ctx.args; const s1 = sql`insert into Post(id, text) values(${id}, ${text})`; const s2 = sql`select * from Post where id = ${id}`; return createMySQLStatement(s1, s2); } ``` **注記** `createPgStatement` および `createMySQLStatement` は、`sql` タグ付きテンプレートで作成されたステートメントをエスケープしたり、引用したりすることはありません。 ## データの取得 実行された SQL ステートメントの結果は、`context.result` オブジェクトのレスポンスハンドラで参照できます。結果は、`ExecuteStatement` アクションからの[レスポンス要素](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_ExecuteStatement.html#API_ExecuteStatement_ResponseElements)を含む JSON 文字列です。解析された結果は次のとおりです。 ``` type SQLStatementResults = { sqlStatementResults: { records: any[]; columnMetadata: any[]; numberOfRecordsUpdated: number; generatedFields?: any[] }[] } ``` `toJsonObject` ユーティリティを使用して、返された行を表す JSON オブジェクトのリストに結果を変換できます。例えば、次のようになります。 ``` import { toJsonObject } from '@aws-appsync/utils/rds'; export function response(ctx) { const { error, result } = ctx; if (error) { return util.appendError( error.message, error.type, result ) } return toJsonObject(result)[1][0] } ``` `toJsonObject` はステートメントの結果の配列を返すことに注意してください。1 つのステートメントを指定した場合、配列の長さは `1` です。2 つのステートメントを指定した場合、配列の長さは `2` です。配列内の各結果には、`0` 以上の行が含まれます。結果の値が無効な場合や予期しないものである場合、`toJsonObject` は `null` を返します。 ## ユーティリティ関数 AWS AppSync RDS モジュールのユーティリティヘルパーを使用して、データベースとやり取りできます。 ### SQL SELECT `select` ユーティリティは、リレーショナルデータベースにクエリを実行する `SELECT` ステートメントを作成します。 **基本的な使用法** 基本的な形式では、クエリを実行するテーブルを指定できます。 ``` import { select, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { // Generates statement: // "SELECT * FROM "persons" return createPgStatement(select({table: 'persons'})); } ``` なお、テーブル識別子でスキーマを指定することもできます。 ``` import { select, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { // Generates statement: // SELECT * FROM "private"."persons" return createPgStatement(select({table: 'private.persons'})); } ``` **列の指定** `columns` プロパティで列を指定できます。これを値に設定しない場合、デフォルトでは `*` になります。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" return createPgStatement(select({ table: 'persons', columns: ['id', 'name'] })); } ``` また、列のテーブルも指定できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "persons"."name" // FROM "persons" return createPgStatement(select({ table: 'persons', columns: ['id', 'persons.name'] })); } ``` **LIMIT と OFFSET** `limit` と `offset` をクエリに適用できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // LIMIT :limit // OFFSET :offset return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], limit: 10, offset: 40 })); } ``` **ORDER BY** 結果は `orderBy` プロパティを使用してソートできます。列とオプションの `dir` プロパティを指定するオブジェクトの配列を指定します。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" FROM "persons" // ORDER BY "name", "id" DESC return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], orderBy: [{column: 'name'}, {column: 'id', dir: 'DESC'}] })); } ``` **フィルター** 特殊条件オブジェクトを使用してフィルターを構築できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: {name: {eq: 'Stephane'}} })); } ``` 以下のフィルターを組み合わせることもできます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME and "id" > :ID return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: {name: {eq: 'Stephane'}, id: {gt: 10}} })); } ``` また、`OR` ステートメントも作成できます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE "name" = :NAME OR "id" > :ID return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: { or: [ { name: { eq: 'Stephane'} }, { id: { gt: 10 } } ]} })); } ``` `not` を使用して条件を無効にすることもできます。 ``` export function request(ctx) { // Generates statement: // SELECT "id", "name" // FROM "persons" // WHERE NOT ("name" = :NAME AND "id" > :ID) return createPgStatement(select({ table: 'persons', columns: ['id', 'name'], where: { not: [ { name: { eq: 'Stephane'} }, { id: { gt: 10 } } ]} })); } ``` 以下の演算子を使用して、値を比較することもできます。 | | | 演算子 | 説明 | 可能な値型 | | --- |--- |--- | | eq | Equal | number, string, boolean | | ne | Not equal | number, string, boolean | | le | Less than or equal | number, string | | lt | Less than | number, string | | ge | Greater than or equal | number, string | | gt | Greater than | number, string | | contains | Like | string | | notContains | Not like | string | | beginsWith | Starts with prefix | string | | between | Between two values | number, string | | attributeExists | The attribute is not null | number, string, boolean | | size | checks the length of the element | string | ### SQL INSERT `insert` ユーティリティによって、`INSERT` オペレーションを使用してデータベースに単一行の項目を簡単に挿入できます。 **単一項目の挿入** 項目を挿入するには、テーブルを指定して、値のオブジェクトを渡します。オブジェクトキーはテーブルの列にマッピングされます。列名は自動的にエスケープされ、値は変数マップを使用してデータベースに送信されます。 ``` import { insert, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values }); // Generates statement: // INSERT INTO `persons`(`name`) // VALUES(:NAME) return createMySQLStatement(insertStatement) } ``` **MySQL ユースケース** `insert` の後に `select` を組み合わせて、挿入した行を取得できます。 ``` import { insert, select, createMySQLStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values }); const selectStatement = select({ table: 'persons', columns: '*', where: { id: { eq: values.id } }, limit: 1, }); // Generates statement: // INSERT INTO `persons`(`name`) // VALUES(:NAME) // and // SELECT * // FROM `persons` // WHERE `id` = :ID return createMySQLStatement(insertStatement, selectStatement) } ``` **Postgres のユースケース** Postgres では、[https://www.postgresql.org/docs/current/dml-returning.html](https://www.postgresql.org/docs/current/dml-returning.html) を使用して、挿入した行からデータを取得できます。`*` または列名の配列が受け入れられます。 ``` import { insert, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: values } = ctx.args; const insertStatement = insert({ table: 'persons', values, returning: '*' }); // Generates statement: // INSERT INTO "persons"("name") // VALUES(:NAME) // RETURNING * return createPgStatement(insertStatement) } ``` ### SQL UPDATE `update` ユーティリティでは、既存の行を更新できます。条件オブジェクトを使用すると、条件を満たすすべての行の指定された列に変更を適用できます。例えば、このミューテーションを可能にするスキーマがあるとします。`Person` の `name` を `3` の `id` 値で更新したいのですが、これは `2000` 年以降にそれら (`known_since`) がわかっている場合に限ります。 ``` mutation Update { updatePerson( input: {id: 3, name: "Jon"}, condition: {known_since: {ge: "2000"}} ) { id name } } ``` 更新リゾルバーは以下のようになります。 ``` import { update, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: { id, ...values }, condition } = ctx.args; const where = { ...condition, id: { eq: id }, }; const updateStatement = update({ table: 'persons', values, where, returning: ['id', 'name'], }); // Generates statement: // UPDATE "persons" // SET "name" = :NAME, "birthday" = :BDAY, "country" = :COUNTRY // WHERE "id" = :ID // RETURNING "id", "name" return createPgStatement(updateStatement) } ``` 条件にチェックを追加して、`3` と等しいプライマリキー `id` を持つ行だけが更新されるようにすることができます。同様に、Postgres `inserts` の場合も、`returning` を使用して変更されたデータを返すことができます。 ### SQL DELETE `remove` ユーティリティでは、既存の行を削除できます。条件オブジェクトは、条件を満たすすべての行で使用できます。なお、`delete` はJavaScriptの予約キーワードです。代わりに `remove` を使ってください。 ``` import { remove, createPgStatement } from '@aws-appsync/utils/rds'; export function request(ctx) { const { input: { id }, condition } = ctx.args; const where = { ...condition, id: { eq: id } }; const deleteStatement = remove({ table: 'persons', where, returning: ['id', 'name'], }); // Generates statement: // DELETE "persons" // WHERE "id" = :ID // RETURNING "id", "name" return createPgStatement(updateStatement) } ``` ## キャスティング ステートメントで使用する正しいオブジェクト型に関して、さらに特異度が必要となる場合もあるでしょう。指定された型ヒントを使用してパラメータのタイプを指定できます。 は Data API [と同じ型ヒント](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html#rdsdtataservice-Type-SqlParameter-typeHint) AWS AppSync をサポートします。モジュールの `typeHint`関数を使用してパラメータを AWS AppSync `rds`キャストできます。 次の例では、JSON オブジェクトとしてキャストされた値として配列を送信できます。`->` 演算子を使用して JSON 配列内にある `index` `2` の要素を取得します。 ``` import { sql, createPgStatement, toJsonObject, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const arr = ctx.args.list_of_ids const statement = sql`select ${typeHint.JSON(arr)}->2 as value` return createPgStatement(statement) } export function response(ctx) { return toJsonObject(ctx.result)[0][0].value } ``` キャスティングは、`DATE`、`TIME`、`TIMESTAMP` の処理や比較を行うときにも役立ちます。 ``` import { select, createPgStatement, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const when = ctx.args.when const statement = select({ table: 'persons', where: { createdAt : { gt: typeHint.DATETIME(when) } } }) return createPgStatement(statement) } ``` 現在の日付と時刻を送信する方法について別の例を以下に示します。 ``` import { sql, createPgStatement, typeHint } from '@aws-appsync/utils/rds'; export function request(ctx) { const now = util.time.nowFormatted('YYYY-MM-dd HH:mm:ss') return createPgStatement(sql`select ${typeHint.TIMESTAMP(now)}`) } ``` **使用可能な型ヒント** + `typeHint.DATE` - 対応するパラメータが、`DATE` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `YYYY-MM-DD` です。 + `typeHint.DECIMAL` - 対応するパラメータが、`DECIMAL` 型のオブジェクトとしてデータベースに送信されます。 + `typeHint.JSON` - 対応するパラメータが、`JSON` 型のオブジェクトとしてデータベースに送信されます。 + `typeHint.TIME` - 対応する文字列パラメータ値が、`TIME` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `HH:MM:SS[.FFF]` です。 + `typeHint.TIMESTAMP` - 対応する文字列パラメータ値が、`TIMESTAMP` 型のオブジェクトとしてデータベースに送信されます。受け入れられる形式は `YYYY-MM-DD HH:MM:SS[.FFF]` です。 + `typeHint.UUID` - 対応する文字列パラメータ値が、`UUID` 型のオブジェクトとしてデータベースに送信されます。 # Amazon Bedrock ランタイムのAWS AppSync JavaScript リゾルバーと関数リファレンス AWS AppSync 関数とリゾルバーを使用して、 の Amazon Bedrock でモデルを呼び出すことができます AWS アカウント。自分のリクエストペイロードと、モデル呼び出し関数からのレスポンスは、クライアントに返す前に調整することができます。Amazon Bedrock ランタイムの `InvokeModel` API または `Converse` API を使用できます。このセクションでは、サポートされる Amazon Bedrock オペレーションのリクエストについて説明します。 **注記** AWS AppSync は、10 秒以内に完了する同期呼び出しのみをサポートします。Amazon Bedrock のストリーム APIs を呼び出すことはできません。 は AWS AppSync 、API と同じリージョンでの基盤モデルと[推論プロファイル](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles.html)の呼び出し AWS AppSync のみをサポートしています。 ## オブジェクトをリクエストする `InvokeModel` リクエストオブジェクトを使用して、Amazon Bedrock の `InvokeModel` API を操作できます。 ``` type BedrockInvokeModelRequest = { operation: 'InvokeModel'; modelId: string; body: any; guardrailIdentifier?: string; guardrailVersion?: string; guardrailTrace?: string; } ``` `Converse` リクエストオブジェクトを使用して、Amazon Bedrock の `Converse` API を操作できます。 ``` type BedrockConverseRequest = { operation: 'Converse'; modelId: string; messages: BedrockMessage[]; additionalModelRequestFields?: any; additionalModelResponseFieldPaths?: string[]; guardrailConfig?: BedrockGuardrailConfig; inferenceConfig?: BedrockInferenceConfig; promptVariables?: { [key: string]: BedrockPromptVariableValues }[]; system?: BedrockSystemContent[]; toolConfig?: BedrockToolConfig; } ``` 詳細については、このトピックで後述する「[タイプリファレンス](#type-reference-bedrock)」のセクション参照してください。 関数やリゾルバーからリクエストオブジェクトを直接構築することも、@aws-appsync/utils/ai のヘルパー関数を使用してリクエストを作成することもできます。リクエストでモデル ID (modelId) を指定する際、モデル ID またはモデル ARN を使用できます。 次の例では、`invokeModel` 関数を使用して、Amazon Titan Text G1 - Lite (amazon.titan-text-lite-v1) を使用してテキストを要約します。設定されたガードレールは、プロンプトフロー内の不要なコンテンツを識別してブロックまたはフィルタリングするために使用されます。[Amazon Bedrock ガードレール](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)の詳細については、「*Amazon Bedrock ユーザーガイド*」を参照してください。 **重要** セキュアなアプリケーションを開発し、プロンプトインジェクションなどの脆弱性を防ぐ責任はお客様にあります。詳細については、「*Amazon Bedrock ユーザーガイド*」の「[プロンプトインジェクションのセキュリティ](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-injection.html)」を参照してください。 ``` import { invokeModel } from '@aws-appsync/utils/ai' export function request(ctx) { return invokeModel({ modelId: 'amazon.titan-text-lite-v1', guardrailIdentifier: "zabcd12345678", guardrailVersion: "1", body: { inputText: `Summarize this text in less than 100 words. : \n${ctx.stash.text ?? ctx.env.DEFAULT_TEXT}` }, }) } export function response(ctx) { return ctx.result.results[0].outputText } ``` 次の例では、クロスリージョン推論プロファイル (us.anthropic.claude-3-5-haiku-20241022-v1:0) を利用する `converse` 関数を使用します。Amazon Bedrock の[推論プロファイルの前提条件](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-prereq.html)の詳細については、「*Amazon Bedrock ユーザーガイド*」を参照してください。 **メモ**: セキュアなアプリケーションを開発し、プロンプトインジェクションなどの脆弱性を防ぐ責任はお客様にあります。 ``` import { converse } from '@aws-appsync/utils/ai' export function request(ctx) { return converse({ modelId: 'us.anthropic.claude-3-5-haiku-20241022-v1:0', system: [ { text: ` You are a database assistant that provides SQL queries to retrieve data based on a natural language request. ${ctx.args.explain ? 'Explain your answer' : 'Do not explain your answer'}. Assume a database with the following tables and columns exists: Customers: - customer_id (INT, PRIMARY KEY) - first_name (VARCHAR) - last_name (VARCHAR) - email (VARCHAR) - phone (VARCHAR) - address (VARCHAR) - city (VARCHAR) - state (VARCHAR) - zip_code (VARCHAR) Products: - product_id (INT, PRIMARY KEY) - product_name (VARCHAR) - description (TEXT) - category (VARCHAR) - price (DECIMAL) - stock_quantity (INT) Orders: - order_id (INT, PRIMARY KEY) - customer_id (INT, FOREIGN KEY REFERENCES Customers) - order_date (DATE) - total_amount (DECIMAL) - status (VARCHAR) Order_Items: - order_item_id (INT, PRIMARY KEY) - order_id (INT, FOREIGN KEY REFERENCES Orders) - product_id (INT, FOREIGN KEY REFERENCES Products) - quantity (INT) - price (DECIMAL) Reviews: - review_id (INT, PRIMARY KEY) - product_id (INT, FOREIGN KEY REFERENCES Products) - customer_id (INT, FOREIGN KEY REFERENCES Customers) - rating (INT) - comment (TEXT) - review_date (DATE)`, }, ], messages: [ { role: 'user', content: [{ text: `${ctx.args.text}:` }], }, ], }) } export function response(ctx) { return ctx.result.output.message.content[0].text } ``` 次の例では、`converse` を使用して構造化レスポンスを作成します。この例では、DB スキーマリファレンスには環境変数を使用し、攻撃を防ぐためにガードレールを設定することに注意してください。 ``` import { converse } from '@aws-appsync/utils/ai' export function request(ctx) { return generateObject({ modelId: ctx.env.HAIKU3_5, // keep the model in an env variable prompt: ctx.args.query, shape: objectType( { sql: stringType('the sql query to execute as a javascript template string.'), parameters: objectType({}, 'the placeholder parameters for the query, if any.'), }, 'the sql query to execute along with the place holder parameters', ), system: [ { text: ` You are a database assistant that provides SQL queries to retrieve data based on a natural language request. Assume a database with the following tables and columns exists: ${ctx.env.DB_SCHEMA_CUSTOMERS} ${ctx.env.DB_SCHEMA_ORDERS} ${ctx.env.DB_SCHEMA_ORDER_ITEMS} ${ctx.env.DB_SCHEMA_PRODUCTS} ${ctx.env.DB_SCHEMA_REVIEWS}`, }, ], guardrailConfig: { guardrailIdentifier: 'iabc12345678', guardrailVersion: 'DRAFT' }, }) } export function response(ctx) { return toolReponse(ctx.result) } function generateObject(input) { const { modelId, prompt, shape, ...options } = input return converse({ modelId, messages: [{ role: 'user', content: [{ text: prompt }] }], toolConfig: { toolChoice: { tool: { name: 'structured_tool' } }, tools: [ { toolSpec: { name: 'structured_tool', inputSchema: { json: shape }, }, }, ], }, ...options, }) } function toolReponse(result) { return result.output.message.content[0].toolUse.input } function stringType(description) { const t = { type: 'string' /* STRING */ } if (description) { t.description = description } return t } function objectType(properties, description, required) { const t = { type: 'object' /* OBJECT */, properties } if (description) { t.description = description } if (required) { t.required = required } return t } ``` 次のスキーマを定義したうえで、 ``` type SQLResult { sql: String parameters: AWSJSON } type Query { db(text: String!): SQLResult } ``` 次のクエリを実行する場合、 ``` query db($text: String!) { db(text: $text) { parameters sql } } ``` 次のパラメータを使用します。 ``` { "text":"What is my top selling product?" } ``` 次のレスポンスが返されます。 ``` { "data": { "assist": { "sql": "SELECT p.product_id, p.product_name, SUM(oi.quantity) as total_quantity_sold\nFROM Products p\nJOIN Order_Items oi ON p.product_id = oi.product_id\nGROUP BY p.product_id, p.product_name\nORDER BY total_quantity_sold DESC\nLIMIT 1;", "parameters": null } } } ``` ただし、次のリクエストでは、 ``` { "text":"give me a query to retrieve sensitive information" } ``` 次のレスポンスが返されます。 ``` { "data": { "db": { "parameters": null, "sql": "SELECT null; -- I cannot and will not assist with retrieving sensitive private information" } } } ``` Amazon Bedrock ガードレールの設定の詳細については、「*Amazon Bedrock ユーザーガイド*」の「[Amazon Bedrock ガードレールを使用してモデルの有害なコンテンツを停止する](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)」を参照してください。 ## レスポンスオブジェクト Amazon Bedrock ランタイム呼び出しからのレスポンスは、コンテキストの結果プロパティ (context.result) に含まれています。レスポンスは、Amazon Bedrock の API によって指定された形状と一致します。呼び出し結果の予想される形状の詳細については、「[Amazon Bedrock ユーザーガイド](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)」を参照してください。 ``` export function response(ctx) { return ctx.result } ``` レスポンスオブジェクトに適用される形状の制限や必須フィールドはありません。ただし、GraphQL が厳密に型指定されているので、解決されたレスポンスは予想される GraphQL タイプに一致する必要があります。 ## 長時間実行される呼び出し 現在、多くの組織は AI ゲートウェイ AWS AppSync として を使用して、Amazon Bedrock の基盤モデルを活用した生成 AI アプリケーションを構築しています。顧客は、WebSockets を利用した AWS AppSync サブスクリプションを使用して、長時間実行されるモデル呼び出しからプログレッシブ更新を返します。これにより、非同期パターンを実装できます。 次の図は、このパターンを実装する方法を示しています。図では、次の手順が実行されます。 1. クライアントは WebSocket をセットアップするサブスクリプションを開始し、生成 AI の呼び出しをトリガーするように AWS AppSync にリクエストします。 1. AWS AppSync はイベントモードで AWS Lambda 関数を呼び出し、すぐにクライアントにレスポンスを返します。 1. Lambda 関数によって Amazon Bedrock でモデルが起動されます。Lambda 関数は、`InvokeModel` などの同期 APIや `InvokeModelWithResponseStream` などのストリーム API を使用して、プログレッシブ更新を取得できます。 1. 更新を受信するか、呼び出しが完了すると、Lambda 関数は API にミューテーションを介して更新を送信 AWS AppSync し、サブスクリプションをトリガーします。 1. サブスクリプションイベントはリアルタイムで送信され、WebSocket 経由でクライアントによって受信されます。 ![\[AWS AppSync サブスクリプションを使用して Amazon Bedrock モデルから更新を返すワークフローを示す図。\]](http://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/images/bedrock-workflow.png) ## タイプリファレンス ``` export type BedrockMessage = { role: 'user' | 'assistant' | string; content: BedrockMessageContent[]; }; export type BedrockMessageContent = | { text: string } | { guardContent: BedrockGuardContent } | { toolResult: BedrockToolResult } | { toolUse: BedrockToolUse }; export type BedrockGuardContent = { text: BedrockGuardContentText; }; export type BedrockGuardContentText = { text: string; qualifiers?: ('grounding_source' | 'query' | 'guard_content' | string)[]; }; export type BedrockToolResult = { content: BedrockToolResultContent[]; toolUseId: string; status?: string; }; export type BedrockToolResultContent = { json: any } | { text: string }; export type BedrockToolUse = { input: any; name: string; toolUseId: string; }; export type ConversePayload = { modelId: string; body: any; guardrailIdentifier?: string; guardrailVersion?: string; guardrailTrace?: string; }; export type BedrockGuardrailConfig = { guardrailIdentifier: string; guardrailVersion: string; trace: string; }; export type BedrockInferenceConfig = { maxTokens?: number; temperature?: number; stopSequences?: string[]; topP?: number; }; export type BedrockPromptVariableValues = { text: string; }; export type BedrockToolConfig = { tools: BedrockTool[]; toolChoice?: BedrockToolChoice; }; export type BedrockTool = { toolSpec: BedrockToolSpec; }; export type BedrockToolSpec = { name: string; description?: string; inputSchema: BedrockInputSchema; }; export type BedrockInputSchema = { json: any; }; export type BedrockToolChoice = | { tool: BedrockSpecificToolChoice } | { auto: any } | { any: any }; export type BedrockSpecificToolChoice = { name: string; }; export type BedrockSystemContent = | { guardContent: BedrockGuardContent } | { text: string }; export type BedrockConverseOutput = { message?: BedrockMessage; }; export type BedrockConverseMetrics = { latencyMs: number; }; export type BedrockTokenUsage = { inputTokens: number; outputTokens: number; totalTokens: number; }; export type BedrockConverseTrace = { guardrail?: BedrockGuardrailTraceAsssessment; }; export type BedrockGuardrailTraceAsssessment = { inputAssessment?: { [key: string]: BedrockGuardrailAssessment }; modelOutput?: string[]; outputAssessments?: { [key: string]: BedrockGuardrailAssessment }; }; export type BedrockGuardrailAssessment = { contentPolicy?: BedrockGuardrailContentPolicyAssessment; contextualGroundingPolicy?: BedrockGuardrailContextualGroundingPolicyAssessment; invocationMetrics?: BedrockGuardrailInvocationMetrics; sensitiveInformationPolicy?: BedrockGuardrailSensitiveInformationPolicyAssessment; topicPolicy?: BedrockGuardrailTopicPolicyAssessment; wordPolicy?: BedrockGuardrailWordPolicyAssessment; }; export type BedrockGuardrailContentPolicyAssessment = { filters: BedrockGuardrailContentFilter[]; }; export type BedrockGuardrailContentFilter = { action: 'BLOCKED' | string; confidence: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | string; type: | 'INSULTS' | 'HATE' | 'SEXUAL' | 'VIOLENCE' | 'MISCONDUCT' | 'PROMPT_ATTACK' | string; filterStrength: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | string; }; export type BedrockGuardrailContextualGroundingPolicyAssessment = { filters: BedrockGuardrailContextualGroundingFilter; }; export type BedrockGuardrailContextualGroundingFilter = { action: 'BLOCKED' | 'NONE' | string; score: number; threshold: number; type: 'GROUNDING' | 'RELEVANCE' | string; }; export type BedrockGuardrailInvocationMetrics = { guardrailCoverage?: BedrockGuardrailCoverage; guardrailProcessingLatency?: number; usage?: BedrockGuardrailUsage; }; export type BedrockGuardrailCoverage = { textCharacters?: BedrockGuardrailTextCharactersCoverage; }; export type BedrockGuardrailTextCharactersCoverage = { guarded?: number; total?: number; }; export type BedrockGuardrailUsage = { contentPolicyUnits: number; contextualGroundingPolicyUnits: number; sensitiveInformationPolicyFreeUnits: number; sensitiveInformationPolicyUnits: number; topicPolicyUnits: number; wordPolicyUnits: number; }; export type BedrockGuardrailSensitiveInformationPolicyAssessment = { piiEntities: BedrockGuardrailPiiEntityFilter[]; regexes: BedrockGuardrailRegexFilter[]; }; export type BedrockGuardrailPiiEntityFilter = { action: 'BLOCKED' | 'ANONYMIZED' | string; match: string; type: | 'ADDRESS' | 'AGE' | 'AWS_ACCESS_KEY' | 'AWS_SECRET_KEY' | 'CA_HEALTH_NUMBER' | 'CA_SOCIAL_INSURANCE_NUMBER' | 'CREDIT_DEBIT_CARD_CVV' | 'CREDIT_DEBIT_CARD_EXPIRY' | 'CREDIT_DEBIT_CARD_NUMBER' | 'DRIVER_ID' | 'EMAIL' | 'INTERNATIONAL_BANK_ACCOUNT_NUMBER' | 'IP_ADDRESS' | 'LICENSE_PLATE' | 'MAC_ADDRESS' | 'NAME' | 'PASSWORD' | 'PHONE' | 'PIN' | 'SWIFT_CODE' | 'UK_NATIONAL_HEALTH_SERVICE_NUMBER' | 'UK_NATIONAL_INSURANCE_NUMBER' | 'UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER' | 'URL' | 'USERNAME' | 'US_BANK_ACCOUNT_NUMBER' | 'US_BANK_ROUTING_NUMBER' | 'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER' | 'US_PASSPORT_NUMBER' | 'US_SOCIAL_SECURITY_NUMBER' | 'VEHICLE_IDENTIFICATION_NUMBER' | string; }; export type BedrockGuardrailRegexFilter = { action: 'BLOCKED' | 'ANONYMIZED' | string; match?: string; name?: string; regex?: string; }; export type BedrockGuardrailTopicPolicyAssessment = { topics: BedrockGuardrailTopic[]; }; export type BedrockGuardrailTopic = { action: 'BLOCKED' | string; name: string; type: 'DENY' | string; }; export type BedrockGuardrailWordPolicyAssessment = { customWords: BedrockGuardrailCustomWord[]; managedWordLists: BedrockGuardrailManagedWord[]; }; export type BedrockGuardrailCustomWord = { action: 'BLOCKED' | string; match: string; }; export type BedrockGuardrailManagedWord = { action: 'BLOCKED' | string; match: string; type: 'PROFANITY' | string; }; ```