Статья
04/01/2012

sp_add_jobstep (Transact-SQL)

Добавляет шаг (операцию) к заданию.

Значок ссылки на раздел Синтаксические обозначения Transact-SQL

Синтаксис

        sp_add_jobstep [ @job_id = ] job_id | [ @job_name= ] 'job_name' 
     [ , [ @step_id = ] step_id ] 
     { , [ @step_name = ] 'step_name' } 
     [ , [ @subsystem = ] 'subsystem' ] 
     [ , [ @command = ] 'command' ] 
     [ , [ @additional_parameters = ] 'parameters' ] 
          [ , [ @cmdexec_success_code = ] code ] 
     [ , [ @on_success_action = ] success_action ] 
          [ , [ @on_success_step_id = ] success_step_id ] 
          [ , [ @on_fail_action = ] fail_action ] 
          [ , [ @on_fail_step_id = ] fail_step_id ] 
     [ , [ @server = ] 'server' ] 
     [ , [ @database_name = ] 'database' ] 
     [ , [ @database_user_name = ] 'user' ] 
     [ , [ @retry_attempts = ] retry_attempts ] 
     [ , [ @retry_interval = ] retry_interval ] 
     [ , [ @os_run_priority = ] run_priority ] 
     [ , [ @output_file_name = ] 'file_name' ] 
     [ , [ @flags = ] flags ] 
     [ , { [ @proxy_id = ] proxy_id 
         | [ @proxy_name = ] 'proxy_name' } ]

Аргументы

[ @job_id = ] job_id
Идентификационный номер задания, к которому добавляется этап. Аргумент job_id имеет тип uniqueidentifier и значение по умолчанию NULL.

[ @job_name = ] 'job_name'
Имя задания, к которому добавляется этап. Аргумент job_name имеет тип sysname и значение по умолчанию NULL.

Примечание
Необходимо указать либо аргумент job_id, либо аргумент job_name, но не оба аргумента одновременно.

[ @step_id = ] step_id
Порядковый идентификационный номер для шага задания. Идентификационные номера этапа начинаются с 1 и увеличиваются без разрывов. Если этап вставляется в существующую последовательность, порядковые номера меняются автоматически. Значение предоставляется в том случае, если не указан аргумент step_id. Аргумент step_id имеет тип int и значение по умолчанию NULL.
[ @step_name = ] 'step_name'
Имя этапа. Аргумент step_name имеет тип sysname и не имеет значения по умолчанию.

[ @subsystem = ] 'subsystem'
Подсистема, используемая службами агента SQL Server для выполнения command. subsystem имеет тип nvarchar(40) и может принимать одно из следующих значений.

Значение	Описание
'ACTIVESCRIPTING'	Активный скрипт. Важно! В будущей версии Microsoft SQL Server эта возможность будет удалена. Избегайте использования этой возможности в новых разработках и запланируйте изменение существующих приложений, в которых она применяется.
'CMDEXEC'	Команда операционной системы или исполняемая программа.
'DISTRIBUTION'	Задание агента распространения репликации.
'SNAPSHOT'	Задание агента моментальных снимков репликации.
'LOGREADER'	Задание агента чтения журнала репликации.
'MERGE'	Задание агента слияния репликации.
'QueueReader'	Задание агента чтения очереди репликации.
'ANALYSISQUERY'	Запрос служб Analysis Services (многомерное выражение, расширения интеллектуального анализа данных).
'ANALYSISCOMMAND'	Команда служб Analysis Services (XML для аналитики).
'Dts'	Выполнение пакетов служб Integration Services.
'PowerShell'	скрипт PowerShell
'TSQL' (по умолчанию)	инструкция Transact-SQL

[ @command= ] 'command'
Команды на выполнение службой SQLServerAgent через subsystem. Аргумент command имеет тип nvarchar(max) и значение по умолчанию NULL. Агент SQL Server выполняет замену токенов, что обеспечивает такую же гибкость, что и переменные при написании программ.

Важно!
В SQL Server 2005 с пакетом обновления 1 (SP1) синтаксис токена шага задания агента SQL Server был изменен. В результате все токены, используемые в шагах заданий, теперь должны сопровождаться экранирующим макросом, в противном случае они вызовут ошибку. Кроме того, синтаксис SQL Server 2000, в котором использовались квадратные скобки для вызова токенов шагов заданий агента SQL Server (например «[DATE]»), также изменен. Теперь имена токенов нужно заключать в круглые скобки и помещать в начале синтаксиса токена знак доллара ($). Например: $(ESCAPE_имя макроса(DATE))

В SQL Server 2005 с пакетом обновления 1 (SP1) синтаксис токена шага задания агента SQL Server был изменен. В результате все токены, используемые в шагах заданий, теперь должны сопровождаться экранирующим макросом, в противном случае они вызовут ошибку. Кроме того, синтаксис SQL Server 2000, в котором использовались квадратные скобки для вызова токенов шагов заданий агента SQL Server (например «[DATE]»), также изменен. Теперь имена токенов нужно заключать в круглые скобки и помещать в начале синтаксиса токена знак доллара ($). Например:

$(ESCAPE_имя макроса(DATE))

Дополнительные сведения о токенах и обновлении шагов заданий для использования нового синтаксиса токенов см. в разделе Использование токенов в шагах задания.

Примечание по безопасности
Все пользователи Windows с разрешением на запись в журнал событий Windows могут получить доступ к шагам заданий, которые активированы предупреждениями агента SQL Server или инструментария WMI. Чтобы избежать этого нарушения безопасности, SQL Server токены агента, которые могут использоваться в заданиях, активированных предупреждениями, по умолчанию отключены. Такими токенами являются A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property). Если необходимо использовать эти токены, убедитесь, что только члены доверенных групп безопасности Windows, таких как группа «Администраторы», обладают разрешением на работу с журналом событий компьютера, на котором находится SQL Server. Затем, чтобы включить эти токены, щелкните правой кнопкой мыши элемент Агент SQL Server в окне Обозреватель объектов, выберите пункт меню Свойства и на странице Система предупреждений установите флажок Заменить токены всех ответов заданий на предупреждения.

Все пользователи Windows с разрешением на запись в журнал событий Windows могут получить доступ к шагам заданий, которые активированы предупреждениями агента SQL Server или инструментария WMI. Чтобы избежать этого нарушения безопасности, SQL Server токены агента, которые могут использоваться в заданиях, активированных предупреждениями, по умолчанию отключены. Такими токенами являются A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property).

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

[ @additional_parameters= ] 'parameters'
Указано только в ознакомительных целях. Не поддерживается. Совместимость с будущими версиями не гарантируется. аргумент parameters имеет тип ntext и значение по умолчанию NULL.
[ @cmdexec_success_code = ] code
Значение, возвращаемое командой подсистемы CmdExec для оповещения о том, что command была выполнена успешно. Аргумент code имеет тип int и значение по умолчанию 0.

[ @on_success_action= ] success_action
Это действие будет выполнено, если выполнение этапа завершилось успешно. Аргумент success_action имеет тип tinyint и может принимать одно из следующих значений.

Значение	Описание (действие)
1 (по умолчанию)	Завершить с успешным выполнением.
2	Завершить с ошибкой.
3	Перейти к следующему шагу.
4	Перейти к этапу on_success_step_id.

[ @on_success_step_id = ] success_step_id
Идентификатор этапа в этом задании, который выполнится, если выполнение этапа завершится успешно и значение аргумента success_action равно 4. Аргумент success_step_id имеет тип int и значение по умолчанию 0.

[ @on_fail_action= ] fail_action
Это действие будет выполнено, если выполнение этапа завершилось ошибкой. Аргумент fail_action имеет тип tinyint и может принимать одно из следующих значений.

Значение	Описание (действие)
1	Завершить с успешным выполнением.
2 (по умолчанию)	Завершить с ошибкой.
3	Перейти к следующему шагу.
4	Перейти к этапу on_fail_step_id.

[ @on_fail_step_id= ] fail_step_id
Идентификатор этапа в этом задании, который выполнится, если выполнение этапа завершится неудачно и значение аргумента fail_action равно 4. Аргумент fail_step_id имеет тип int и значение по умолчанию 0.
[ @server =] 'server'
Аргумент Указано только в ознакомительных целях. Не поддерживается. Совместимость с будущими версиями не гарантируется.serverимеет тип nvarchar(30) и значение по умолчанию NULL.
[ @database_name = ] 'database'
Имя базы данных, в которой необходимо выполнить шаг Transact-SQL. Аргумент database имеет тип sysname и значение по умолчанию NULL, в случае которого используется база данных master. Имена, заключенные в квадратные скобки ([ ]), недопустимы. Для шага задания ActiveX database является именем языка скриптов, который используется в этапе.
[ @database_user_name= ] 'user'
Имя учетной записи пользователя, используемое при выполнении шага Transact-SQL. Аргумент user имеет тип sysname и значение по умолчанию NULL. Если значение аргумента user равно NULL, этап выполняется в контексте пользователя владельца задания на базе данных database. Агент SQL Server включит этот параметр только в случае, если владелец задания — член роли SQL Server sysadmin. Если это так, то данный шаг Transact-SQL будет выполнен в контексте данного имени пользователя SQL Server. Если владелец задания не входит в роль SQL Server sysadmin, то шаг Transact-SQL всегда будет выполняться в контексте имени входа, выполняющего задание, а параметр @database_user_name будет игнорироваться.
[ @retry_attempts= ] retry_attempts
Число производимых попыток в случае неудачного выполнения этапа. Аргумент retry_attemptsимеет тип int и значение по умолчанию 0, что указывает на отсутствие повторных попыток.
[ @retry_interval= ] retry_interval
Время между попытками. Аргумент retry_interval имеет тип int и значение по умолчанию 0, что означает 0-минутный интервал.
[ @os_run_priority = ] run_priority
Зарезервировано.
[ @output_file_name= ] 'file_name'
Имя файла, в который сохраняется вывод этапа. Аргумент file_name имеет тип nvarchar(200) и значение по умолчанию NULL. Аргумент file_name может включать один или несколько токенов, указанных в команде command. Этот параметр действителен только с командами, выполняемыми в подсистемах Transact-SQL, CmdExec, PowerShell, Integration Services или Службы Analysis Services.

[ @flags= ] flags
Параметр, который управляет поведением. Аргумент flags имеет тип int и может принимать одно из следующих значений.

Значение	Описание
0 (по умолчанию)	Переписать выходной файл.
2	Добавить к выходному файлу.
4	Записать вывод шага задания Transact-SQL в журнал шагов.
8	Записать журнал в таблицу (переписать существующий журнал).
16	Записать журнал в таблицу (добавить к существующему журналу).
32	Записать все выходные данные в журнал заданий.
64	Создать событие Windows для использования в качестве сигнала для прерывания шага задания Cmd.

[ @proxy_id = ] proxy_id
Идентификационный номер учетной записи-посредника, в качестве которого выполняется шаг задания. Аргумент proxy_id имеет тип int и значение по умолчанию NULL. Если значения аргументов proxy_id, proxy_name и user_name не указаны, шаг задания выполняется как учетная запись службы агента SQL Server.
[ @proxy_name = ] 'proxy_name'
Имя учетной записи-посредника, под которым выполняется шаг задания. Аргумент proxy_name имеет тип sysname и значение по умолчанию NULL. Если значения аргументов proxy_id, proxy_name и user_name не указаны, шаг задания выполняется как учетная запись службы агента SQL Server.

Значения кода возврата

0 (успешное завершение) или 1 (неуспешное завершение)

Результирующие наборы

Нет

Замечания

Процедура sp_add_jobstep должна быть выполнена из базы данных msdb.

Среда SQL Server Management Studio обеспечивает простой, наглядный способ управления заданиями и рекомендуется для создания инфраструктуры заданий и управления ею.

Шаг задания должен указывать учетную запись-посредник, если только создатель этапа задания не является членом фиксированной роли безопасности sysadmin.

Учетная запись-посредник может быть задана с помощью аргументов proxy_name или proxy_id.

Разрешения

По умолчанию эту хранимую процедуру могут выполнять члены предопределенной роли сервера sysadmin. Другим пользователям должна быть предоставлена одна из следующих предопределенных ролей базы данных агента SQL Server в базе данных msdb.

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Дополнительные сведения о разрешениях для этих ролей см. в разделе Предопределенные роли базы данных агента SQL Server.

Создатель шага задания должен иметь доступ к учетной записи-посреднику для шага задания. Члены предопределенной роли сервера sysadmin имеют доступ ко всем учетным записям-посредникам. Другим пользователям доступ к учетной записи-посреднику должен быть предоставлен явно.

Примеры

Следующий пример создает шаг задания, который изменяет доступ к базе данных на доступ только для чтения для базы данных Sales. Кроме того, этот пример задает число повторных попыток, которое равно 5, и через каждые 5 минут.

Примечание
В этом примере предполагается, что задание Weekly Sales Data Backup уже существует.

USE msdb;
GO
EXEC sp_add_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_name = N'Set database to read only',
    @subsystem = N'TSQL',
    @command = N'ALTER DATABASE SALES SET READ_ONLY', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO