Używanie @env() do zastępowania zmiennych środowiskowych w konstruktorze interfejsu API danych

Konstruktor interfejsu API danych (DAB) umożliwia przechowywanie tajnych danych (na przykład parametrów połączenia bazy danych) poza dab-config.json poprzez zastępowanie wartościami podczas ładowania. Pierwszy obsługiwany mechanizm to @env() funkcja, która odczytuje zmienne środowiskowe ze środowiska procesu hosta lub lokalnego pliku .env.

Zobacz również: the @akv() function.

Co @env() robi

Umieść odwołanie do zmiennej środowiskowej w dowolnym miejscu, w jakim oczekiwano wartości ciągu:

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

W czasie ładowania konfiguracji usługa DAB skanuje wartości ciągów pod kątem wzorca @env('VAR_NAME') i zastępuje token wartością zmiennej środowiskowej VAR_NAME.

Źródła wartości

Źródło	Description
System operacyjny/środowisko przetwarzania	Standardowe zmienne środowiskowe obecne podczas uruchamiania procesu DAB.
Plik .env	Plik w postaci zwykłego tekstu z wierszami NAME=VALUE w katalogu konfiguracji (dla lokalnej wygody rozwoju).

Uwaga / Notatka

Plik .env zastępuje istniejące zmienne środowiskowe procesu/systemu podczas definiowania tej samej nazwy. Jeśli podasz plik lokalny .env do programowania, jego wpisy będą używane do spełnienia @env(wyszukiwania "var-name" bez wywoływania środowiska lokalnego.

Przykładowy .env plik:

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

Wytyczne:

• Zachowaj .env obok dab-config.json (lub wszędzie tam, gdzie oczekuje się procesu uruchamiania).
• Dodaj .env do .gitignore.
• Puste wiersze i wiersze rozpoczynające się od # (jeśli są obsługiwane, należy to zweryfikować) są zwykle ignorowane; upewnij się przed dokumentowaniem obsługi komentarzy.
• W systemach Linux i macOS rozróżniana jest wielkość liter w nazwach. W systemie Windows są one zasadniczo niewrażliwe na wielkość liter.

Używanie @env() w konfiguracji

Podstawowe podstawienie

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

Połączone z @akv()

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

Parametry procedury składowanej

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

Wartości środowiska są zastępowane ciągami. Kolejne analizowanie (na przykład do typu int lub bool) jest obsługiwane przez logikę przetwarzania konfiguracji lub logikę wykonawczą.

Rozwiązywanie problemów

Scenario	Outcome
Znaleziono zmienną	Podstawianie kończy się powodzeniem.
Zmienna nieobecna	Prawdopodobnie ładowanie konfiguracji kończy się niepowodzeniem.
Nie można odnaleźć zmiennej	Podstawione jako pusty ciąg.
Wiele @env() w różnych właściwościach	Wszystkie rozwiązane niezależnie.
Używane tam, gdzie oczekiwano wartości liczbowej lub boolean.	Wartość zamieniona na ciąg znaków; analiza może zakończyć się powodzeniem.
Nieprawidłowy wzorzec (na przykład @env(DB_VAR) brak cudzysłowów)	Traktowane jako ciąg literału.

Pełny przykład

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

Ważne

Nie zatwierdzaj .env plików zawierających tajne dane. |

Krótki przewodnik

Produkt	Podsumowanie
Składnia	@env('variable-name')
Plik symulacji	.env z liniami name=value
Mieszanie z @env()	Supported.

Wykonaj przegląd

Użyj @env() do trzymania wpisów tajnych i wartości specyficznych dla środowiska poza plikami konfiguracji. Połącz je z zdyscyplinowanym zarządzaniem tajnymi danymi, takimi jak repozytoria zmiennych CI/CD lub komponenty kontenerów, aby zapewnić bezpieczne i elastyczne wdrożenie. W przypadku użycia magazynu przedsiębiorstwa użyj funkcji @akv(), aby scentralizować tajne dane.