Используйте @env() для подстановки переменных среды в построителе API данных

Построитель API данных (DAB) позволяет держать секреты (например, строки подключения к базе данных) вне dab-config.json путем замены значений во время загрузки. Первый поддерживаемый механизм — это @env() функция, которая разрешает переменные окружения из окружения процесса хоста или локального .env файла.

См. также: the @akv() function

Что @env() делает

Поместите ссылку на переменную среды в любом месте, где ожидается строковое значение:

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

Во время загрузки конфигурации DAB сканирует строковые значения @env('VAR_NAME') шаблона и заменяет маркер значением переменной VAR_NAMEсреды.

Источники значений

Исходный материал Description
ОС или среда обработки Стандартные переменные среды присутствуют при запуске процесса DAB.
Файл .env Файл с открытым текстом со строками NAME=VALUE в каталоге конфигурации (для удобства локальной разработки).

Замечание

Файл .env переопределяет существующие переменные среды процесса или системы, когда оба определяют одно и то же имя. Если вы предоставляете локальный .env файл для разработки, его записи используются для поиска @env( var-name, не вызывая локальную среду.

Пример файла .env:

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

Руководящие принципы:

  • Держите .env рядом с dab-config.json (или там, где это ожидает процесс запуска).
  • Добавьте .env в .gitignore.
  • Пустые строки и строки, начинающиеся с # (если поддерживается, проверьте), обычно игнорируются; необходимо подтвердить их поддержку перед документированием.
  • В Linux или macOS имена чувствительны к регистру. В Windows регистр фактически не учитывается.

Использование @env() в конфигурации

Базовая подстановка

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

В сочетании с @akv()

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

Параметры хранимой процедуры

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

Значения среды заменяются строками. Последующий синтаксический анализ (например, в int или bool) обрабатывается с помощью потребляемой конфигурации или логики выполнения.

Устранение неполадок

Scenario Результат
Найденная переменная Замена удалась.
Переменная отсутствует Скорее всего, загрузка конфигурации завершается ошибкой.
Переменная не найдена Заменена пустой строкой.
Несколько @env() в разных свойствах Все проблемы решены независимо.
Используется, где ожидается числовое или логическое значение Значение преобразовано в строку; синтаксический анализ может пройти успешно.
Недопустимый шаблон (например @env(DB_VAR) , отсутствующие кавычки) Рассматривается как литеральная строка.

Полный пример

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!;

Это важно

Не коммитьте .env файлы, содержащие секретные данные. |

Краткий справочник

Item Сводка
Синтаксис @env('variable-name')
Файл моделирования .envсо строками name=value
Сочетание с @env() Supported.

Отзыв

Используется @env() для хранения секретов и значений, относящихся к среде, вне файлов конфигурации. Совместите это с упорядоченным управлением секретами, такими как хранилища переменных CI/CD или конфигурации контейнеров, для безопасного и гибкого развертывания. Для использования корпоративного хранилища секретов объедините его с функцией для централизации данных.

  • Last updated on