Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Resolver mapping template context reference

Amazon AppSync defines a set of variables and functions for working with resolver mapping templates. This makes logical operations on data easier with GraphQL. This document describes those functions and provides examples for working with templates.

Accessing the $context

The $context variable is a map that holds all of the contextual information for your resolver invocation. It has the following structure:

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

Each field in the $context map is defined as follows:

$context fields

Identity

The identity section contains information about the caller. The shape of this section depends on the authorization type of your Amazon AppSync API.

For more information about Amazon AppSync security options, see Authorization and authentication.

Each field is defined as follows:

Access request headers

Amazon AppSync supports passing custom headers from clients and accessing them in your GraphQL resolvers by using $context.request.headers. You can then use the header values for actions such as inserting data into a data source or authorization checks. You can use single or multiple request headers using $curl with an API key from the command line, as shown in the following examples:

Single header example

Suppose you set a header of custom with a value of nadia like the following:

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

This could then be accessed with $context.request.headers.custom. For example, it might be in the following VTL for DynamoDB:

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

Multiple header example

You can also pass multiple headers in a single request and access these in the resolver mapping template. For example, if the custom header is set with two values:

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

You could then access these as an array, such as $context.request.headers.custom[1].

Access the request custom domain name

Amazon AppSync supports configuring a custom domain that you can use to access your GraphQL and real-time endpoints for your APIs. When making a request with a custom domain name, you can get the domain name using $context.request.domainName.

When using the default GraphQL endpoint domain name, the value is null.

Info

The info section contains information about the GraphQL request. This section has the following form:

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

Each field is defined as follows:

For example, if you are resolving the getPost field of the following query:

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

Then the full $context.info variable that is available when processing a mapping template might be:

{
  "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 exposes only fields that belong to the current type. If the current type is an interface or union, only selected fields that belong to the interface are exposed. For example, given the following schema:

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
}

And the following query:

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

        ... on Blog {
            title
        }
    }
}

When calling $ctx.info.selectionSetList at the Query.node field resolution, only id is exposed:

"selectionSetList": [
    "id"
]

Sanitizing inputs

Applications must sanitize untrusted inputs to prevent any external party from using an application outside of its intended use. As the $context contains user inputs in properties such as $context.arguments, $context.identity, $context.result, $context.info.variables, and $context.request.headers, care must be taken to sanitize their values in mapping templates.

Since mapping templates represent JSON, input sanitization takes the form of escaping JSON reserved characters from strings that represent user inputs. It is best practice to use the $util.toJson() utility to escape JSON reserved characters from sensitive string values when placing them into a mapping template.

For example, in the following Lambda request mapping template, because we accessed an unsafe customer input string ($context.arguments.id), we wrapped it with $util.toJson() to prevent unescaped JSON characters from breaking the JSON template.

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

As opposed to the mapping template below, where we directly insert $context.arguments.id without sanitization. This does not work for strings containing unescaped quotation marks or other JSON reserved characters, and can leave your template open to failure.

## 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.
    }
}