Использование токенов в шагах задания

Область применения: SQL Server Управляемый экземпляр SQL Azure

Агент SQL Server позволяет применять токены в скриптах шагов заданий на языке Transact-SQL. Применение токенов при написании шагов заданий обеспечивают такую же гибкость, какую дают переменные при написании программ. Если вы добавите токен в скрипт шага задания, агент SQL Server будет заменять его нужным значением во время выполнения, до передачи на выполнение подсистеме Transact-SQL.

Общие сведения об использовании маркеров

агент 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

Экранирующие макросы агента SQL Server

Обновление шагов задания для использования макросов

В следующей таблице описывается обработка замены маркеров агент SQL Server. Чтобы включить или отключить замену токенов предупреждений, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойстваи на странице Система предупреждений установите или снимите флажок Заменить токены всех ответов заданий на предупреждения .

Примеры обновления синтаксиса токенов

Ниже приведены примеры синтаксиса маркеров, которые помогут проиллюстрировать использование этих команд.

А. Использование маркеров в не вложенных строках

В следующем примере показано, как обновить простой скрипт без вложенных строк соответствующим управляющим маркером. До выполнения обновляющего скрипта следующий скрипт шага задания использует токен шага задания, чтобы напечатать соответствующее имя базы данных:

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;

C. Использование маркеров с макросом ESCAPE_NONE

Следующий пример является частью скрипта, который извлекает job_id из таблицы sysjobs и использует маркер JOBID для заполнения @JobID переменной, которая была объявлена ранее в скрипте как двоичный тип данных.

DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))

Это напрямую назначает значение маркера JOBID @JobID, устраняя ненужные запросы базы данных и неявные преобразования, устраняя проблемы, возникающие в разделе C.

См. также

• Реализация заданий
• Управление шагами задания