Использование токенов в шагах задания
Область применения:
SQL Server Управляемый экземпляр SQL Azure
Внимание
В Управляемом экземпляре Azure SQL в настоящее время поддерживается большинство функций агента SQL Server (но не все). Подробные сведения см. в статье Различия в T-SQL между Управляемым экземпляром SQL Azure и SQL Server.
Агент SQL Server позволяет применять токены в скриптах шагов заданий на языке Transact-SQL. Применение токенов при написании шагов заданий обеспечивают такую же гибкость, какую дают переменные при написании программ. Если вы добавите токен в скрипт шага задания, агент SQL Server будет заменять его нужным значением во время выполнения, до передачи на выполнение подсистеме Transact-SQL.
Общие сведения об использовании маркеров
Внимание
Любой пользователь 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 заменяет одну кавычку двумя одними кавычками в конечной строке.
Например, если строка, переданная для замены маркера, будет AdventureWorks2022'SELECT @@VERSION --выполнена команда, выполненная на шаге задания агент SQL Server:
PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;
В этом случае вставленная инструкция SELECT @@VERSIONне выполняется. Вместо этого, дополнительный символ одинарной кавычки заставляет сервер анализировать передаваемую инструкцию как строку. Если строка замены маркера не содержит один кавычки, символы не экранируются, а шаг задания, содержащий маркер, выполняется должным образом.
Чтобы отладить использование токенов в шагах заданий, используйте инструкции вывода на печать, такие как PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' и сохраняйте выходные данные шага задания в файл или таблицу. Используйте страницу Дополнительно диалогового окна Свойства шага задания , чтобы указать выходной файл или таблицу для шага задания.
Токены и макросы агента SQL Server
В следующих таблицах перечислены маркеры и макросы, которые агент SQL Server поддерживаются.
Токены агента SQL Server
| Маркер | Description |
|---|---|
| (A-DBN) | имя базы данных. Если задание запускается в результате предупреждения, то имя базы данных автоматически замещает в шаге задания этот токен. |
| (A-SVR) | Имя сервера. Если задание запускается в результате предупреждения, то имя сервера автоматически замещает в шаге задания этот токен. |
| (A-ERR) | Номер ошибки. Если задание запускается в результате предупреждения, то номер ошибки автоматически замещает в шаге задания этот токен. |
| (A-SEV) | Серьезность ошибки. Если задание запускается в результате предупреждения, то степень серьезности ошибки автоматически замещает в шаге задания этот токен. |
| (A-MSG) | Текст сообщения. Если задание запускается в результате предупреждения, то текст сообщения автоматически замещает в шаге задания этот токен. |
| (JOBNAME) | Имя задания. Этот токен доступен только в SQL Server 2016 и более поздних версиях. |
| (STEPNAME) | Имя шага этапа. Этот токен доступен только в SQL Server 2016 и более поздних версиях. |
| (DATE) | Текущая дата (в формате ГГГГММДД). |
| (INST) | Имя экземпляра. Для экземпляра по умолчанию этот маркер имеет имя экземпляра по умолчанию: MSSQLSERVER. |
| (JOBID) | Идентификатор задания. |
| (MACH) | Имя компьютера. |
| (MSSA) | Имя главной службы SQLServerAgent. |
| (OSCMD) | Префикс для программы, используемой для запуска шагов задания CmdExec . |
| (SQLDIR) | Каталог, в котором установлен SQL Server. Значение по умолчанию — «C:\Program Files\Microsoft SQL Server\MSSQL». |
| (SQLLOGDIR) | Токен замены для пути к папке журнала ошибок SQL Server, например $(ESCAPE_SQUOTE(SQLLOGDIR)). Этот токен доступен только в SQL Server 2014 и более поздних версиях. |
| (STEPCT) | Количество выполнений этого шага (кроме повторных попыток). Может применяться командой шага для принудительного прекращения цикла из нескольких шагов. |
| (STEPID) | Идентификатор шага. |
| (SRVR) | Имя компьютера под управлением SQL Server. Если экземпляр SQL Server является именованным экземпляром, это включает имя экземпляра. |
| (TIME) | Текущее время (в формате ЧЧММСС). |
| (STRTTM) | Время запуска задания (в формате ЧЧММСС). |
| (STRTDT) | Дата запуска задания (в формате ГГГГММДД). |
| (WMI(свойство)) | Для заданий, запускаемых в ответ на предупреждение инструментария WMI, значение свойства указывается параметром свойство. Например, маркер $(WMI(DatabaseName)) предоставляет значение для свойства DatabaseName в событии инструментария WMI, которое вызвало предупреждение. |
Экранирующие макросы агента SQL Server
| Экранирующие макросы | Description |
|---|---|
| $(ESCAPE_SQUOTE(имя_токена)) | Экранирует символы одинарных кавычек (') в строке замещения токена. Замещает символ одинарной кавычки двумя символами одинарной кавычки. |
| $(ESCAPE_DQUOTE(имя_токена)) | Экранирует символы двойных кавычек (") в строке замещения токена. Замещает символ двойных кавычек двумя символами двойных кавычек. |
| $(ESCAPE_RBRACKET(имя_токена)) | Экранирует символы правой квадратной скобки (]) в строке замещения токена. Замещает один символ правой квадратной скобки двумя символами правой квадратной скобки. |
| $(ESCAPE_NONE(имя_токена)) | Замещает токен, не экранируя никакие символы строки. Этот макрос предоставлен для поддержки обратной совместимости в окружениях, где строки замещения токена ожидаются только от надежных пользователей. Дополнительные сведения см. в подразделе «Обновление шагов заданий для использования маркеров» далее в этом разделе. |
Обновление шагов задания для использования макросов
В следующей таблице описывается обработка замены маркеров агент SQL Server. Чтобы включить или отключить замену токенов предупреждений, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойстваи на странице Система предупреждений установите или снимите флажок Заменить токены всех ответов заданий на предупреждения .
| Синтаксис токена | Предупреждение о замене токенов включено | Предупреждение о замене токенов отключено |
|---|---|---|
| Управляющие макросы используются | Все токены в заданиях заменяются успешно. | Маркеры, активированные оповещениями, не заменяются. К этим токенам относятся: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGи WMI(свойство). Другие статические токены заменяются успешно. |
| Управляющие макросы не используются | Все задания, содержащие токены, завершаются сбоем. | Все задания, содержащие токены, завершаются сбоем. |
Примеры обновления синтаксиса токенов
Ниже приведены примеры синтаксиса маркеров, которые помогут проиллюстрировать использование этих команд.
А. Использование маркеров в не вложенных строках
В следующем примере показано, как обновить простой скрипт без вложенных строк соответствующим управляющим маркером. До выполнения обновляющего скрипта следующий скрипт шага задания использует токен шага задания, чтобы напечатать соответствующее имя базы данных:
PRINT N'Current database name is $(A-DBN)' ;
После выполнения обновляющего скрипта макрос ESCAPE_NONE добавляется перед токеном A-DBN . Так как для отделения строки печати используются одинарные кавычки, необходимо обновить шаг задания, добавив макрос ESCAPE_SQUOTE следующим образом:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B. Использование маркеров в вложенных строках
В скриптах шагов заданий, где токены используются во вложенных строках или инструкциях, перед добавлением соответствующих управляющих токенов следует переписать вложенные инструкции в виде нескольких инструкций.
Например, рассмотрим следующий шаг задания, который использует A-MSG маркер и не был обновлен с помощью escape-макроса:
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 переменной, которая была объявлена ранее в скрипте как двоичный тип данных.
Примечание.
Так как для двоичных типов данных не требуются разделители, макрос ESCAPE_NONE используется с маркером JOBID. После запуска скрипта обновления не потребуется обновить этот шаг задания.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
Это напрямую назначает значение маркера JOBID @JobID, устраняя ненужные запросы базы данных и неявные преобразования, устраняя проблемы, возникающие в разделе C.