Usare @env() per la sostituzione delle variabili di ambiente in Generatore API dati

Il generatore di API dati (DAB) consente di mantenere i segreti (ad esempio, le stringhe di connessione del database) nascosti attraverso la sostituzione dei valori durante il caricamento di dab-config.json. Il primo meccanismo supportato è la @env() funzione , che risolve le variabili di ambiente dall'ambiente del processo host o da un file locale .env .

Vedere anche: the @akv() function.

Che cosa @env() fa

Inserire un riferimento a una variabile di ambiente ovunque sia previsto un valore stringa:

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

In fase di caricamento della configurazione, DAB analizza i valori stringa per il modello @env('VAR_NAME') e sostituisce il token con il valore della variabile di ambiente VAR_NAME.

Origini per i valori

Fonte	Description
Ambiente del sistema operativo/processo	Variabili di ambiente standard presenti all'avvio del processo DAB.
File .env	File di testo non crittografato con NAME=VALUE righe nella directory di configurazione (per praticità di sviluppo locale).

Annotazioni

Il file .env sostituisce le variabili di ambiente del processo/sistema esistenti quando entrambe definiscono lo stesso nome. Se si fornisce un file locale .env per lo sviluppo, le relative voci vengono utilizzate per soddisfare le query @env('var-name' senza effettuare una chiamata all'ambiente locale.

File di esempio .env :

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

Istruzioni:

• Mantenere .env adiacente a dab-config.json (o ovunque il tuo processo di avvio lo richieda).
• Aggiunta di .env a .gitignore.
• Le righe vuote e le righe che iniziano con # (se supportato, verifica) vengono generalmente ignorate; confermare il supporto dei commenti prima di documentare.
• In Linux/macOS i nomi fanno distinzione tra maiuscole e minuscole. In Windows, effettivamente non fanno distinzione tra maiuscole e minuscole.

Uso @env() nella configurazione

Sostituzione di base

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

Combinato con @akv()

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

Parametri della stored procedure

{
  "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" ] }
      ]
    }
  }
}

I valori di ambiente vengono sostituiti come stringhe. L'analisi successiva, ad esempio int o bool, viene gestita dalla logica di runtime o configurazione di utilizzo.

Risoluzione dei problemi

Scenario	Risultato
Variabile trovata	La sostituzione ha esito positivo.
Variabile assente	Probabilmente il caricamento della configurazione fallisce.
Variabile non trovata	Sostituito con una stringa vuota.
Multiplo @env() in proprietà diverse	Tutti risolti in modo indipendente.
Usato dove è previsto un valore numerico o booleano.	Valore sostituito come stringa; l'analisi può avere esito positivo.
Modello non valido (ad esempio @env(DB_VAR) virgolette mancanti)	Considerato come stringa letterale.

Esempio 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

Non eseguire il commit .env di file contenenti segreti. |

Riferimento rapido

Elemento	Riassunto
Sintassi	@env('variable-name')
File di simulazione	.env con name=value linee
Combinazione con @env()	Supportato.

Review

Usare @env() per mantenere i segreti e i valori specifici dell'ambiente fuori dai file di configurazione. Associarlo a una gestione dei segreti disciplinata, ad esempio archivi variabili CI/CD o definizioni di contenitori, per una distribuzione sicura e flessibile. Per l'utilizzo della cassaforte aziendale, combinare con la @akv() funzione per centralizzare le informazioni riservate.