Статья
09/28/2010

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 и не имеет значения по умолчанию.

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

[ @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.
[ @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 и службах SQL Server Integration Services или SQL Server Analysis Services.

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

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

[ @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 имеют доступ ко всем учетным записям-посредникам. Другим пользователям доступ к учетной записи-посреднику должен быть предоставлен явно.

Примеры

Следующий пример создает шаг задания, который изменяет доступ к базе данных на доступ только для чтения для базы данных AdventureWorks. Кроме того, этот пример задает число повторных попыток, которое равно 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