Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

解析器映射模板上下文参考

Amazon AppSync 定义了一组用于处理解析器映射模板的变量和函数。这样，就可以更轻松地通过 GraphQL 对数据进行逻辑操作。本文档将介绍这些函数，并提供使用模板的示例。

使用 $context

$context 变量是一个映射，它保留进行解析器调用的所有上下文信息。它具有以下结构：

{
   "arguments" : { ... },
   "source" : { ... },
   "result" : { ... },
   "identity" : { ... },
   "request" : { ... },
   "info": { ... }
}

$context 映射中每个字段的定义如下所示：

$context 字段

求同

identity 部分包含调用方的相关信息。此部分的形态取决于您的 Amazon AppSync API 的授权类型。

有关 Amazon AppSync 安全选项的更多信息，请参阅授权和身份验证。

每个字段的定义如下所示：

访问请求标头

Amazon AppSync 支持从客户端传递自定义标头，并使用 $context.request.headers 在 GraphQL 解析器中访问这些标头。然后，您可以使用标头值执行操作，例如，将数据插入到数据源或进行授权检查。您可以在命令行中使用 $curl 将一个或多个请求标头与 API 密钥一起使用，如以下示例中所示：

单标头示例

假设您设置一个 custom 标头，值为 nadia，如下所示：

curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

然后可使用 $context.request.headers.custom 访问它。例如，对于 DynamoDB，它可能位于以下 VTL 中：

"custom": $util.dynamodb.toDynamoDBJson($context.request.headers.custom)

多标头示例

您还可以在一个请求中传递多个标头，并在解析器映射模板中访问它们。例如，如果为 custom 标头设置了两个值：

curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

它们可以作为一个数组访问，例如 $context.request.headers.custom[1]。

访问请求自定义域名

Amazon AppSync 支持配置自定义域，您可以使用该域访问 API 的 GraphQL 和实时终端节点。在使用自定义域名发出请求时，您可以使用 $context.request.domainName 获取域名。

在使用默认 GraphQL 终端节点域名时，值为 null。

Info

info 部分包含有关 GraphQL 请求的信息。该部分采用以下格式：

{
    "fieldName": "string",
    "parentTypeName": "string",
    "variables": { ... },
    "selectionSetList": ["string"],
    "selectionSetGraphQL": "string"
}

每个字段的定义如下所示：

例如，如果您要解析以下查询的 getPost 字段：

query {
  getPost(id: $postId) {
    postId
    title
    secondTitle: title
    content
    author(id: $authorId) {
      authorId
      name
    }
    secondAuthor(id: "789") {
      authorId
    }
    ... on Post {
      inlineFrag: comments: {
        id
      }
    }
    ... postFrag
  }
}

fragment postFrag on Post {
  postFrag: comments: {
    id
  }
}

那么，在处理映射模板时可用的完整 $context.info 变量可以是：

{
  "fieldName": "getPost",
  "parentTypeName": "Query",
  "variables": {
    "postId": "123",
    "authorId": "456"
  },
  "selectionSetList": [
    "postId",
    "title",
    "secondTitle"
    "content",
    "author",
    "author/authorId",
    "author/name",
    "secondAuthor",
    "secondAuthor/authorId",
    "inlineFragComments",
    "inlineFragComments/id",
    "postFragComments",
    "postFragComments/id"
  ],
  "selectionSetGraphQL": "{\n  getPost(id: $postId) {\n    postId\n    title\n    secondTitle: title\n    content\n    author(id: $authorId) {\n      authorId\n      name\n    }\n    secondAuthor(id: \"789\") {\n      authorId\n    }\n    ... on Post {\n      inlineFrag: comments {\n        id\n      }\n    }\n    ... postFrag\n  }\n}"
}

selectionSetList 仅公开属于当前类型的字段。如果当前类型是接口或联合，则仅公开属于该接口的选定字段。例如，给定以下架构：

type Query {
    node(id: ID!): Node
}

interface Node {
    id: ID
}

type Post implements Node {
    id: ID
    title: String
    author: String
}

type Blog implements Node {
    id: ID
    title: String
    category: String
}

以及以下查询：

query {
    node(id: "post1") {
        id
        ... on Post {
            title
        }

        ... on Blog {
            title
        }
    }
}

如果在进行 Query.node 字段解析时调用 $ctx.info.selectionSetList，则仅公开 id：

"selectionSetList": [
    "id"
]

清理输入

应用程序必须对不可信的输入进行清理，以防止任何外部方在应用程序的预期用途之外使用该应用程序。由于 $context 包含 $context.arguments、$context.identity、$context.result、$context.info.variables 和 $context.request.headers 等属性中的用户输入，因此，务必谨慎在映射模板中清理它们的值。

由于映射模板代表 JSON，因此输入清理采用从表示用户输入的字符串转义 JSON 保留字符的形式。将 JSON 保留字符放入映射模板时，最佳做法是使用 $util.toJson() 实用程序从敏感字符串值转义 JSON 保留字符。

例如，在以下 Lambda 请求映射模板中，由于我们访问了不安全的客户输入字符串 ($context.arguments.id)，因此，我们使用 $util.toJson() 将其包装起来，以防止未转义的 JSON 字符破坏 JSON 模板。

{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": $util.toJson($context.arguments.id)
    }
}

下面的映射模板与之相反，我们直接插入 $context.arguments.id 而不进行清理。这不适用于包含未转义引号或其他 JSON 保留字符的字符串，并且可能使您的模板很容易失败。

## DO NOT DO THIS
{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "$context.arguments.id" ## Unsafe! Do not insert $context string values without escaping JSON characters.
    }
}