Resolver Mapping Template Context Reference

AWS AppSync defines a set of variables and functions for working with resolver mapping templates to make logicful 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 which holds all of the contextual information for your resolver invocation. It has the following structure:


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

Note: If you are trying to access a dictionary/map entry (such as an entry in context) by its key to retrieve the value, the VTL allows for you to directly use the notation <dictionary-element>.<key-name>. However, this might not work for all cases, such as when the key names have special characters (for example, an underscore "_"). We recommend that you always use <dictionary-element>.get(“<key-name>”) notation.

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

arguments: A map containing all GraphQL arguments for this field.
identity: An object containing information about the caller. For more information about the structure of this field, see Identity.
source: A map containing the resolution of the parent field.
stash: The stash is a Map that is made available inside each resolver and function mapping template. The same stash instance lives through a single resolver execution. What this means is you can use the stash to pass arbitrary data across request and response mapping templates, and across functions in a pipeline resolver. The stash exposes the same methods as the Java Map data structure.

result

A container for the results of this resolver. This field is only available to response mapping templates.

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


query {
    getPost(id: 1234) {
        postId
        title
        content
        author {
            id
            name
        }
    }
}

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


{
  "arguments" : {
    id: "1234"
  },
  "source": {},
  "result" : {
      "postId": "1234"
      "title": "Some title"
      "content": "Some content"
      "author": {
        "id": "5678"
        "name": "Author Name"
      }
  },
  "identity" : {
      "sourceIp" : ["x.x.x.x"],
      "userArn" : "arn:aws:iam::123456789012:user/appsync",
      "accountId" : "123456789012",
      "user" : "AIDAAAAAAAAAAAAAAAAAA"
  }
}

prev.result

It represents the result of whatever previous operation that was executed in a pipeline resolver. If the previous operation was the pipeline resolver request mapping template, then $ctx.prev.result represents the output of the evaluation of the template and is made available to the first function in the pipeline. If the previous operation was the first function, then $ctx.prev.result represents the output of the first function and is made available to the second function in the pipeline. If the previous operation was the last function, then $ctx.prev.result represents the output of the first function and is made available to the pipeline resolver response mapping template.

Identity

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

For more information about this section and how it can be used, see Security.

API_KEY authorization

The identity field is not populated.

AWS_IAM authorization

The identity has the following shape:


{
    "accountId" = "string",
    "cognitoIdentityPoolId" = "string",
    "cognitoIdentityId" = "string",
    "sourceIp" = ["string"],
    "username" = "string", // IAM user principal
    "userArn" = "string"
}

AMAZON_COGNITO_USER_POOLS authorization

The identity has the following shape:


{
    "sub" : "uuid",
    "issuer" : "string",
    "username" : "string"
    "claims" : { ... },
    "sourceIp" : ["x.x.x.x"],
    "defaultAuthStrategy" : "string"
}

Each field is defined as follows:

accountId: The AWS account ID of the caller.
claims: The claims the user has.
cognitoIdentityId: The Amazon Cognito identity ID of the caller.
cognitoIdentityPoolId: The Amazon Cognito identity pool ID associated with the caller.
defaultAuthStrategy: The default auth strategy for this caller (ALLOW or DENY).
issuer: The token issuer.
sourceIp: The source IP address of the caller received by AppSync. If the request doesn't include the x-forwarded-for header, the source IP value contains only a single IP Address from the TCP Connection. If the request includes a x-forwarded-for header, the source IP is a list of IP Addresses from the x-forwarded-for header, in addition to the IP address from the TCP connection.
sub: The UUID of the authenticated user.
user: The IAM user.
userArn: The IAM user ARN.
username: The username of the authenticated user. In case of AMAZON_COGNITO_USER_POOLS authorization, the value of username is the value of attribute cognito:username. In case of AWS_IAM authorization, the value of the username is the value of the AWS User Principal. We recommend that you use cognitoIdentityId if you are using AWS IAM authorization with credentials vended from Amazon Cognito federated identities.

Access Request Headers

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

Single Header Example

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


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": { "S": "$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 was 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]".

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »

Resolver Mapping Template Context Reference

Accessing the $context

Identity

Access Request Headers

Accessing the `$context`