Uso de variáveis de ambiente no AWS AppSync

É possível usar variáveis de ambiente para ajustar o comportamento de resolvedores e funções do AWS AppSync sem atualizar o código. As variáveis de ambiente são pares de strings armazenadas com sua configuração de API que são disponibilizadas para seus resolvedores e funções para serem aproveitadas em runtime. Elas são particularmente úteis para situações em que você precisa consultar dados de configuração que só estão disponíveis durante a configuração inicial, mas precisam ser usados por seus resolvedores e funções durante a execução. As variáveis de ambiente expõem os dados de configuração em seu código, reduzindo assim a necessidade de codificar esses valores.

As variáveis de ambiente devem seguir vários comportamentos e regras para funcionar adequadamente:

Configurar variáveis de ambiente (console)

Você pode configurar variáveis de ambiente para sua API GraphQL do AWS AppSync criando a variável e definindo seu par de chave-valor. Seus resolvedores e funções usarão o nome da chave da variável de ambiente para recuperar o valor em runtime. Para definir variáveis de ambiente no console do AWS AppSync:

Configurar variáveis de ambiente (API)

Para definir uma variável de ambiente usando APIs, você pode usar PutGraphqlApiEnvironmentVariables. O comando CLI correspondente é put-graphql-api-environment-variables.

Para recuperar uma variável de ambiente usando APIs, você pode usar GetGraphqlApiEnvironmentVariables. O comando CLI correspondente é get-graphql-api-environment-variables.

O comando deve conter o ID da API e a lista de variáveis de ambiente:

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

O exemplo a seguir define duas variáveis de ambiente em uma API com o ID abcdefghijklmnopqrstuvwxyz usando o comando put-graphql-api-environment-variables:

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

Observe que, quando você aplica variáveis de ambiente com o comando put-graphql-api-environment-variables, o conteúdo da estrutura das variáveis de ambiente é sobrescrito; isso significa que as variáveis de ambiente existentes serão perdidas. Para reter variáveis de ambiente existentes ao adicionar outras novas, inclua todos os pares de chave-valor existentes junto com os novos em sua solicitação. Usando o exemplo acima, se quiser adicionar "EMPTY":"", você pode fazer o seguinte:

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

Para recuperar a configuração atual, use o comando get-graphql-api-environment-variables:

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

Usando o exemplo acima, você poderia usar o comando a seguir:

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

O resultado mostrará a lista de variáveis de ambiente junto com seus valores de chave:

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

Configuração de variáveis de ambiente (CFN)

Você pode usar o modelo abaixo para criar variáveis de ambiente:

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

Variáveis de ambiente e APIs mescladas

As variáveis de ambiente definidas nas APIs de origem também estão disponíveis em suas APIs mescladas. As variáveis de ambiente nas APIs mescladas são somente para leitura e não podem ser atualizadas. Observe que suas chaves de variáveis de ambiente devem ser exclusivas em todas as APIs de origem para que suas mesclagens sejam bem-sucedidas; chaves duplicadas sempre resultarão em uma falha na mesclagem.

Recuperar variáveis de ambiente

Para recuperar variáveis de ambiente em seu código de função, recupere o valor do ctx.env objeto em seus resolvedores e funções. Veja a seguir alguns exemplos.

Publishing to Amazon SNS

Neste exemplo, nosso resolvedor de HTTP envia uma mensagem para um tópico do Amazon SNS. O ARN do tópico só é conhecido depois que a pilha que define a API GraphQL e o tópico são implantados.

/**
 * 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

Neste exemplo, os nomes da tabela do DynamoDB serão diferentes se a API for implantada para preparação ou se já estiver em produção. O código do resolvedor não precisa mudar. Os valores das variáveis de ambiente são atualizados com base no local onde a API é implantada.

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
      },
    ],
  };
}