Использование токенов в шагах задания
Агент SQL Server позволяет применять токены в скриптах шагов заданий на языке Transact-SQL. Применение токенов при написании шагов заданий обеспечивают такую же гибкость, какую дают переменные при написании программ. После добавления токена в сценарий шага задания агент SQL Server замещает токен во время выполнения, до того как шаг задания выполняется подсистемой Transact-SQL
.gif "Важное примечание") Важно! |
|---|
Начиная с SQL Server 2005 с пакетом обновления 1 (SP1), синтаксис токена шага задания агента SQL Server был изменен. В результате управляющий макрос должен сопровождать все токены, используемые в шагах заданий, иначе произойдет сбой в шагах заданий. Использование управляющих макросов и обновление шагов заданий агента SQL Server, в которых используются токены, описывается в разделах «Основные сведения об использовании токенов», «Макросы и токены агента SQL Server» и «Обновление шагов заданий для использования маркеров». Кроме того, также изменился синтаксис SQL Server 2000, при котором для обнаружения токенов шагов заданий SQL Server (например «[DATE]») использовались квадратные скобки. Теперь имена токенов необходимо заключать в круглые скобки и в начале записи токена добавлять знак доллара ($). Например: $(ESCAPE_имя макроса(DATE)) |
Основные сведения об использовании токенов
.gif "Примечание по безопасности") Примечание по безопасности |
|---|
Все пользователи Windows с разрешением на запись в журнал событий Windows могут получить доступ к шагам заданий, которые активируются предупреждениями агента SQL Server или предупреждениями инструментария WMI. Чтобы избежать этого нарушения безопасности, SQL Server токены агента, которые могут использоваться в заданиях, активированных предупреждениями, по умолчанию отключены. Такими токенами являются A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property). Если необходимо использовать эти токены, убедитесь, что только члены доверенных групп безопасности Windows, таких как группа «Администраторы», обладают разрешением на работу с журналом событий компьютера, на котором находится SQL Server. Затем, чтобы включить эти токены, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойства и на странице Система предупреждений выберите Заменять токены всех ответов заданий на предупреждения. |
Замена токенов агента SQL Server проста и эффективна: Агент SQL Server заменяет токен точной символьной строкой. Все токены обрабатываются с учетом регистра. Шаги заданий должны это учитывать для учетной записи и правильно заключать в кавычки применяемые токены или преобразовывать замещающие строки к верному типу данных.
Например, чтобы напечатать имя базы данных в шаге задания, можно использовать следующую инструкцию:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
В этом примере макрос ESCAPE_SQUOTE добавляется с токеном A-DBN. Во время выполнения токен A-DBN будет замещен соответствующим именем базы данных. Управляющий макрос экранирует все одиночные кавычки, которые случайно передаются в строку замещения токена. Агент SQL Server заместит символ одиночной кавычки двумя символами одиночной кавычки в конечной строке.
Например, если замещающая токен строка AdventureWorks2008R2'SELECT @@VERSION --, то команда, выполняемая агентом SQL Server имеет вид:
PRINT N'Current database name is AdventureWorks2008R2''SELECT @@VERSION --' ;
В этом случае добавленная инструкция SELECT @@VERSION не выполняется. Вместо этого, дополнительный символ одинарной кавычки заставляет сервер анализировать передаваемую инструкцию как строку. Если замещающая токен строка не содержит одинарных кавычек, то никакие символы не экранируются, и шаг задания, содержащий маркер, выполняется как планировалось.
Чтобы отладить использование токенов в шагах заданий, используйте инструкции вывода на печать, такие как PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' и сохраняйте выходные данные шага задания в файл или таблицу. Используйте страницу Дополнительно диалогового окна Свойства шага задания для указания выходного файла или таблицы для шага задания.
Токены и макросы агента SQL Server
В следующей таблице перечислены и описаны токены и макросы, которые поддерживает агент SQL Server.
Токены агента SQL Server
Токен |
Описание |
|---|---|
(A-DBN) |
Имя базы данных. Если задание запускается в результате предупреждения, то имя базы данных автоматически замещает в шаге задания этот токен. |
(A-SVR) |
Имя сервера. Если задание запускается в результате предупреждения, то имя сервера автоматически замещает в шаге задания этот токен. |
(A-ERR) |
Номер ошибки. Если задание запускается в результате предупреждения, то номер ошибки автоматически замещает в шаге задания этот токен. |
(A-SEV) |
Серьезность ошибки. Если задание запускается в результате предупреждения, то степень серьезности ошибки автоматически замещает в шаге задания этот токен. |
(A-MSG) |
Текст сообщения. Если задание запускается в результате предупреждения, то текст сообщения автоматически замещает в шаге задания этот токен. |
(DATE) |
Текущая дата (в формате ГГГГММДД). |
(INST) |
Имя экземпляра. Для экземпляра по умолчанию этот токен будет иметь имя экземпляра по умолчанию MSSQLSERVER. |
(JOBID) |
Идентификатор задания. |
(MACH) |
Имя компьютера. |
(MSSA) |
Имя главной службы SQLServerAgent. |
(OSCMD) |
Префикс для программы, используемой для запуска шагов задания CmdExec. |
(SQLDIR) |
Каталог, в котором установлен SQL Server. Значение по умолчанию — «C:\Program Files\Microsoft SQL Server\MSSQL». |
(STEPCT) |
Количество выполнений этого шага (кроме повторных попыток). Может применяться командой шага для принудительного прекращения цикла из нескольких шагов. |
(STEPID) |
Идентификатор шага. |
(SRVR) |
Имя компьютера, на котором работает SQL Server. В случае именованного экземпляра SQL Server имя компьютера включается в имя экземпляра. |
(TIME) |
Текущее время (в формате ЧЧММСС). |
(STRTTM) |
Время запуска задания (в формате ЧЧММСС). |
(STRTDT) |
Дата запуска задания (в формате ГГГГММДД). |
(WMI(property)) |
Для заданий, запускаемых в ответ на предупреждение инструментария WMI, значение свойства указывается параметром property. Например, маркер $(WMI(DatabaseName)) предоставляет значение для свойства DatabaseName в событии инструментария WMI, которое вызвало предупреждение. |
Экранирующие макросы агента SQL Server
Экранирующие макросы |
Описание |
|---|---|
$(ESCAPE_SQUOTE(имя_токена)) |
Экранирует символы одинарных кавычек (') в строке замещения токена. Замещает символ одинарной кавычки двумя символами одинарной кавычки. |
$(ESCAPE_DQUOTE(имя_токена)) |
Экранирует символы двойных кавычек (") в строке замещения токена. Замещает символ двойных кавычек двумя символами двойных кавычек. |
$(ESCAPE_RBRACKET(имя_токена)) |
Экранирует символы правой квадратной скобки (]) в строке замещения токена. Замещает один символ правой квадратной скобки двумя символами правой квадратной скобки. |
$(ESCAPE_NONE(имя_токена)) |
Замещает токен, не экранируя никакие символы строки. Этот макрос предоставлен для поддержки обратной совместимости в окружениях, где строки замещения токена ожидаются только от надежных пользователей. Дополнительные сведения см. в подразделе «Обновление шагов заданий для использования маркеров» далее в этом разделе. |
Обновление шагов заданий для использования маркеров
Начиная с версии SQL Server 2005 с пакетом обновления 1 (SP1), шаги заданий, содержащие токены без экранирующих макросов, завершаются сбоем и возвращают сообщение об ошибке; это сообщение указывает на то, что шаг задания содержит токены, обновление которых при помощи макроса необходимо перед тем, как задание можно будет выполнить.
Сценарий см. в статье базы знаний Microsoft 915845: SQL Server Agent Job Steps That Use Tokens Fail in SQL Server 2005 Service Pack 1. С помощью этого сценария можно обновить все шаги задания, использующие токены с макросом ESCAPE_NONE. После применения этого сценария рекомендуется как можно скорее просмотреть шаги заданий, в которых используются токены, и заменить макрос ESCAPE_NONE экранирующим макросом, который соответствует контексту шага задания.
Следующая таблица показывает, каким образом замена токенов обрабатывается агентом SQL Server. Чтобы включить или отключить замену токенов предупреждений, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойства и на странице Система предупреждений установите или снимите флажок Заменить токены всех ответов заданий на предупреждения.
Синтаксис токена |
Предупреждение о замене токенов включено |
Предупреждение о замене токенов отключено |
|---|---|---|
Управляющие макросы используются |
Все токены в заданиях заменяются успешно. |
Токены, активированные предупреждениями, не заменяются. К этим токенам относятся A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property). Другие статические токены заменяются успешно. |
Управляющие макросы не используются |
Все задания, содержащие токены, завершаются сбоем. |
Все задания, содержащие токены, завершаются сбоем. |
Примеры обновления синтаксиса токенов
А. Использование токенов в невложенных строках
В следующем примере показано, как обновить простой сценарий без вложенных строк соответствующим управляющим маркером. До выполнения обновляющего сценария следующий сценарий шага задания использует токен шага задания, чтобы напечатать соответствующее имя базы данных:
PRINT N'Current database name is $(A-DBN)' ;
После выполнения обновляющего сценария макрос ESCAPE_NONE добавляется перед токеном A-DBN. Так как для отделения строки печати используются одинарные кавычки, необходимо обновить шаг задания, добавив макрос ESCAPE_SQUOTE следующим образом:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
Б. Использование токенов во вложенных строках
В сценариях шагов заданий, где токены используются во вложенных строках или инструкциях, перед добавлением соответствующих управляющих токенов следует переписать вложенные инструкции в виде нескольких инструкций.
Например, рассмотрим следующий шаг задания, в котором используется токен A-MSG и который не был обновлен с помощью управляющего макроса:
PRINT N'Print ''$(A-MSG)''' ;
После выполнения обновляющего сценария макрос ESCAPE_NONE добавляется с токеном. Однако, в этом случае необходимо переписать сценарий, чтобы не использовалось вложение, как показано ниже, и добавить макрос ESCAPE_SQUOTE, чтобы правильным образом экранировать разделители, которые могут быть переданы в строку замены токена:
DECLARE @msgString nvarchar(max)
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))'
SET @msgString = QUOTENAME(@msgString,'''')
PRINT N'Print ' + @msgString ;
Имейте в виду, что функция QUOTENAME устанавливает символ кавычки.
В. Использование токенов с макросом ESCAPE_NONE
Следующий пример является частью сценария, который извлекает job_id из таблицы sysjobs и использует токен JOBID, чтобы заполнить переменную @JobID, которая была объявлена как бинарный тип данных ранее в сценарии. Имейте в виду, что с токеном JOBID используется макрос ESCAPE_NONE, так как для бинарного типа данных разделители не требуются. После выполнения сценария обновления не нужно обновлять этот шаг задания.
SELECT * FROM msdb.dbo.sysjobs
WHERE @JobID = CONVERT(uniqueidentifier, $(ESCAPE_NONE(JOBID))) ;