Tokeny SQL Server Agent

Tokeny SQL Server Agent to wewnętrzne zmienne wykorzystywane w krokach zadań, np. do przekazywania nazwy bazy.

Rola tokenów w zadaniach SQL Server Agent

Tokeny SQL Server Agent są zmiennymi zastępczymi rozpoznawanymi przez usługę SQL Server Agent podczas wykonywania zadania. W definicji kroku zadania zapisuje się specjalny wzorzec, a agent przed uruchomieniem polecenia zastępuje go wartością wynikającą z bieżącego kontekstu wykonania. Dzięki temu jedno zadanie może działać dla różnych baz, serwerów, etapów lub identyfikatorów uruchomienia bez wpisywania tych danych na stałe w treści każdego kroku.

Tokeny mają składnię opartą na znaku dolara, nawiasie otwierającym i nazwie tokenu, na przykład $(ESCAPE_SQUOTE(A-DBN)). W tym przykładzie A-DBN oznacza nazwę bazy danych powiązaną z wywołującym alertem, a ESCAPE_SQUOTE jest makrem zabezpieczającym wartość przed użyciem w kontekście pojedynczych cudzysłowów. Token nie jest zmienną T-SQL dostępną bezpośrednio w każdej sesji. Jest elementem mechanizmu podmiany tekstu wykonywanej przez SQL Server Agent przed uruchomieniem kroku.

Tokeny dostępne w kontekście zadania i kroku

SQL Server Agent udostępnia tokeny opisujące zadanie, krok oraz środowisko wykonania. $(JOBID) identyfikuje zadanie, $(JOBNAME) zawiera jego nazwę, $(STEPID) wskazuje numer kroku, a $(STEPNAME) jego nazwę. Informacje o serwerze można pobierać za pomocą tokenu $(SRVR), natomiast $(MACH) odnosi się do nazwy komputera, na którym działa agent. W zależności od miejsca użycia dostępne są również tokeny związane z alertem, między innymi nazwa bazy danych, komunikat alertu, numer alertu i jego poziom.

Tokeny są użyteczne w poleceniach T-SQL, skryptach systemu operacyjnego, powiadomieniach i nazwach plików tworzonych przez krok zadania. Przykładowo polecenie może zapisać w tabeli audytowej nazwę zadania i numer kroku albo przekazać nazwę bazy do procedury składowanej. Tokeny alertów pozwalają przygotować ogólne zadanie reagujące na różne zdarzenia, lecz ich wartości są dostępne tylko wtedy, gdy zadanie rzeczywiście zostało uruchomione w kontekście obsługującym dany alert. Użycie tokenu niedostępnego w konkretnym wywołaniu może skutkować błędną podmianą albo niepoprawnym działaniem kroku.

Makra ESCAPE i bezpieczna podmiana wartości

Wartości tokenów mogą pochodzić z komunikatów alertów lub innych danych sterujących wykonaniem zadania, dlatego SQL Server Agent udostępnia makra ucieczki. ESCAPE_SQUOTE służy do wartości umieszczanych w tekście ograniczonym pojedynczym cudzysłowem, a ESCAPE_RBRACKET do wartości używanych w identyfikatorach ograniczonych nawiasami kwadratowymi. ESCAPE_NONE zwraca wartość bez dodatkowego mechanizmu ucieczki i powinno być stosowane wyłącznie wtedy, gdy format oraz źródło danych są kontrolowane i nie wymagają takiego zabezpieczenia.

Przykładowy fragment kroku T-SQL może wyglądać następująco: EXEC dbo.ZapiszUruchomienie @NazwaZadania = N'$(ESCAPE_SQUOTE(JOBNAME))', @NumerKroku = $(STEPID);. Wartość nazwy zadania jest wtedy przygotowana do użycia w literałach tekstowych, natomiast numer kroku jest wstawiany jako wartość liczbowa. W praktyce trzeba sprawdzić, czy po podmianie tokenu powstaje poprawna składnia T-SQL lub polecenia systemowego. Szczególnej uwagi wymagają tokeny umieszczane w nazwach plików, parametrach programów i poleceniach wywoływanych przez CmdExec, ponieważ nieprawidłowe znaki mogą zmienić znaczenie całego polecenia.

Weryfikacja konfiguracji i śladów wykonania zadania

Analizę problemu z tokenami należy rozpocząć od sprawdzenia typu kroku, treści polecenia, konta uruchamiającego zadanie oraz historii SQL Server Agent. W historii zadania warto porównać komunikat kroku z oczekiwaną wartością po podmianie. Pomocne jest także tymczasowe zapisanie użytych parametrów w kontrolowanym dzienniku technicznym, aby odróżnić błąd samego tokenu od błędu procedury, uprawnień, połączenia z bazą lub formatu argumentów. Nie należy zakładać, że token związany z alertem będzie miał wartość podczas ręcznego uruchomienia zadania z poziomu SQL Server Management Studio.

Przy zadaniach reagujących na alerty trzeba sprawdzić ustawienia zastępowania tokenów w SQL Server Agent oraz reguły zabezpieczeń dotyczące tokenów alertów. Po zmianie konfiguracji należy uruchomić kontrolowany test i zweryfikować zarówno treść wykonanej operacji, jak i historię zadania. Jeśli krok generuje skrypt lub plik, należy sprawdzić jego wynik po podmianie, a nie tylko samą definicję zadania. Błąd może wynikać z nieistniejącego tokenu, złego kontekstu uruchomienia, braku makra ESCAPE, niezgodności typu danych albo użycia wartości w niewłaściwym miejscu składni.