sp_add_jobstep (Transact-SQL)

Статья
03/07/2014

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

Применимо для следующих объектов: SQL Server (начиная с SQL Server 2008 до текущей версии).

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

Важно!
Все токены, используемые в шагах заданий, теперь должны сопровождаться экранирующим макросом, в противном случае они вызовут ошибку.Кроме того, теперь имена токенов нужно заключать в круглые скобки и помещать в начале синтаксиса токена знак доллара ($).Например. $(ESCAPE_macro name(DATE))

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

$(ESCAPE_macro name(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