Zmienna środowiskowa w zadaniu

Zmienna środowiskowa w zadaniu przekazuje wartość konfiguracyjną do kroku wykonywanego przez SQL Server Agent.

Rola zmiennej środowiskowej w kroku SQL Server Agent

Zmienna środowiskowa w zadaniu SQL Server Agent jest wartością tekstową udostępnianą procesowi uruchamianemu przez krok zadania. Może przechowywać na przykład ścieżkę katalogu roboczego, nazwę środowiska, identyfikator instancji albo lokalizację pliku używanego przez skrypt. Sama zmienna nie wykonuje żadnej operacji na bazie danych. Dostarcza jedynie parametr, który może zostać odczytany przez program lub skrypt uruchomiony w ramach danego kroku.

W SQL Server Agent trzeba odróżnić zmienną systemu Windows od mechanizmu tokenów SQL Server Agent. Zmienna środowiskowa jest elementem środowiska procesu, natomiast token, taki jak $(ESCAPE_SQUOTE(A-DBN)), jest podstawiany przez SQL Server Agent podczas przygotowywania polecenia zadania. Są to dwa niezależne mechanizmy i nie należy stosować ich zamiennie. Zmienna środowiskowa może być używana przez krok typu CmdExec lub PowerShell, a tokeny służą do przekazywania informacji dostępnych w kontekście zadania, na przykład nazwy bazy albo daty uruchomienia.

Dziedziczenie wartości przez proces SQL Server Agent

Wartość zmiennej środowiskowej dostępna w kroku zależy od środowiska procesu SQL Server Agent. W systemie Windows usługa SQL Server Agent działa jako konkretny proces i otrzymuje zestaw zmiennych środowiskowych podczas uruchamiania. Jeżeli zmienna zostanie dodana lub zmieniona w systemie po starcie usługi, działająca instancja agenta może nadal używać poprzedniego zestawu wartości. Z tego powodu po zmianie konfiguracji środowiska konieczne jest uwzględnienie ponownego uruchomienia usługi SQL Server Agent zgodnie z zasadami obowiązującymi w danym środowisku.

Wartość nie jest automatycznie izolowana dla jednego zadania. Jeżeli kilka kroków lub zadań uruchamia procesy w tym samym środowisku usługowym, mogą odczytywać tę samą zmienną. Nie oznacza to jednak, że zmiana wykonana w jednym procesie musi zmienić środowisko innych procesów. Proces potomny dziedziczy środowisko procesu nadrzędnego, ale modyfikacja zmiennej w uruchomionym skrypcie zwykle obowiązuje tylko ten proces oraz jego potomków. Należy również uwzględnić konto, pod którym wykonywany jest krok, ponieważ jego profil, uprawnienia i dostęp do zasobów mogą różnić się od środowiska interaktywnego użytkownika.

Odczyt zmiennej w CmdExec, PowerShell i Transact-SQL

Dla kroku typu Operating system (CmdExec) zmienna środowiskowa jest odczytywana składnią powłoki Windows, na przykład %NAZWA_ZMIENNEJ%. Dla kroku PowerShell używa się składni $env:NAZWA_ZMIENNEJ. Jeżeli zmienna nie istnieje, skrypt może otrzymać pustą wartość albo zachowanie zależne od dalszej logiki polecenia. Dlatego skrypt powinien jawnie sprawdzić, czy wartość została przekazana, i zakończyć się kontrolowanym błędem, gdy brak konfiguracji uniemożliwia bezpieczne wykonanie operacji.

Krok typu Transact-SQL nie udostępnia zmiennych środowiskowych jako zwykłych zmiennych języka T-SQL. Nie można więc traktować wartości systemowej tak samo jak parametru procedury składowanej lub zmiennej zadeklarowanej przez DECLARE. Pośredni odczyt może wymagać uruchomienia polecenia systemowego, dodatkowego komponentu albo przekazania wartości inną, jawnie zaprojektowaną drogą. Takie rozwiązanie należy oceniać pod kątem uprawnień, obsługi znaków specjalnych, rejestrowania wartości i ryzyka ujawnienia danych konfiguracyjnych.

Przy budowaniu polecenia trzeba pamiętać o różnicy między rozwinięciem zmiennej przez powłokę a podstawieniem tokenu przez agenta. Zapis %NAZWA_ZMIENNEJ% zostanie zinterpretowany przez Cmd.exe, natomiast składnia PowerShell nie zadziała w kroku CmdExec bez uruchomienia właściwego interpretera. Analogicznie token SQL Server Agent musi być dozwolony dla danego typu kroku i poprawnie zabezpieczony funkcją ESCAPE_, jeżeli jego wartość trafia do polecenia lub skryptu.

Kontrola konfiguracji i diagnostyka nieprawidłowej wartości

Gdy zadanie działa ręcznie, lecz kończy się błędem uruchomione przez SQL Server Agent, pierwszym punktem kontroli jest rzeczywiste środowisko procesu agenta. Należy sprawdzić nazwę zmiennej, jej pisownię, sposób rozwinięcia oraz to, czy usługa została uruchomiona po ustawieniu wartości. Trzeba także porównać konto używane przez krok z kontem używanym podczas testu interaktywnego. Różnica może dotyczyć dostępu do katalogu, udziału sieciowego, programu zewnętrznego albo profilu PowerShell.

Skrypt diagnostyczny powinien zapisywać informację o obecności zmiennej i bezpiecznie maskować jej zawartość, jeżeli może zawierać hasło, klucz lub inny sekret. Nie należy umieszczać poufnej wartości bezpośrednio w treści zadania, historii polecenia ani komunikacie błędu. W przypadku ścieżek warto sprawdzić także cudzysłowy, znaki końca linii i różnicę między ścieżką lokalną a ścieżką widoczną dla konta usługi. Sama poprawna nazwa zmiennej nie gwarantuje, że wskazywany zasób istnieje lub jest dostępny.

Podczas analizy należy rozdzielić błąd przekazania konfiguracji od błędu działania programu. Brak zmiennej, pusta wartość i nieprawidłowa ścieżka to trzy różne przypadki, które powinny prowadzić do odrębnych komunikatów oraz kodów zakończenia. Pomocne są historia zadania SQL Server Agent, dziennik SQL Server Agent i logi programu uruchamianego przez krok. Taka diagnostyka pozwala ustalić, czy problem powstał przy dziedziczeniu środowiska, podstawieniu wartości, uprawnieniach konta, czy dopiero podczas wykonywania właściwej operacji.