Partilhar via

Uso @env() para substituição de variáveis 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 por valores no tempo de carregamento. O primeiro mecanismo suportado é a função @env(), que resolve variáveis de ambiente do ambiente de processo do host ou de um ficheiro local .env.

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

O que @env() faz

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

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

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

Fontes de valores

Fonte Description
SO / ambiente de processo Variáveis de ambiente padrão presentes quando o processo DAB é iniciado.
arquivo .env Um ficheiro de texto simples com NAME=VALUE linhas no diretório de configuração (para conveniência de desenvolvimento local).

Observação

O .env arquivo substitui as variáveis de ambiente de processo/sistema existentes quando ambas definem o mesmo nome. Se for fornecido um arquivo local .env para desenvolvimento, as suas entradas serão usadas para satisfazer pesquisas de @env('var-name') sem realizar uma chamada para o ambiente local.

Exemplo .env de ficheiro:

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 o seu processo de arranque o espere).
  • Adicionar .env a .gitignore.
  • Linhas em branco e linhas que começam com # (se suportado, verificar) são normalmente ignoradas; confirme antes de documentar o suporte a comentários.
  • No Linux ou macOS, os nomes são sensíveis a maiúsculas e minúsculas. No Windows, eles não diferenciam maiúsculas de minúsculas.

Usando @env() na configuração

Substituição de base

{
  "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 do 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) é manipulada pela configuração consumidora ou lógica de execução em tempo real.

Solução de problemas

Scenario Outcome
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.
Múltiplos @env() em propriedades diferentes Tudo resolvido de forma independente.
Usado onde se espera numérico ou booleano Valor substituído como cadeia de caracteres; o processamento pode ter sucesso.
Padrão inválido (por exemplo @env(DB_VAR) , aspas ausentes) Tratada 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 ficheiros que contenham informações confidenciais. |

Referência rápida

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

Revisão

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

  • Last updated on