ユニットリゾルバーパイプラインリゾルバーサンプルテンプレート評価されたマッピングテンプレートの逆シリアル化ルール

AWS AppSync リゾルバーマッピングテンプレートの概要

注記

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

AWS AppSync では、リソースに対してオペレーションを実行して、GraphQL リクエストに応答できます。クエリやミューテーションなど、実行する GraphQL フィールドごとに、データソースとやり取りするためにリゾルバーをアタッチする必要があります。通常、この通信はパラメータを介して行うか、データソースに固有の処理を使用します。

リゾルバーは GraphQL とデータソースの間のコネクタです。 AWS AppSync 受信した GraphQL リクエストをバックエンドデータソースの手順に変換する方法と、そのデータソースからのレスポンスを GraphQL レスポンスに変換する方法を説明します。これらは Apache Velocity テンプレート言語 (VTL）で記述されます。この言語はリクエストを入力として受け取り、リゾルバーの指示を含むJSONドキュメントを出力します。GraphQL フィールドから引数を渡すなどの簡単な指示や、引数の指定により、項目をビルドしてから DynamoDB への挿入を繰り返すといったより複雑な指示をマッピングテンプレートを使用して行えます。

マッピングテンプレートを少し異なる方法で活用 AWS AppSync するリゾルバーには 2 つのタイプがあります。

ユニットリゾルバー
パイプラインリゾルバー

ユニットリゾルバー

ユニットリゾルバーは、リクエストおよびレスポンステンプレートのみを含む自己完結型エンティティです。1 つのデータソースから項目を一覧表示するなどのシンプルな 1 つのオペレーションに、この種類のリゾルバーを使用します。

リクエストテンプレート: GraphQL オペレーションが解析された後に受信リクエストを受け取り、選択されたデータソースオペレーション用のリクエスト設定に変換します。
レスポンステンプレート: データソースからのレスポンスを解釈し、GraphQL フィールド出力タイプの形式にマッピングします。

パイプラインリゾルバー

パイプラインリゾルバーには、順番に実行される 1 つ以上の関数が含まれています。各関数には、リクエストテンプレートとレスポンステンプレートが含まれています。パイプラインのリゾルバーには、一連の関数を囲むテンプレートである before テンプレートとafter テンプレートも含まれています。After テンプレートは GraphQL フィールド出力タイプにマッピングします。パイプラインのリゾルバーは、レスポンステンプレートの出力をマッピングする点でユニットリゾルバーとは異なります。パイプラインリゾルバーは、別の関数の入力や、パイプラインリゾルバーのafterテンプレートを含むどんな出力でもマッピングできます。

パイプラインリゾルバー機能では、スキーマ内の複数のリゾルバーにまたがって再利用できる共通のロジックを作成できます。関数はデータソースに直接アタッチされており、ユニットリゾルバーのものと同じリクエストおよびレスポンスマッピングテンプレート形式を含んでいます。

次の図は、左側がユニットリゾルバー、右側がパイプラインリゾルバーのプロセスフローを示しています。

単一のデータソースと通信するユニットリゾルバーの図と、複数のデータソースと通信するパイプラインのリゾルバーの図。

パイプラインリゾルバーには、少々複雑になるものの、ユニットリゾルバーが提供する機能の上位集合が含まれています。

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

パイプラインリゾルバーは、Before マッピングテンプレート、After マッピングテンプレート、関数のリストで構成されています。各関数には、データソースに対して実行されるリクエストおよびレスポンスマッピングテンプレートがあります。パイプラインリゾルバーは実行をリスト内の関数に委任するため、いずれのデータソースにもリンクされていません。ユニットリゾルバーと関数は、データソースに対してオペレーションを実行するプリミティブです。詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。

Before マッピングテンプレート

パイプラインリゾルバーのリクエストマッピングテンプレート (Before ステップとも呼ばれる) では、定義した関数を実行する前に準備ロジックを実行できます。

関数のリスト

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

After マッピングテンプレート

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

実行フロー

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

GraphQL request flow diagram showing template processing and data source interactions.

パイプラインリゾルバーの Before マッピングテンプレート
関数 1: 関数のリクエストマッピングテンプレート
関数 1: データソースの呼び出し
関数 1: 関数のレスポンスマッピングテンプレート
関数 2: 関数のリクエストマッピングテンプレート
関数 2: データソースの呼び出し
関数 2: 関数のレスポンスマッピングテンプレート
パイプラインリゾルバーの After マッピングテンプレート

注記

パイプラインリゾルバーの実行フローは単方向であり、リゾルバーで静的に定義されています。

便利な Apache Velocity Template Language (VTL) ユーティリティ

アプリケーションの複雑さが増すにつれて、開発の生産性を向上させるためにVTLユーティリティとディレクティブがここにあります。パイプラインリゾルバーでの作業には、以下のユーティリティが役立ちます。

$ctx.stash

stash は、リゾルバーと関数の各マッピングテンプレート内で使用可能になる Map です。同じ stash インスタンスは 1 つのリゾルバーの実行を通して存続します。つまり、stash を使用して、リクエストとレスポンスのマッピングテンプレート間、およびパイプラインリゾルバーの関数間で、任意のデータを渡すことができます。stash は Java Map データ構造と同じメソッドを継承しています。

$ctx.prev.result

$ctx.prev.result は、パイプラインリゾルバーで実行された前のオペレーションの結果を表します。

前のオペレーションがパイプラインリゾルバーの Before マッピングテンプレートであった場合、$ctx.prev.result はテンプレートの評価の出力を表し、パイプライン内の最初の関数に使用可能になります。前のオペレーションが最初の関数であった場合、$ctx.prev.result は最初の関数の出力を表し、パイプライン内の 2 番目の関数に使用可能になります。前のオペレーションが最後の関数であった場合、$ctx.prev.result は最後の関数の出力を表し、パイプラインリゾルバーの After マッピングテンプレートに使用可能になります。

#return(data: Object)

マッピングテンプレートから途中で戻る必要がある場合は、#return(data: Object) ディレクティブが便利です。#return(data: Object) は、プログラミング言語の return キーワードと似ています。これは、最も近いスコープのロジックブロックから戻るためです。つまり、リゾルバーのマッピングテンプレート内で #return を使用すると、リゾルバーから戻ることになります。リゾルバーのマッピングテンプレートで #return(data: Object) を使用すると、GraphQL フィールドに data が設定されます。さらに、関数のマッピングテンプレートから #return(data: Object) を使用すると、実行が関数から戻り、パイプライン内の次の関数に、またはリゾルバーのレスポンスマッピングテンプレートに継続されます。

#return

これは #return(data: Object) と同じですが、代わりに null が返されます。

$util.error

$util.error ユーティリティはフィールドエラーをスローするのに便利です。関数のマッピングテンプレート内で $util.error を使用すると、フィールドエラーがすぐにスローされ、それ以降の関数が実行されなくなります。詳細およびその他の $util.error 署名については、「リゾルバーのマッピングテンプレートのユーティリティリファレンス」を参照してください。

$util。appendError

注意: $util.appendError は $util.error() と似ていますが、マッピングテンプレートの評価を中断しないという違いがあります。代わりに、フィールドにエラーがあったことを通知します。ただし、テンプレートを評価し、データを引き続き返すことも可能です。関数内で $util.appendError を使用しても、パイプラインの実行フローは中断されません。詳細およびその他の $util.error 署名については、「リゾルバーのマッピングテンプレートのユーティリティリファレンス」を参照してください。

サンプルテンプレート

DynamoDB データソースがあり、また次の GraphQL クエリにより Post 型を返す getPost(id:ID!) というフィールドの ユニット リゾルバーがあるとします。


getPost(id:1){
    id
    title
    content
}

リゾルバーのテンプレートは以下のようになります。


     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

これにより、 idの入力パラメータ値が 1 に置き換え${ctx.args.id}られ、次のが生成されますJSON。


     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : { "S" : "1" }
    }
}

AWS AppSync はこのテンプレートを使用して、DynamoDB と通信し、データを取得する (または必要に応じて他のオペレーションを実行する) 手順を生成します。データが返されると、 AWS AppSync はオプションのレスポンスマッピングテンプレートを使用してデータシェーピングまたはロジックを実行できます。たとえば、DynamoDB から次のような結果を取得します。


{
        "id" : 1,
        "theTitle" : "AWS AppSync works offline!",
        "theContent-part1" : "It also has realtime functionality",
        "theContent-part2" : "using GraphQL"
}

次のようなレスポンスマッピングテンプレートを使用して、2 つのフィールドを 1 つのフィールドに結合することもできます。


{
        "id" : $util.toJson($context.data.id),
        "title" : $util.toJson($context.data.theTitle),
        "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}")
}

テンプレートがデータに適用されると、データは次のように成形されます。


{
        "id" : 1,
        "title" : "AWS AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

このデータは以下のように、クライアントへのレスポンスとして返されます。


{
        "data": {
                "getPost":      {
                        "id" : 1,
                        "title" : "AWS AppSync works offline!",
                        "content" : "It also has realtime functionality using GraphQL"
                }
        }
}

ほとんどの場合、レスポンスマッピングテンプレートはデータを単純に転送します。個々の項目や項目のリストを返す場合は、大きく異なります。個々の項目について、パススルーは次のようになります。


$util.toJson($context.result)

リストについて、パススルーは通常次のようになります。


$util.toJson($context.result.items)

ユニットリゾルバーとパイプラインリゾルバーの両方のさらに多くの例については、リゾルバーのチュートリアルを参照してください。

評価されたマッピングテンプレートの逆シリアル化ルール

マッピングテンプレートは文字列として評価されます。では AWS AppSync、出力文字列は有効なJSON構造に従う必要があります。

さらに、以下の逆シリアル化ルールが適用されます。

JSON オブジェクトでは重複キーは許可されません

評価されたマッピングテンプレート文字列がJSONオブジェクトを表すか、キーが重複しているオブジェクトを含む場合、マッピングテンプレートは次のエラーメッセージを返します。

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

評価されたリクエストマッピングテンプレートの重複キーの例:


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
        "field": "getPost" ## key 'field' has been redefined
    }
}

このエラーを修正するには、JSONオブジェクト内のキーを再定義しないでください。

JSON オブジェクトでは末尾文字は使用できません

評価されたマッピングテンプレート文字列がJSONオブジェクトを表し、後続の外部文字が含まれている場合、マッピングテンプレートは次のエラーメッセージを返します。

Trailing characters at the end of the JSON string are not allowed.

評価されたリクエストマッピングテンプレートの末尾の文字の例:


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
    }
}extraneouschars

このエラーを修正するには、評価されたテンプレートがに厳密に評価されていることを確認しますJSON。

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

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

ドキュメントの表記規則

リゾルバーマッピングテンプレートリファレンス (VTL）

リゾルバーのマッピングテンプレートプログラミングガイド