Variáveis de ambiente

Com as variáveis de ambiente, você pode adicionar variáveis no processo do aplicativo executado em um ambiente sem precisar fazer mudanças no código. Elas são armazenadas com segurança, o que as torna ideais para os seguintes casos de uso:

• Chaves de API para integrações de terceiros
• Sinalizadores de funcionalidade para a lógica do aplicativo
• Configuração que difere entre ambientes ou que pode não ser secreta

Siga estes tutoriais para definir variáveis de ambiente e, em seguida, implemente o código em seu site PWA Kit para usar as variáveis. Você pode personalizar o código de acordo com suas necessidades específicas. Os tutoriais mostram como:

• Acessar recursos protegidos com variáveis de ambiente
• Usar variáveis de ambiente no React.js

Recomendamos testar as etapas em sua máquina local e, em seguida, em um ambiente que não seja de produção, antes de implantar suas alterações na produção. Para obter mais orientações, consulte Práticas recomendadas, Solucionar problemas de variáveis de ambiente e Depuração local.

Variáveis de ambiente:

• Podem ser gerenciadas usando a Managed Runtime API ou o Runtime Admin
• São acessadas em Node.js usando process.env

Ao introduzir uma nova variável de ambiente, primeiro a defina via API ou Runtime Admin. Aguarde até que a reimplantação seja concluída e, em seguida, implante um novo pacote que a utilize.

Definir, atualizar e cancelar a definição de variáveis de ambiente

Use projects_target_env_var_partial_update:

Para cancelar a definição de uma variável de ambiente existente, defina seu valor como null.

A modificação de variáveis de ambiente reimplanta o ambiente. Os valores atualizados estarão disponíveis quando a implantação for concluída.

Obter todas as variáveis de ambiente

Use projects_target_env_var_list:

Para criar, atualizar, remover ou visualizar variáveis de ambiente:

1. Faça logon no Runtime Admin. Para obter acesso ao Runtime Admin, consulte Administração do Managed Runtime.
2. Vá para a página Overview de um projeto.
3. Clique no nome do ambiente para o qual você deseja gerenciar variáveis de ambiente.
4. Clique em Variáveis de ambiente na navegação à esquerda.

• Escolha nomes para as variáveis de ambiente que façam sentido para o seu aplicativo. Use nomes descritivos: Escolha nomes claros e concisos para suas variáveis de ambiente para torná-las facilmente compreensíveis para sua equipe.
• Evite codificar informações confidenciais, como chaves de API, em seu código. Use variáveis de ambiente para mantê-las seguras.
• Não passe variáveis de ambiente para dados que serão serializados para a página. Considere adicionar um teste para garantir que você não está vazando dados de variáveis de ambiente.
• Não retorne variáveis de ambiente de ganchos react-query ou getProps.
• Use variáveis de ambiente somente no lado do servidor. Por padrão, as variáveis de ambiente não são expostas no lado do cliente. Você pode optar por expô-los no lado do cliente (por exemplo, em seu arquivo de configuração), mas certifique-se de que a exposição dos valores esteja em conformidade com suas práticas de segurança.
• Teste as variáveis de ambiente em sua máquina local e, em seguida, em um ambiente que não seja de produção antes de implantá-las em produção. Isso ajuda a garantir que você possa resolver problemas localmente com rapidez, simular o comportamento do site, validar a funcionalidade e fazer qualquer teste de aceitação do usuário antes de implantar em produção.
• Inclua o tratamento de erros em seu código que usa variáveis de ambiente para evitar falhas devido a variáveis de ambiente indefinidas.
• Controle o acesso às variáveis de ambiente para evitar modificações não autorizadas.
• Documente a finalidade e a configuração de cada variável de ambiente. Isso ajuda na integração de novos desenvolvedores e na solução de problemas.

O uso de variáveis de ambiente está sujeito às seguintes limitações:

• Os valores das variáveis de ambiente devem ser strings. Para armazenar valores complexos, codifique JSON em uma cadeia de caracteres.
• Cada ambiente tem um limite de 100 variáveis de ambiente.
• O tamanho máximo dos valores das variáveis de ambiente definidas é 32 KB.
• Os nomes das variáveis de ambiente precisam ter até 512 caracteres e não podem começar com prefixos reservados: AWS, MRT, X_MRT, MOBIFY, X_MOBIFY, SSR_PROXY, NODE.
• Os nomes das variáveis de ambiente não podem usar nenhum nome reservado: BUNDLE_ID, DEPLOY_ID, DEPLOY_TARGET, EXTERNAL_DOMAIN_NAME, HANDLER, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, NODE_ENV, REDIRECT_BUCKET, REDIRECT_KEY, REDIRECT_UPDATE, REMOTE, X_AMZN_TRACE_ID.

Esta seção fornece soluções sugeridas para erros comuns que você pode encontrar ao usar variáveis de ambiente.

Seu código lança uma declaração Error sobre a ausência de uma variável.

Causa: A variável de ambiente que o código chama não está definida.

Solução sugerida: Chame o o endpoint da projects_target_env_var_partial_update API para definir a variável de ambiente aplicável.

Seu código registra uma mensagem de erro informando que a variável de ambiente não foi encontrada.

Causa: O código não conseguiu localizar a variável de ambiente porque há um erro de digitação no código ou um nome de variável de ambiente incorreto é usado.

Solução sugerida: Confirme se você digitou o nome da variável de ambiente corretamente em seu código e se usou o nome da variável de ambiente desejado. Verifique o nome da variável de ambiente chamando o endpoint da projects_target_env_var_list API para ver a lista completa de variáveis definidas.

Há falha na chamada de API para definir uma variável de ambiente.

Causa: O nome da variável de ambiente pode não estar em conformidade com as restrições. Por exemplo, o tamanho do valor de uma variável de ambiente é superior a 32 KB.

Solução sugerida: Confirme se a variável de ambiente está em conformidade com as restrições.

Erros de autenticação ocorrem quando você executa código que envolve o uso de uma chave de API.

Causa: A chave de API usada ao definir a variável de ambiente não está no formato esperado ou está ausente.

Solução sugerida: Confirme se a chave de API armazenada por uma variável de ambiente está correta. Se necessário, chame o endpoint da projects_target_env_var_partial_update API para corrigir a chave da API.

Uma solicitação fetch falha com um erro de rede.

Causa: Um URL para qualquer endpoint de API chamado em seu código pode não ter sido definido corretamente ou é inválido. Por exemplo, o URL de um endpoint do sistema de gerenciamento de conteúdo (CMS) está incorreto.

Solução sugerida: Confirme se todos os URLs para endpoints de API em seu código estão corretos.