本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 创建基本查询（VTL）
**注意**
我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.amazonaws.cn/appsync/latest/devguide/configuring-resolvers-js.html)的指南。
GraphQL 解析器将类型的架构中的字段连接到数据来源。解析器是满足请求的机制。 Amazon AppSync 无需编写任何代码，即可自动创建和连接架构中的解析器，或者创建架构并从现有表连接解析器。
Amazon AppSync 用于将 GraphQL 表达式 JavaScript 转换为数据源可以使用的格式的解析器。或者，可以使用 [Apache Velocity 模板语言 (VTL)](https://velocity.apache.org/engine/2.0/vtl-reference.html) 编写映射模板，以将 GraphQL 表达式转换为数据来源可使用的格式。
本节说明了如何使用 VTL 配置解析器。关于编写解析器的入门教程式编程指南可以在解析器[映射模板编程指南中找到，编程](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide)时可用的帮助工具可以在[解析器](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference)映射模板上下文参考中找到。 Amazon AppSync 还具有内置的测试和调试流程，您可以在从头开始编辑或创作时使用这些流程。有关更多信息，请参阅[测试和调试解析器](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)。
我们建议您在尝试使用任何上述教程之前先遵循本指南。
在本节中，我们将介绍如何创建解析器，为变更添加解析器以及使用高级配置。
## 创建您的第一个解析器
按照前面几节中的示例，第一步是为 `Query` 类型创建一个解析器。
------
#### [ Console ]
1. 登录 Amazon Web Services 管理控制台 并打开[AppSync 控制台](https://console.amazonaws.cn/appsync/)。
1. 在**APIs 控制面板**中，选择你的 GraphQL API。
1. 在**侧边栏**中，选择**架构**。
1. 在页面右侧，具有一个名为**解析器**的窗口。该框包含页面左侧的**架构**窗口中定义的类型和字段列表。您可以将解析器附加到字段。例如，在 **Query** 类型下面，选择 `getTodos` 字段旁边的**附加**。
1. 在**创建解析器**页面上，选择您在[附加数据来源](https://docs.amazonaws.cn/appsync/latest/devguide/attaching-a-data-source.html)指南中创建的数据来源。在**配置映射模板**窗口中，您可以使用右侧的下拉列表选择通用请求和响应映射模板，也可以编写自己的映射模板。
**注意**
请求映射模板与响应映射模板的配对称为单位解析器。单位解析器通常用于执行机械性的操作；我们建议仅将它们用于具有少量数据来源的单一操作。对于更复杂的操作，我们建议使用管道解析器，该解析器按顺序对多个数据来源执行多个操作。
有关请求映射模板和响应映射模板之间的差异的更多信息，请参阅[单位解析器](https://docs.amazonaws.cn//appsync/latest/devguide/resolver-mapping-template-reference-overview.html#unit-resolvers)。
有关使用管道解析器的更多信息，请参阅[管道解析器](pipeline-resolvers.md#aws-appsync-pipeline-resolvers)。
1. 对于常见用例， Amazon AppSync 控制台内置了模板，您可以使用这些模板从数据源获取项目（例如，所有项目查询、个人查询等）。例如，对于[设计您的架构](designing-your-schema.md#aws-appsync-designing-your-schema)中的简单架构版本（`getTodos` 没有分页），用于列出项目的请求映射模板如下所示：
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. 您始终需要为请求提供响应映射模板。控制台为列表提供的默认模板具有以下传递值：
```
$util.toJson($ctx.result.items)
```
此示例中，项目列表的 `context` 对象（别名为 `$ctx`）的格式为 `$context.result.items`。如果您的 GraphQL 操作返回一个项目，它将是 `$context.result`。 Amazon AppSync 为常用操作提供帮助程序函数，如之前列出的 `$util.toJson` 函数，以保证响应格式正确。有关完整的函数列表，请参阅[解析器映射模板实用程序参考](resolver-util-reference.md#aws-appsync-resolver-mapping-template-util-reference)。
1. 选择**保存解析器**。
------
#### [ API ]
1. 调用 [https://docs.amazonaws.cn/appsync/latest/APIReference/API_CreateResolver.html](https://docs.amazonaws.cn/appsync/latest/APIReference/API_CreateResolver.html) API 以创建一个解析器对象。
1. 您可以调用 [https://docs.amazonaws.cn/appsync/latest/APIReference/API_UpdateResolver.html](https://docs.amazonaws.cn/appsync/latest/APIReference/API_UpdateResolver.html) API 以修改解析器的字段。
------
#### [ CLI ]
1. 运行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html) 命令以创建解析器。
您需要为该特定命令键入 6 个参数：
1. 您的 API 的 `api-id`。
1. 您要在架构中修改的类型的 `type-name`。在控制台示例中，这是 `Query`。
1. 您要在类型中修改的字段的 `field-name`。在控制台示例中，这是 `getTodos`。
1. 您在[附加数据来源](https://docs.amazonaws.cn/appsync/latest/devguide/attaching-a-data-source.html)指南中创建的数据来源的 `data-source-name`。
1. `request-mapping-template`，这是请求的正文。在控制台示例中，这是：
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. `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)"
}
}
```
1. 要修改解析器的字段 and/or 映射模板，请运行[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html)命令。
除了 `api-id` 参数以外，`create-resolver` 命令中使用的参数将由 `update-resolver` 命令中的新值覆盖。
------
## 为变更添加解析器
下一步是为您的 `Mutation` 类型创建一个解析器。
------
#### [ Console ]
1. 登录 Amazon Web Services 管理控制台 并打开[AppSync 控制台](https://console.amazonaws.cn/appsync/)。
1. 在**APIs 控制面板**中，选择你的 GraphQL API。
1. 在**侧边栏**中，选择**架构**。
1. 在 **Mutation** 类型下面，选择 `addTodo` 字段旁边的**附加**。
1. 在**创建解析器**页面上，选择您在[附加数据来源](https://docs.amazonaws.cn/appsync/latest/devguide/attaching-a-data-source.html)指南中创建的数据来源。
1. 在**配置映射模板**窗口中，您需要修改请求模板，因为这是一个变更，该操作将新项目添加 DynamoDB 中。使用以下请求映射模板：
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
1. Amazon AppSync 自动将`addTodo`字段中定义的参数从 GraphQL 架构转换为 DynamoDB 操作。上一示例使用 `id` 键将记录存储在 DynamoDB 中，该键是从变更参数中作为 `$ctx.args.id` 传递的。您传递的所有其他字段使用 `$util.dynamodb.toMapValuesJson($ctx.args)` 自动映射到 DynamoDB 属性。
对于此解析器，使用以下响应映射模板：
```
$util.toJson($ctx.result)
```
Amazon AppSync 还支持用于编辑解析器的测试和调试工作流程。您可在调用之前使用模拟 `context` 对象查看模板经过转换的值。还可在运行查询时选择以交互方式查看对数据来源的完整请求执行过程。有关更多信息，请参阅[测试和调试解析器](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)和[监控和日志记录](monitoring.md#aws-appsync-monitoring)。
1. 选择**保存解析器**。
------
#### [ API ]
您也可以使用 “[创建您的第一个解析器](https://docs.amazonaws.cn/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)” 部分中的命令以及本节中的参数详细信息来执行此操作。 APIs
------
#### [ CLI ]
您也可以在 CLI 中使用[创建您的第一个解析器](https://docs.amazonaws.cn/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)一节中的命令以及本节中的参数详细信息执行该操作。
------
此时，如果您不使用高级解析器，您可以开始使用 GraphQL API，如[使用 API](using-your-api.md#aws-appsync-using-your-api) 中所述。
## 高级解析器
如果您按照[设计您的架构](designing-your-schema.md#aws-appsync-designing-your-schema)的“高级”一节进行操作，并构建一个示例架构以执行分页扫描，请将以下请求模板用于 `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` 表创建了一个数据来源，如[附加数据来源](attaching-a-data-source.md#aws-appsync-getting-started-build-a-schema-from-scratch)中所述。
**注意**
我们对第二个表使用查询操作仅用于说明目的。您可以对 DynamoDB 使用其他操作。此外，您可以从其他数据源（例如 Amazon Lambda 或 Amazon S OpenSearch ervice）提取数据，因为该关系由您的 GraphQL 架构控制。
------
#### [ Console ]
1. 登录 Amazon Web Services 管理控制台 并打开[AppSync 控制台](https://console.amazonaws.cn/appsync/)。
1. 在**APIs 控制面板**中，选择你的 GraphQL API。
1. 在**侧边栏**中，选择**架构**。
1. 在 **Todo** 类型下面，选择 `comments` 字段旁边的**附加**。
1. 在**创建解析器**页面上，选择您的 **Comments** 表数据来源。快速入门指南中的 **Comments** 表的默认名称是 `AppSyncCommentTable`，但它可能会根据您指定的名称而有所不同。
1. 将以下代码片段添加到您的请求映射模板中：
```
{
"version": "2017-02-28",
"operation": "Query",
"index": "todoid-index",
"query": {
"expression": "todoid = :todoid",
"expressionValues": {
":todoid": {
"S": $util.toJson($context.source.id)
}
}
}
}
```
1. `context.source` 会引用当前被解析的字段的父对象。在本示例中，`source.id` 指单个 `Todo` 对象，之后它会被用于查询表达式。
您可以如下所示使用传递响应映射模板：
```
$util.toJson($ctx.result.items)
```
1. 选择**保存解析器**。
1. 最后，返回到控制台中的**架构**页面，将一个解析器附加到 `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 ]
您也可以使用 “[创建您的第一个解析器](https://docs.amazonaws.cn/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)” 部分中的命令以及本节中的参数详细信息来执行此操作。 APIs
------
#### [ CLI ]
您也可以在 CLI 中使用[创建您的第一个解析器](https://docs.amazonaws.cn/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)一节中的命令以及本节中的参数详细信息执行该操作。
------