解析程序映射模板概述

AmazonAppSync 允许您通过对资源执行操作来响应 GraphQL 请求。对于要对其运行查询或变异的每个 GraphQL 字段，必须附加解析程序以便与数据源进行通信。通常，通常是通过对数据源唯一的参数或操作来实现的。

解析器是 GraphQL 和数据源之间的连接器。他们告诉AmazonAppSync 如何将传入的 GraphQL 请求转换为针对后端数据源的指令，以及如何将来自该数据源的响应转换回 GraphQL 响应。它们以 Apache Velocity 模板语言 (VTL) 编写，将您的请求作为输入，并输出包含解析程序指令的 JSON 文档。您可以对简单的指令使用映射模板（例如，传入 GraphQL 字段中的参数），也可以对更复杂的指令使用映射模板（例如，循环访问各个参数以构建项目，然后将该项目插入到 DynamoDB）。

AppSync 中有两种类型的解析程序，它们通过略微不同的方式使用映射模板：单元解析程序和管道解析程序。

单元解析程序

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

请求模板：在解析 GraphQL 操作后获取传入请求，并将其转换为选定数据源操作的请求配置。
响应模板：解释来自数据源的响应并映射到 GraphQL 字段输出类型的形状。

管道解析程序

管道解析器包含一个或多个功能它们按先后顺序执行。每个函数都包括一个请求模板和响应模板。管道解析器还有以前一个模板和之后围绕模板包含的函数序列的模板。这些区域有：之后映射到 GraphQL 字段输出类型。流水线解析器与单位解析器的不同之处在于响应模板映射输出的方式。管道解析器可以映射到你想要的任何输出，包括另一个函数的输入或之后管道解析程序的模板。

管道解析程序功能利用，您可以编写可以跨您的架构中的多个解析程序重用的常见逻辑。函数直接附加到数据源，就像单元解析程序一样，函数包含相同的请求和响应映射模板格式。

下图显示了左侧的单元解析器和右侧的管道解析器的流程流程。

管道解析程序包含单元解析程序支持的功能的超集，以及更多的功能，但代价是更复杂一些。

示例模板

例如，假设您有一个 DynamoDB 数据源和单位在名为的字段上的解析器getPost(id:ID!)返回Post使用以下 GraphQL 查询键入：


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

AmazonAppSync 使用此模板生成用来与 DynamoDB 进行通信和获取数据（或执行其他操作，视情况而定）的指令。数据返回之后，AmazonAppSync 通过可选的可用于执行数据形状塑造或逻辑的响应映射模板以运行数据。例如，当我们从 DynamoDB 获得返回的结果时，结果可能如下所示：


{
        "id" : 1,
        "theTitle" : "Amazon 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" : "Amazon AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

此数据作为响应返回给客户端，如下所示：


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

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


$util.toJson($context.result)

对于列表，通常传递的是：


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

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

已评估映射模板反序列化规则

映射模板计算结果为字符串。InAmazonAppSync，输出字符串必须遵循 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

解析程序映射模板参考

解析程序映射模板编程指南