Compartilhar via

Uso @env() para substituição de variável de ambiente no Construtor de API de Dados

O Construtor de API de Dados (DAB) permite manter segredos (por exemplo, cadeias de conexão de banco de dados) fora de dab-config.json, substituindo os valores no momento do carregamento. O primeiro mecanismo com suporte é a @env() função que resolve variáveis de ambiente do processo do host ou de um arquivo local .env.

Veja também: the @akv() function.

O que @env() faz

Coloque uma referência a uma variável de ambiente em qualquer lugar em que um valor de cadeia de caracteres seja esperado:

{
  "data-source": {
    "connection-string": "@env('SQL_CONN_STRING')"
  }
}

Durante o carregamento da configuração, o DAB verifica valores de cadeia de caracteres para o modelo @env('VAR_NAME') e substitui o token pelo valor da variável de ambiente VAR_NAME.

Fontes para valores

Source Description
Ambiente do sistema operacional/processo Variáveis de ambiente padrão presentes quando o processo da DAB é iniciado.
Arquivo .env Um arquivo de texto plano com NAME=VALUE linhas no diretório de configuração para facilitar o desenvolvimento local.

Observação

O .env arquivo substitui variáveis de ambiente de processo/sistema existentes quando ambos definem o mesmo nome. Se você fornecer um arquivo local .env para desenvolvimento, suas entradas serão usadas para satisfazer @env(consultas de 'var-name' sem fazer uma chamada ao ambiente local.

Exemplo de arquivo .env:

SQL_CONN_STRING=Server=localhost;Database=AppDb;User Id=app;Password=local-dev;
DB_TYPE=mssql
JOB_API_KEY=dev-job-key

Diretrizes:

  • Mantenha .env adjacente a dab-config.json (ou onde quer que seu processo de inicialização o espere).
  • Adicione .env a .gitignore.
  • Linhas em branco e linhas começando com # (se houver suporte, verifique) costumam ser ignoradas; confirme a possibilidade de suporte a comentários antes de documentar.
  • No Linux/macOS, os nomes são sensíveis a maiúsculas e minúsculas. No Windows, eles não fazem distinção entre maiúsculas e minúsculas.

Usando @env() na configuração

Substituição básica

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@env('SQL_CONN_STRING')"
  }
}

Combinado com @akv()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('prod-sql-connection')"
  }
}

Parâmetros de procedimento armazenado

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "intParam": "@env('SP_PARAM1_INT')",
          "boolParam": "@env('SP_PARAM2_BOOL')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Os valores de ambiente são substituídos como cadeias de caracteres. A análise subsequente (por exemplo, para int ou bool) é tratada pela configuração consumidora ou pela lógica de tempo de execução.

Resolução de problemas

Scenario Resultado
Variável encontrada A substituição é bem-sucedida.
Variável ausente Provável falha na carga de configuração.
Variável não encontrada Substituído como cadeia de caracteres vazia.
Várias @env() em diferentes propriedades Tudo resolvido de forma independente.
Usado onde o valor numérico ou bool é esperado Valor substituído como cadeia de caracteres; A análise pode ter êxito.
Padrão inválido (por exemplo @env(DB_VAR) , aspas ausentes) Tratado como uma cadeia de caracteres literal.

Exemplo completo

dab-config.json:

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@env('SQL_CONN_STRING')"
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

.env:

DB_TYPE=mssql
SQL_CONN_STRING=Server=localhost;Database=BooksDb;User Id=app;Password=StrongPassword!;

Importante

Não confirme .env arquivos que contêm segredos. |

Referência rápida

Item Resumo
Sintaxe @env('variable-name')
Arquivo de simulação .env com name=value linhas
Misturando com @env() Suportado.

Review

Use @env() para manter segredos e valores específicos do ambiente fora dos arquivos de configuração. Emparelhe-o com o gerenciamento de segredo disciplinado, como repositórios de variáveis de CI/CD ou definições de contêiner, para uma implantação segura e flexível. Para uso do cofre empresarial, combine com a @akv() função para centralizar segredos.

  • Last updated on