Uso @env() para la sustitución de variables de entorno en Data API Builder

Data API Builder (DAB) permite mantener los secretos (por ejemplo, cadenas de conexión de base de datos) fuera de dab-config.json sustituyendo los valores en el momento de la carga. El primer mecanismo admitido es la función @env(), que resuelve las variables de entorno del entorno del proceso host o de un archivo local .env.

Vea también: the @akv() function.

¿Qué hace?@env()

Coloque una referencia a una variable de entorno en cualquier lugar donde se espera un valor de cadena:

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

En el momento de carga de configuración, DAB examina los valores de cadena del patrón @env('VAR_NAME') y reemplaza el token por el valor de la variable de entorno VAR_NAME.

Orígenes de valores

Fuente	Description
Entorno de sistema operativo o proceso	Las variables de entorno estándar que están presentes cuando el proceso DAB se inicia.
Archivo .env	Un archivo de texto plano con NAME=VALUE líneas en el directorio de configuración (para facilitar el desarrollo local).

Nota:

El .env archivo invalida las variables de entorno de proceso o sistema existentes cuando ambas definen el mismo nombre. Si proporciona un archivo local .env para el desarrollo, sus entradas se usan para satisfacer consultas de @env('var-name' sin realizar una llamada al entorno local.

Archivo .env de ejemplo:

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

Directrices:

• Mantenga .env adyacente a dab-config.json (o donde el proceso de inicio lo espere).
• Agregue .env a .gitignore.
• Las líneas en blanco y las líneas que comienzan por # (si se admiten, verifíquelo) suelen omitirse; confirme antes de documentar el soporte de comentarios.
• En Linux/macOS, los nombres distinguen mayúsculas de minúsculas. En Windows, prácticamente no distinguen entre mayúsculas y minúsculas.

Uso de @env() en la configuración

Sustitución básica

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

Combinado con @akv()

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

Parámetros de procedimiento almacenado

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

Los valores de entorno se sustituyen como cadenas. El análisis posterior (por ejemplo, para int o bool) se controla mediante la configuración de consumo o la lógica en tiempo de ejecución.

Solución de problemas

Scenario	Resultado
Variable encontrada	La sustitución tuvo éxito.
Variable ausente	Es probable que se produzca un error en la carga de configuración.
Variable no encontrada	Sustituido por cadena vacía
Múltiplo @env() en propiedades diferentes	Todo resuelto de forma independiente.
Se usa donde se esperaban valores numéricos o bool	Valor sustituido como cadena de texto; el análisis puede tener éxito.
Patrón no válido (por ejemplo @env(DB_VAR) , faltan comillas)	Se trata como una cadena de texto literal.

Ejemplo 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

No suba .env archivos que contengan secretos. |

Referencia rápida

Elemento	Resumen
Syntax	@env('variable-name')
Archivo de simulación	.env con name=value líneas
Mezcla con @env()	Supported.

Revisión

Use @env() para mantener los secretos y los valores específicos del entorno fuera de los archivos de configuración. Combínalo con una administración de secretos disciplinada, como repositorios de variables de CI/CD o configuraciones de contenedores, para una implementación segura y flexible. Para uso del almacén empresarial, combine con la @akv() función para centralizar secretos.