Using environment variables in AWS AppSync

You can use environment variables to adjust your AWS AppSync resolvers' and functions' behavior without updating your code. Environment variables are pairs of strings stored with your API configuration that are made available to your resolvers and functions to leverage at runtime. They're particularly useful for situations in which you must reference configuration data that's only available during the initial setup but needs to be used by your resolvers and functions during the run. Environment variables expose configuration data in your code, thereby reducing the need to hard-code those values.

Environment variables must follow several behaviors and rules to function properly:

Configuring environment variables (console)

You can configure environment variables for your AWS AppSync GraphQL API by creating the variable and defining its key-value pair. Your resolvers and functions will use the environment variable's key name to retrieve the value at runtime. To set environment variables in the AWS AppSync console:

Configuring environment variables (API)

To set an environment variable using APIs, you can use PutGraphqlApiEnvironmentVariables. The corresponding CLI command is put-graphql-api-environment-variables.

To retrieve an environment variable using APIs, you can use GetGraphqlApiEnvironmentVariables. The corresponding CLI command is get-graphql-api-environment-variables.

The command must contain the API ID and list of environment variables:

aws appsync put-graphql-api-environment-variables \  
  --api-id "<api-id>" \
  --environment-variables '{"key1":"value1","key2":"value2", …}'

The following example sets two environment variables in an API with the ID of abcdefghijklmnopqrstuvwxyz using the put-graphql-api-environment-variables command:

aws appsync put-graphql-api-environment-variables \  
  --api-id "abcdefghijklmnopqrstuvwxyz" \
  --environment-variables '{"USER_TABLE":"users_prod","DEBUG":"true"}'

Note that when you apply environment variables with the put-graphql-api-environment-variables command, the contents of the environment variables' structure are overwritten; this means existing environment variables will be lost. To retain existing environment variables when adding new ones, include all existing key-value pairs along with the new ones in your request. Using the example above, if you wanted to add "EMPTY":"", you could do the following:

aws appsync put-graphql-api-environment-variables \  
  --api-id "abcdefghijklmnopqrstuvwxyz" \
  --environment-variables '{"USER_TABLE":"users_prod","DEBUG":"true", "EMPTY":""}'

To retrieve the current configuration, use the get-graphql-api-environment-variables command:

aws appsync get-graphql-api-environment-variables --api-id "<api-id>"

Using the example above, you could use the following command:

aws appsync get-graphql-api-environment-variables --api-id "abcdefghijklmnopqrstuvwxyz"

The result will show the list of environment variables along with their key values:

{
    "environmentVariables": {
        "USER_TABLE": "users_prod",
        "DEBUG": "true",
        "EMPTY": ""
    }
}

Configuring environment variables (CFN)

You can use the template below to create environment variables:

AWSTemplateFormatVersion: 2010-09-09
Resources:
  GraphQLApiWithEnvVariables:
    Type: "AWS::AppSync::GraphQLApi"
    Properties:
      Name: "MyApiWithEnvVars"
      AuthenticationType: "AWS_IAM"
      EnvironmentVariables:
        EnvKey1: "non-empty"
        EnvKey2: ""

environment variables and merged APIs

Environment variables defined in Source APIs are also available in your Merged APIs. Environment variables in Merged APIs are read-only and cannot be updated. Note that your environment variable keys must be unique across all Source APIs for your merges to succeed; duplicate keys will always result in a merge failure.

Retrieving environment variables

To retrieve environment variables in your function code, retrieve the value from the ctx.env object in your resolvers and functions. Below are some examples of this in action.

Publishing to Amazon SNS

In this example, our HTTP resolver sends a message to an Amazon SNS topic. The ARN of the topic is only known after the stack that defines the GraphQL API and the topic has been deployed.

/**
 * Sends a publish request to the SNS topic
 */
export function request(ctx) {
    const TOPIC_ARN = ctx.env.TOPIC_ARN;
    const { input: values } = ctx.args;
    // this custom function sends values to the SNS topic
    return publishToSNSRequest(TOPIC_ARN, values);
}

Transactions with DynamoDB

In this example, the names of the DynamoDB table are different if the API is deployed for staging or is already in production. The resolver code doesn't need to change. The values of the environment variables are updated based on where the API is deployed.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { authorId, postId } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: ctx.env.POST_TABLE,
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ postId }),
        // rest of the configuration
      },
      {
        table: ctx.env.AUTHOR_TABLE,
        operation: 'UpdateItem',
        key: util.dynamodb.toMapValues({ authorId }),
        // rest of the configuration
      },
    ],
  };
}