Usando variáveis de ambiente em AWS AppSync

Você pode usar variáveis de ambiente para ajustar o comportamento de seus AWS AppSync resolvedores e funções sem atualizar seu código. Variáveis de ambiente são pares de cadeias de caracteres armazenadas com sua API configuração que são disponibilizadas para seus resolvedores e funções para serem aproveitadas em tempo de execução. Eles são particularmente úteis para situações em que você precisa referenciar 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.

nota

Para aumentar a segurança do banco de dados, recomendamos que você use o Secrets Manager ou o AWS Systems Manager Parameter Store em vez de variáveis de ambiente para armazenar credenciais ou informações confidenciais. Para aproveitar esse recurso, consulte Invocação de AWS serviços com fontes AWS AppSync HTTP de dados.

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

• Tanto os JavaScript resolvedores/funções quanto os VTL modelos oferecem suporte a variáveis de ambiente.

• As variáveis de ambiente não são avaliadas antes da invocação da função.

• As variáveis de ambiente só oferecem suporte a valores de string.

• Qualquer valor definido em uma variável de ambiente é considerado uma string literal e não expandido.

• Idealmente, as avaliações de variáveis devem ser realizadas no código da função.

Configurar variáveis de ambiente (console)

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

1. Faça login no AWS Management Console e abra o AppSyncconsole.

2. Na APIspágina, escolha o nome de um GraphQLAPI.

3. Na sua API página inicial, no painel de navegação, escolha Configurações.

4. Em Variáveis de ambiente, escolha Adicionar variável de ambiente.

5. Escolha Add environment variable (Adicionar variável de ambiente).

6. Insira um par de chave e valor.

7. Se necessário, repita as etapas 5 e 6 para adicionar mais valores-chave. Se você precisar remover um valor de chave, escolha a opção Remover e a (s) chave (s) a ser removida.

8. Selecione Enviar.

dica

Há algumas regras que você deve seguir ao criar chaves e valores:

• As chaves devem começar com uma letra.

• As chaves devem ter pelo menos dois caracteres.

• As teclas só podem conter letras, números e o caractere sublinhado (_).

• Os valores podem ter até 512 caracteres.

• Você pode configurar até 50 pares de valores-chave em um GraphQL. API

Configurar variáveis de ambiente (API)

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

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

O comando deve conter o API ID 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 um API com o ID de abcdefghijklmnopqrstuvwxyz uso do put-graphql-api-environment-variables comando:

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 put-graphql-api-environment-variables comando, o conteúdo da estrutura das variáveis de ambiente é sobrescrito; isso significa que as variáveis de ambiente existentes serão perdidas. Para manter as variáveis de ambiente existentes ao adicionar novas, inclua todos os pares de valores-chave existentes junto com os novos em sua solicitação. Usando o exemplo acima, se você 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 get-graphql-api-environment-variables comando:

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

Usando o exemplo acima, você pode usar o seguinte comando:

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

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

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

Configurar 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 mescladas APIs

As variáveis de ambiente definidas em Source também APIs estão disponíveis em seu MergedAPIs. As variáveis de ambiente no Merged APIs são somente para leitura e não podem ser atualizadas. Observe que suas chaves variáveis de ambiente devem ser exclusivas em todo o Source APIs 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. Abaixo estão alguns exemplos disso em ação.

Publishing to Amazon SNS

Neste exemplo, nosso HTTP resolvedor envia uma mensagem para um SNS tópico da Amazon. O ARN tópico só é conhecido depois que a pilha que define o API GraphQL e o tópico foram 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 são diferentes se ela for implantada para teste ou se API já estiver em produção. O código do resolvedor não precisa ser alterado. Os valores das variáveis de ambiente são atualizados com base em onde elas API são implantadas.

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