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

解析程序映射模板概述

利用 AWS AppSync,您可以通过对资源执行操作来响应 GraphQL 请求。对于要执行的每个 GraphQL 字段(如“查询”或“更改”),必须附加解析程序以便与数据源进行通信。通常,通信是通过对数据源唯一的参数或操作来实现的。

映射模板是一种指示方法,可向 AWS AppSync 指示如何将传入的 GraphQL 请求转换为针对后端数据源的指令,以及如何将来自该数据源的响应转换回 GraphQL 响应。它们以 Apache Velocity 模板语言 (VTL) 编写,将您的请求作为输入,并输出包含解析程序指令的 JSON 文档。您可以对简单的指令使用映射模板(例如,传入 GraphQL 字段中的参数),也可以对更复杂的指令使用映射模板(例如,循环访问各个参数以构建项目,然后将该项目插入到 DynamoDB)。AppSync 中有两种类型的解析程序,它们通过略微不同的方式使用映射模板:单元解析程序和管道解析程序。

单元解析程序

单元解析器是自包含的实体,仅包含请求和响应模板。将它们用于简单、单一的操作(例如,列出来自单个数据源的项目)。

  • 请求模板:在解析 GraphQL 操作后获取传入请求,并将其转换为选定数据源操作的请求配置。

  • 响应模板:解释来自数据源的响应并映射到 GraphQL 字段输出类型的形状。

管道解析程序

管道解析程序包含一个或多个按顺序执行的函数。每个函数都包含一个请求和一个响应模板,并以类似的方式运行,但与单元解析程序不完全相同。不同之处在于,响应模板可以映射到您希望的任何输出,这可能是其他函数的输入或管道解析程序的之后模板。管道解析程序还具有围绕函数执行序列的之前之后模板。之后模板映射到 GraphQL 字段输出类型。管道解析程序包含单元解析程序提供的功能的超集,以及更多的功能,但代价是更复杂一些。

函数允许您编写跨您的架构中的多个解析程序重用的常见逻辑。它们直接附加到数据源,就像单元解析程序一样,包含相同的请求和响应映射模板格式。

下方是单元解析程序(左)和管道解析程序(右)的并排图解。

示例模板

例如,假设您在名为 getPost(id:ID!) 的字段(返回带以下 GraphQL 查询的 Post 类型)上有一个 DynamoDB 数据源和一个单元解析程序:

getPost(id:1){ id title content }

解析程序模板应如下所示:

{ "version" : "2017-02-28", "operation" : "GetItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) } }

这会使用 id 输入参数值 1 替换 ${ctx.args.id} 并生成以下 JSON:

{ "version" : "2017-02-28", "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" }

您可以选择使用以下响应映射模板将两个字段联接成单一字段:

{ "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" } } }

请注意,在大多数情况下,响应映射模板是简单的数据传递,主要由于您返回的是单个项目还是项目列表而不同。对于单个项目,传递:

$utils.toJson($context.result)

对于列表,通常传递的是:

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

要查看单元解析程序和管道解析程序的更多示例,请参阅解析程序教程

已计算的映射模板反序列化规则

映射模板计算结果为字符串。在 AWS AppSync 中,输出字符串必须遵循 JSON 结构才会有效。

此外,将强制执行以下反序列化规则。

JSON 对象中不允许使用重复的键

如果计算得出的映射模板字符串表示 JSON 对象或包含具有重复键的对象,则映射模板会返回以下错误消息:

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

已计算的请求映射模板中的重复键示例:

{ "version": "2017-02-28", "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": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": "1", } }extraneouschars

要修复此错误,请确保已计算的模板严格计算为 JSON。