Lambda 解析程序映射模板参考 - Amazon AppSync
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Lambda 解析程序映射模板参考

这些区域有:AmazonAppSync Lambda 解析器映射模板使您能够调整来自的请求AmazonAppSync 到Amazon Lambda以及 Lambda 函数返回到的响应位于您账户中的函数以及AmazonAppSync。通过映射模板,还可以向提供提示AmazonAppSync 介绍要调用的操作的性质。本节介绍用于支持的 Amazon 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 }

在下面的示例中,我们选择从上下文传递 field 值和 GraphQL 字段参数。

{ "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 是必需的。

"version": "2018-05-29"

Operation

Lambda 数据源让您可以定义两个操作:InvokeBatchInvoke。这些区域有:Invoke让Amazon而 AppSync 知道针对每个 GraphQL 字段解析程序调用 Lambda 函数,而BatchInvoke指示AmazonAppSync 用于批量对当前 GraphQL 字段的请求。

operation 是必需的。

对于 Invoke,已解析的请求映射模板与 Lambda 函数的输入负载完全匹配。因此,下面的示例模板:

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

经过解析并传递给 Lambda 函数,如下所示:

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

对于 BatchInvoke,将对批处理中的每个字段解析程序应用映射模板。为了简洁起见,AmazonAppSync 合并所有已解析的映射模板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 列表的每个元素对应于一个批处理项目。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、AmazonAppSync 将包装现有的payload值转入列表中。

payload 为可选项。

响应映射模板

对于其他数据源,Lambda 函数将响应发送到Amazon需要转换为 GraphQL 类型的 AppSync。

Lambda 函数的结果将在通过 VTL context 属性提供的 $context.result 对象上设置。

如果 Lambda 函数响应的形状与 GraphQL 类型的形状完全匹配,您可以使用以下响应映射模板转发响应:

$util.toJson($context.result)

没有必填字段,也没有形状限制应用于响应映射模板。但是,由于 GraphQL 是强类型化的,因此解析的映射模板必须与预期的 GraphQL 类型匹配。

Lambda 函数批处理响应

如果operation字段设置为BatchInvoke、AmazonAppSync 预计从 Lambda 函数返回项目列表。为了AmazonAppSync 要将每个结果映射回原始请求项目,响应列表在大小和顺序方面必须匹配。响应列表可以有 null 项目;$ctx.result 将相应地设置为 null

直接 Lambda 解析程序

如果你想完全规避使用映射模板,AmazonAppSync 可以为您的 Lambda 函数提供默认负载以及 Lambda 函数对 GraphQL 类型的默认响应。您可以选择提供请求模板、响应模板,也可以选择两者都不提供以及AmazonAppSync 会相应地处理它。

直接 Lambda 请求映射模板

如果未提供请求映射模板,AmazonAppSync 会将上下文对象作为Invokeoperation. 有关 Context 对象结构的更多信息,请参阅上下文.

直接 Lambda 响应映射模板

如果没有提供响应映射模板,Amazon在收到 Lambda 函数响应后,AppSync 将执行以下两件事之一。如果您没有提供请求映射模板,或者如果您提供了版本为 “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 解析器响应中的自定义错误处理

您可以通过引发自定义异常来自 Direct Lambda 解析器调用的 Lambda 函数自定义错误响应。以下示例演示如何使用 JavaScript 创建自定义异常。

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

当出现例外情况时,errorTypeerrorMessage将是namemessage,分别是引发的自定义错误的信息。

如果errorTypeUnauthorizedException、AmazonAppSync 返回默认消息("You are not authorized to make this call.") 而不是自定义消息。

以下是 GraphQL 响应示例,演示了自定义:errorType.

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