创建基本查询（VTL）

注意

我们现在主要支持 APPSYNC_JS 运行时系统及其文档。请考虑使用 APPSYNC_JS 运行时系统和此处的指南。

GraphQL 解析器将类型的架构中的字段连接到数据来源。解析器是满足请求的机制。 Amazon AppSync 无需编写任何代码，即可自动创建和连接架构中的解析器，或者创建架构并连接现有表中的解析器。

Amazon AppSync 用于将 GraphQL 表达式 JavaScript 转换为数据源可以使用的格式的解析器。或者，可以使用 Apache Velocity 模板语言 (VTL) 编写映射模板，以将 GraphQL 表达式转换为数据来源可使用的格式。

本节说明了如何使用 VTL 配置解析器。关于编写解析器的入门教程式编程指南可以在解析器映射模板编程指南中找到，编程时可用的帮助工具可以在解析器映射模板上下文参考中找到。 Amazon AppSync 还具有内置的测试和调试流程，您可以在从头开始编辑或创作时使用这些流程。有关更多信息，请参阅测试和调试解析器。

我们建议您在尝试使用任何上述教程之前先遵循本指南。

在本节中，我们将介绍如何创建解析器，为变更添加解析器以及使用高级配置。

创建您的第一个解析器

按照前面几节中的示例，第一步是为 Query 类型创建一个解析器。

Console

登录 Amazon Web Services Management Console 并打开AppSync 控制台。
1. 在APIs 控制面板中，选择你的 GraphQL API。
2. 在侧边栏中，选择架构。
在页面右侧，具有一个名为解析器的窗口。该框包含页面左侧的架构窗口中定义的类型和字段列表。您可以将解析器附加到字段。例如，在 Query 类型下面，选择 getTodos 字段旁边的附加。
在创建解析器页面上，选择您在附加数据来源指南中创建的数据来源。在配置映射模板窗口中，您可以使用右侧的下拉列表选择通用请求和响应映射模板，也可以编写自己的映射模板。

注意
请求映射模板与响应映射模板的配对称为单位解析器。单位解析器通常用于执行机械性的操作；我们建议仅将它们用于具有少量数据来源的单一操作。对于更复杂的操作，我们建议使用管道解析器，该解析器按顺序对多个数据来源执行多个操作。
有关请求映射模板和响应映射模板之间的差异的更多信息，请参阅单位解析器。
有关使用管道解析器的更多信息，请参阅管道解析器。
对于常见用例， Amazon AppSync 控制台内置了模板，您可以使用这些模板从数据源获取项目（例如，所有项目查询、个人查询等）。例如，对于设计您的架构中的简单架构版本（getTodos 没有分页），用于列出项目的请求映射模板如下所示：
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
您始终需要为请求提供响应映射模板。控制台为列表提供的默认模板具有以下传递值：
```
$util.toJson($ctx.result.items)
```
此示例中，项目列表的 context 对象（别名为 $ctx）的格式为 $context.result.items。如果您的 GraphQL 操作返回一个项目，它将是 $context.result。 Amazon AppSync 为常用操作提供帮助程序函数，如之前列出的 $util.toJson 函数，以保证响应格式正确。有关完整的函数列表，请参阅解析器映射模板实用程序参考。
选择保存解析器。

API

调用 CreateResolver API 以创建一个解析器对象。
您可以调用 UpdateResolver API 以修改解析器的字段。

CLI

运行 create-resolver 命令以创建解析器。

您需要为该特定命令键入 6 个参数：

您的 API 的 api-id。
您要在架构中修改的类型的 type-name。在控制台示例中，这是 Query。
您要在类型中修改的字段的 field-name。在控制台示例中，这是 getTodos。
您在附加数据来源指南中创建的数据来源的 data-source-name。
request-mapping-template，这是请求的正文。在控制台示例中，这是：
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
response-mapping-template，这是响应的正文。在控制台示例中，这是：
```
$util.toJson($ctx.result.items)
```

示例命令可能如下所示：


aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"

将在 CLI 中返回输出。示例如下：


{
    "resolver": {
        "kind": "UNIT",
        "dataSourceName": "TodoTable",
        "requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
        "resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
        "typeName": "Query",
        "fieldName": "getTodos",
        "responseMappingTemplate": "$util.toJson($ctx.result.items)"
    }
}

要修改解析器的字段 and/or 映射模板，请运行update-resolver命令。

除了 api-id 参数以外，create-resolver 命令中使用的参数将由 update-resolver 命令中的新值覆盖。

为变更添加解析器

下一步是为您的 Mutation 类型创建一个解析器。

Console

登录 Amazon Web Services Management Console 并打开AppSync 控制台。
1. 在APIs 控制面板中，选择你的 GraphQL API。
2. 在侧边栏中，选择架构。
在 Mutation 类型下面，选择 addTodo 字段旁边的附加。
在创建解析器页面上，选择您在附加数据来源指南中创建的数据来源。

在配置映射模板窗口中，您需要修改请求模板，因为这是一个变更，该操作将新项目添加 DynamoDB 中。使用以下请求映射模板：


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

Amazon AppSync 自动将addTodo字段中定义的参数从 GraphQL 架构转换为 DynamoDB 操作。上一示例使用 id 键将记录存储在 DynamoDB 中，该键是从变更参数中作为 $ctx.args.id 传递的。您传递的所有其他字段使用 $util.dynamodb.toMapValuesJson($ctx.args) 自动映射到 DynamoDB 属性。

对于此解析器，使用以下响应映射模板：
```
$util.toJson($ctx.result)
```
Amazon AppSync 还支持用于编辑解析器的测试和调试工作流程。您可在调用之前使用模拟 context 对象查看模板经过转换的值。还可在运行查询时选择以交互方式查看对数据来源的完整请求执行过程。有关更多信息，请参阅测试和调试解析器和监控和日志记录。
选择保存解析器。

API

您也可以使用 “创建您的第一个解析器” 部分中的命令以及本节中的参数详细信息来执行此操作。 APIs

CLI

您也可以在 CLI 中使用创建您的第一个解析器一节中的命令以及本节中的参数详细信息执行该操作。

此时，如果您不使用高级解析器，您可以开始使用 GraphQL API，如使用 API 中所述。

高级解析器

如果您按照设计您的架构的“高级”一节进行操作，并构建一个示例架构以执行分页扫描，请将以下请求模板用于 getTodos 字段：


{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "limit": $util.defaultIfNull(${ctx.args.limit}, 20),
    "nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}

对于这个分页使用案例，响应映射不只是简单的传递，因为它必须包含光标（这样客户端才知道下次从哪一页开始）以及结果集。映射模板如下所示：


{
    "todos": $util.toJson($context.result.items),
    "nextToken": $util.toJson($context.result.nextToken)
}

以上响应映射模板中的字段必须与 TodoConnection 类型中定义的字段匹配。

如果存在以下关系：您具有 Comments 表并且要解析 Todo 类型（返回 [Comment] 类型）的 Comments 字段，您可以使用映射模板以对第二个表运行查询。为此，您必须已为 Comments 表创建了一个数据来源，如附加数据来源中所述。

注意

我们对第二个表使用查询操作仅用于说明目的。您可以对 DynamoDB 使用其他操作。此外，您可以从其他数据源（例如 Amazon Lambda 或 Amazon S OpenSearch ervice）提取数据，因为该关系由您的 GraphQL 架构控制。

Console

登录 Amazon Web Services Management Console 并打开AppSync 控制台。
1. 在APIs 控制面板中，选择你的 GraphQL API。
2. 在侧边栏中，选择架构。
在 Todo 类型下面，选择 comments 字段旁边的附加。
在创建解析器页面上，选择您的 Comments 表数据来源。快速入门指南中的 Comments 表的默认名称是 AppSyncCommentTable，但它可能会根据您指定的名称而有所不同。

将以下代码片段添加到您的请求映射模板中：


{
    "version": "2017-02-28",
    "operation": "Query",
    "index": "todoid-index",
    "query": {
        "expression": "todoid = :todoid",
        "expressionValues": {
            ":todoid": {
                "S": $util.toJson($context.source.id)
            }
        }
    }
}

context.source 会引用当前被解析的字段的父对象。在本示例中，source.id 指单个 Todo 对象，之后它会被用于查询表达式。

您可以如下所示使用传递响应映射模板：
```
$util.toJson($ctx.result.items)
```
选择保存解析器。
最后，返回到控制台中的架构页面，将一个解析器附加到 addComment 字段，并指定 Comments 表的数据来源。在此例中请求映射模板只是简单的 PutItem，它具有作为参数注释的特定 todoid，但您可以使用 $utils.autoId() 实用程序来为如下所示注释创建唯一的排序键：
```
{
    "version": "2017-02-28",
    "operation": "PutItem",
    "key": {
        "todoid": { "S": $util.toJson($context.arguments.todoid) },
        "commentid": { "S": "$util.autoId()" }
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
如下所示使用传递响应模板：
```
$util.toJson($ctx.result)
```

API

您也可以使用 “创建您的第一个解析器” 部分中的命令以及本节中的参数详细信息来执行此操作。 APIs

CLI

您也可以在 CLI 中使用创建您的第一个解析器一节中的命令以及本节中的参数详细信息执行该操作。

Javascript 在您的浏览器中被禁用或不可用。

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

配置和使用管道解析器 () JavaScript

使用直接 Lambda 解析器（VTL）禁用 VTL 映射模板