配置解析器 (VTL) - Amazon AppSync
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

配置解析器 (VTL)

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

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

此部分将向您展示如何使用 VTL 配置解析器。有关编写解析器的入门教程式编程指南可在 Resol ver 映射模板编程指南中找到,编程时可用的辅助实用程序可在 Resolver 映射模板上下文参考中找到。Amazon AppSync 还具有内置的测试和调试流程,您可以在从头开始编辑或创作时使用这些流程。有关更多信息,请参阅测试和调试解析器

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

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

创建您的第一个解析器

按照前面部分的示例,第一步是为您的Query类型创建解析器。

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 在页面的右侧,有一个名为 “解析器” 的窗口。此框包含在页面左侧的 “架构” 窗口中定义的类型和字段列表。您可以将解析器附加到字段。例如,在 “查询类型” 下,选择getTodos字段旁边的 “附加”。

  3. 在 “创建解析器” 页面上,选择您在 “附加数据源” 指南中创建的数据源。在配置映射模板窗口中,您可以使用右侧的下拉列表选择通用请求和响应映射模板,也可以自己编写。

    注意

    请求映射模板与响应映射模板的配对称为单位解析器。单元解析器通常用于执行死记硬背的操作;我们建议仅将其用于具有少量数据源的单一运算。对于更复杂的操作,我们建议使用管道解析器,它可以对多个数据源按顺序执行多个操作。

    有关请求映射模板与响应映射模板之间的差别的更多信息,请参阅单元解析器

    有关使用管道解析器的更多信息,请参阅管道解析器

  4. 对于常见用例,Amazon AppSync 控制台具有内置模板,您可以使用这些模板从数据源获取项目(例如,所有项目查询、个人查询等)。例如,在 Designing your schema 中getTodos没有分页的简单架构版本上,用于列出项目的请求映射模板如下所示:

    { "version" : "2017-02-28", "operation" : "Scan" }
  5. 您始终需要一个响应映射模板来附带请求。控制台为列表提供的默认模板具有以下传递值:

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

    此示例中,项目列表的 context 对象(别名为 $ctx)的格式为 $context.result.items。如果您的 GraphQL 操作返回单个项目,则会返回$context.result。Amazon AppSync为常见操作(例如前面列出的$util.toJson函数)提供辅助函数,以正确格式化响应。有关函数的完整列表,请参阅 Resolver 映射模板实用程序参考

  6. 选择 “保存解析器”。

API
  1. 通过调用 CreateResolverAPI 创建解析器对象。

  2. 您可以通过调用 UpdateResolverAPI 来修改解析器的字段。

CLI
  1. 通过运行create-resolver命令创建解析器。

    你需要为这个特定命令输入 6 个参数:

    1. api-id的 API 的。

    2. type-name在架构中,要修改的类型。在控制台示例中,这是Query

    3. field-name在您的类型中,修改的字段。在控制台示例中,这是getTodos

    4. 您在data-source-name附加数据源》指南中创建的数据源的。

    5. request-mapping-template,这是请求的正文。在控制台示例中,这是:

      { "version" : "2017-02-28", "operation" : "Scan" }
    6. 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)" } }
  2. 要修改解析器的字段和/或映射模板,请运行update-resolver命令。

    api-id参数外,create-resolver命令中使用的参数将被命令中的新值覆盖。update-resolver

为突变添加解析器

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

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 在 “突变类型” 下,选择该addTodo字段旁边的 “附加”。

  3. 在 “创建解析器” 页面上,选择您在 “附加数据源” 指南中创建的数据源

  4. 在 “配置映射模板” 窗口中,您需要修改请求模板,因为这是您向 DynamoDB 添加新项目的变更。使用以下请求映射模板:

    { "version" : "2017-02-28", "operation" : "PutItem", "key" : { "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id) }, "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args) }
  5. Amazon AppSync 自动将addTodo字段中定义的参数从 GraphQL 架构转换为 DynamoDB 操作。前面的示例使用密钥在 DynamoDB 中存储记录id,该密钥是从变异参数传递的$ctx.args.id。您传递的所有其他字段都会自动映射到 DynamoDB 属性$util.dynamodb.toMapValuesJson($ctx.args)

    对于此解析程序,使用以下响应映射模板:

    $util.toJson($ctx.result)

    Amazon AppSync 还支持编辑解析器的测试和调试工作流程。您可在调用之前使用模拟 context 对象查看模板经过转换的值。还可在运行查询时选择以交互方式查看对数据源的完整请求执行过程。有关更多信息,请参阅测试和调试解析器以及监控和记录

  6. 选择 “保存解析器”。

API

您也可以使用 “创建您的第一个解析器” 部分中的命令和本节中的参数详细信息通过 API 来实现此目的。

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表创建了数据源,如附加数据源中所述。

注意

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

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 在 “待办事项类型” 下,选择该comments字段旁边的 “附加”。

  3. 在 “创建解析器” 页面上,选择您的评论表数据源。快速入门指南中 “评论” 表格的默认名称是AppSyncCommentTable,但它可能会因您为其命名的不同而有所不同。

  4. 将以下片段添加到您的请求映射模板中:

    { "version": "2017-02-28", "operation": "Query", "index": "todoid-index", "query": { "expression": "todoid = :todoid", "expressionValues": { ":todoid": { "S": $util.toJson($context.source.id) } } } }
  5. context.source 会引用当前被解析的字段的父对象。在本示例中,source.id 指单个 Todo 对象,之后它会被用于查询表达式。

    您可以如下所示使用传递响应映射模板:

    $util.toJson($ctx.result.items)
  6. 选择 “保存解析器”。

  7. 最后,返回控制台的 “架构” 页面,将解析器连接到该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

您也可以使用 “创建您的第一个解析器” 部分中的命令和本节中的参数详细信息通过 API 来实现此目的。

CLI

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