リクエストマッピングテンプレートレスポンスマッピングテンプレート Lambda 関数のバッチ処理されたレスポンスダイレクトLambda リゾルバー

Lambda のリゾルバーのマッピングテンプレートリファレンス

注記

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

AWS Lambda 用 AWS AppSync のリゾルバーマッピングテンプレートを使用すると、AWS AppSync から、アカウントに配置された Lambda 関数へのリクエストと、Lambda 関数から AWS AppSync に返すレスポンスを作成できます。マッピングテンプレートを使用して、呼び出されるオペレーションの特性に関して、AWS AppSync にヒントを渡すこともできます。このセクションでは、サポートされる Lambda 操作用の異なるマッピングテンプレートについて説明します。

リクエストマッピングテンプレート

Lambda リクエストマッピングテンプレートは非常に簡単で、できるだけ多くのコンテキスト情報を Lambda 関数に渡すことができます。


{
   "version": string,
   "operation": Invoke|BatchInvoke,
   "payload": any type
}

以下に示しているのは、解決時の Lambda リクエストマッピングテンプレートの JSON スキーマ表現です。


{
    "definitions": {},
    "$schema": "https://json-schema.org/draft-06/schema#",
    "$id": "https://aws.amazon.com/appsync/request-mapping-template.json",
    "type": "object",
    "properties": {
        "version": {
            "$id": "/properties/version",
            "type": "string",
            "enum": [
                "2018-05-29"
            ],
            "title": "The Mapping template version.",
            "default": "2018-05-29"
        },
        "operation": {
            "$id": "/properties/operation",
            "type": "string",
            "enum": [
                "Invoke",
                "BatchInvoke"
            ],
            "title": "The Mapping template operation.",
            "description": "What operation to execute.",
            "default": "Invoke"
        },
        "payload": {}
    },
    "required": [
        "version",
        "operation"
    ],
    "additionalProperties": false
}

以下に示しているのは、コンテキストから GraphQL フィールド引数と field 値を渡すように選択した例です。


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $util.toJson($context.arguments)
    }
}

マッピングドキュメント全体は、使用する Lambda 関数に入力として渡されます。これにより、前の例では以下のようになります。


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": {
            "id": "postId1"
        }
    }
}

バージョン

すべてのリクエストマッピングテンプレートに共通で、version はテンプレートが使用するバージョンを定義します。version が必要です。


"version": "2018-05-29"

操作

Lambda データソースでは、2 つの操作である Invoke と BatchInvoke を定義できます。Invoke では、すべての GraphQL フィールドリゾルバーに対して Lambda 関数を呼び出すことを AWS AppSync に通知し、一方 BatchInvoke では、現在の GraphQL フィールドに対するリクエストをバッチ実行するように AWS AppSync に指示します。

operation は必須です。

Invoke では、解決されたリクエストマッピングテンプレートは Lambda 関数の入力 payload と完全に一致します。したがって、次のサンプルテンプレートは、


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "arguments": $util.toJson($context.arguments)
    }
}

解決され、次の内容が Lambda 関数に渡されます。


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "arguments": {
            "id": "postId1"
        }
    }
}

BatchInvoke では、バッチ内のすべてのフィールドリゾルバーにマッピングテンプレートが適用されます。簡潔さのために、AWS AppSync は解決されたすべてのマッピングテンプレートの payload 値を、マッピングテンプレートに一致する単一オブジェクトの下でリストにマージします。

次のサンプルテンプレートは、マージを示します。


{
    "version": "2018-05-29",
    "operation": "BatchInvoke",
    "payload": $util.toJson($context)
}

このテンプレートは、次のマッピングドキュメントに解決されます。


{
    "version": "2018-05-29",
    "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
]

operation は必須です。

Payload

payload フィールドは、任意の正しい形式の JSON を Lambda 関数に渡す際に使用するコンテナです。

operation フィールドが BatchInvoke に設定されている場合、AWS AppSync は既存の payload 値をリストにまとめます。

payload は省略可能です。

レスポンスマッピングテンプレート

他のデータソースと同様に、Lambda 関数はレスポンスを、AWS AppSync に送信します。これは GraphQL タイプに変換する必要があります。

Lambda 関数の結果は、Velocity Template Language (VTL) $context.result プロパティを通じて使用できる context オブジェクトで設定されます。

Lambda 関数のレスポンスの形状と GraphQL タイプの形状が正確に一致する場合は、以下のレスポンスマッピングテンプレートを使用して、レスポンスを転送できます。


$util.toJson($context.result)

レスポンスマッピングテンプレートに適用される形状の制限や必須フィールドはありません。ただし、GraphQL が厳密に型指定されているので、解決されたマッピングテンプレートは予想される GraphQL タイプに一致する必要があります。

Lambda 関数のバッチ処理されたレスポンス

operation フィールドが BatchInvoke に設定されている場合、AWS AppSync は Lambda 関数からの項目のリストを想定します。AWS AppSync で、それぞれの結果を元のリクエスト項目にマッピングするためには、レスポンスリストでサイズと順番が一致する必要があります。レスポンスリストに null 項目があっても構いません。その場合、$ctx.result が null に設定されます。

ダイレクトLambda リゾルバー

マッピングテンプレートの使用を完全に回避したい場合は、AWS AppSync は、Lambda 関数にデフォルトのペイロードを提供し、GraphQL タイプに対する Lambda 関数のデフォルトの応答を提供できます。リクエストテンプレート、レスポンステンプレート、またはどちらを指定しないかを選択できます。AWS AppSync はどちらを選択したかに応じて処理します。

ダイレクト Lambda リクエストマッピングテンプレート

リクエストマッピングテンプレートが提供されていない場合、AWS AppSync は、Context オブジェクトをオペレーションとして Lambda 関数に直接送信します。Context オブジェクトの構造の詳細については、「リゾルバーのマッピングテンプレートのコンテキストリファレンス」を参照してください。

ダイレクト Lambda レスポンスマッピングテンプレート

レスポンスマッピングテンプレートが提供されていない場合、AWS AppSync は、Lambda 関数のレスポンスの受信時に 2 つのうちいずれかを実行します。リクエストマッピングテンプレートを指定しなかった場合、またはバージョン「2018-05-29」でリクエストマッピングテンプレートを提供した場合、応答ロジックは次のレスポンスマッピングテンプレートと同じように機能します。


#if($ctx.error)
     $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
 #end
 $util.toJson($ctx.result)

バージョン「2017-02-28」のテンプレートを提供した場合、レスポンス・ロジックは次のレスポンス・マッピングテンプレートと同様に機能します。


$util.toJson($ctx.result)

表面的には、マッピングテンプレートのバイパスは、前の例に示すように、特定のマッピングテンプレートを使用する場合と同様に機能します。ただし、裏では、マッピングテンプレートの評価は完全に回避されます。テンプレート評価ステップはバイパスされるため、一部のシナリオでは、評価が必要なレスポンスマッピングテンプレートを持つ Lambda 関数と比較して、アプリケーションのレスポンスのオーバーヘッドとレイテンシーが少なくなる場合があります。

ダイレクト Lambda リゾルバーレスポンスのカスタムエラー処理

カスタム例外を発生させることにより、ダイレクト Lambda リゾルバーによって呼び出される Lambda 関数からのエラーレスポンスをカスタマイズできます。次の例では、JavaScript を使用してカスタム例外を作成する方法を示します。


class CustomException extends Error {
    constructor(message) {
        super(message);
        this.name = "CustomException";
    }
}
 
throw new CustomException("Custom message");

例外が発生すると、errorType と errorMessage が、それぞれ個別に、スローされるカスタムエラーの name と message になります。

errorType が UnauthorizedException の場合は、AWS AppSync は、カスタムメッセージの代わりにデフォルトのメッセージ ("You are not authorized to make this call.") を返します。

以下は、カスタム errorType を示す GraphQL レスポンスの例です。


{
  "data": {
    "query": null
  },
  "errors": [
    {
      "path": [
        "query"
      ],
      "data": null,
      "errorType": "CustomException",
      "errorInfo": null,
      "locations": [
        {
          "line": 5,
          "column": 10,
          "sourceName": null
        }
      ],
      "message": "Custom Message"
    }
  ]
}

ダイレクト Lambda リゾルバー: バッチ処理が有効

Direct Lambda リゾルバーのバッチ処理を有効にするには、リゾルバーで maxBatchSize を設定します。maxBatchSize をダイレクト Lambda リゾルバーで 0 より大きい値に設定すると、AWS AppSync は Lambda関数に最大サイズ maxBatchSize のリクエストをバッチで送信します。

ダイレクト Lambda リゾルバーで maxBatchSize を 0 に設定すると、バッチ処理がオフになります。

Lambda リゾルバーによるバッチ処理の仕組みの詳細については、「高度なユースケース: バッチ処理」を参照してください。

リクエストマッピングテンプレート

バッチ処理が有効で、リクエストマッピングテンプレートが提供されていない場合、AWS AppSync は、Context オブジェクトのリストを BatchInvoke 操作として Lambda 関数に直接送信します。

レスポンスマッピングテンプレート

バッチ処理が有効で、レスポンスマッピングテンプレートが提供されていない場合、レスポンスロジックは次のレスポンスマッピングテンプレートと同様に機能します。


#if( $context.result && $context.result.errorMessage )
      $utils.error($context.result.errorMessage, $context.result.errorType,
      $context.result.data)
#else
      $utils.toJson($context.result.data)
#end

Lambda 関数は、送信された Context オブジェクトのリストと同じ順序で結果のリストを返す必要があります。特定の結果に対して errorMessage と errorTypeを指定することで、個々のエラーを返すことができます。リストの各結果には、次の形式があります。


{
   "data" : { ... }, // your data
   "errorMessage" : { ... }, // optional, if included an error entry is added to the "errors" object in the AppSync response 
   "errorType" : { ... } // optional, the error type
}

注記

結果オブジェクトの他のフィールドは現時点では無視されます。

Lambda からのエラーの処理

Lambda 関数に例外またはエラーを投げると、すべての結果に対してエラーを返すことができます。バッチリクエストの payload リクエストまたはレスポンスサイズが大きすぎる場合、Lambda はエラーを返します。その場合は、maxBatchSize を小さくするか、レスポンス payload のサイズを小さくすることを検討してください。

個別のエラー処理については、「個々のエラーを返す」を参照してください。

サンプル Lambda 関数

以下のスキーマを使用して、Post.relatedPosts フィールドリゾルバー用のダイレクト Lambda リゾルバーを作成し、maxBatchSize を0 より大きい値に設定することでバッチ処理を有効にできます。


schema {
    query: Query
    mutation: Mutation
}

type Query {
    getPost(id:ID!): Post
    allPosts: [Post]
}

type Mutation {
    addPost(id: ID!, author: String!, title: String, content: String, url: String): Post!
}

type Post {
    id: ID!
    author: String!
    title: String
    content: String
    url: String
    ups: Int
    downs: Int
    relatedPosts: [Post]
}

次のクエリでは、relatedPosts を解決するリクエストのバッチとともに Lambda 関数が呼び出されます。


query getAllPosts {
  allPosts {
    id
    relatedPosts {
      id
    }
  }
}

Lambda 関数の簡単な実装を以下に示します。


const posts = {
  1: {
    id: '1',
    title: 'First book',
    author: 'Author1',
    url: 'https://amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1',
    ups: '100',
    downs: '10',
  },
  2: {
    id: '2',
    title: 'Second book',
    author: 'Author2',
    url: 'https://amazon.com',
    content: 'SAMPLE TEXT AUTHOR 2 SAMPLE TEXT AUTHOR 2 SAMPLE TEXT',
    ups: '100',
    downs: '10',
  },
  3: { id: '3', title: 'Third book', author: 'Author3', url: null, content: null, ups: null, downs: null },
  4: {
    id: '4',
    title: 'Fourth book',
    author: 'Author4',
    url: 'https://www.amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4',
    ups: '1000',
    downs: '0',
  },
  5: {
    id: '5',
    title: 'Fifth book',
    author: 'Author5',
    url: 'https://www.amazon.com/',
    content: 'SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT',
    ups: '50',
    downs: '0',
  },
}

const relatedPosts = {
  1: [posts['4']],
  2: [posts['3'], posts['5']],
  3: [posts['2'], posts['1']],
  4: [posts['2'], posts['1']],
  5: [],
}
exports.handler = async (event) => {
  console.log('event ->', event)
  // retrieve the ID of each post
  const ids = event.map((context) => context.source.id)
  // fetch the related posts for each post id
  const related = ids.map((id) => relatedPosts[id])

  // return the related posts; or an error if none were found
  return related.map((r) => {
    if (r.length > 0) {
      return { data: r }
    } else {
      return { data: null, errorMessage: 'Not found', errorType: 'ERROR' }
    }
  })
}

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

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

ドキュメントの表記規則

OpenSearch のリゾルバーのマッピングテンプレートリファレンス

EventBridge のリゾルバーのマッピングテンプレートリファレンス