sp_add_jobstep (Transact-SQL)

Статья
12/22/2023

Применимо к:SQL Server Управляемый экземпляр SQL Azure

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

Внимание

В Управляемый экземпляр SQL Azure поддерживаются большинство, но не все типы заданий агент SQL Server. Подробные сведения см. в статье Различия в T-SQL между Управляемым экземпляром SQL Azure и SQL Server.

Синтаксис

sp_add_jobstep
    [ [ @job_id = ] 'job_id' ]
    [ , [ @job_name = ] N'job_name' ]
    [ , [ @step_id = ] step_id ]
    , [ @step_name = ] N'step_name'
    [ , [ @subsystem = ] N'subsystem' ]
    [ , [ @command = ] N'command' ]
    [ , [ @additional_parameters = ] N'additional_parameters' ]
    [ , [ @cmdexec_success_code = ] cmdexec_success_code ]
    [ , [ @on_success_action = ] on_success_action ]
    [ , [ @on_success_step_id = ] on_success_step_id ]
    [ , [ @on_fail_action = ] on_fail_action ]
    [ , [ @on_fail_step_id = ] on_fail_step_id ]
    [ , [ @server = ] N'server' ]
    [ , [ @database_name = ] N'database_name' ]
    [ , [ @database_user_name = ] N'database_user_name' ]
    [ , [ @retry_attempts = ] retry_attempts ]
    [ , [ @retry_interval = ] retry_interval ]
    [ , [ @os_run_priority = ] os_run_priority ]
    [ , [ @output_file_name = ] N'output_file_name' ]
    [ , [ @flags = ] flags ]
    [ , [ @proxy_id = ] proxy_id ]
    [ , [ @proxy_name = ] N'proxy_name' ]
    [ , [ @step_uid = ] 'step_uid' OUTPUT ]
[ ; ]

Аргументы

[ @job_id = ] 'job_id'

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

Необходимо указать @job_id или @job_name, но их нельзя указать.

[ @job_name = ] N'job_name'

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

Необходимо указать @job_id или @job_name, но их нельзя указать.

[ @step_id = ] step_id

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

[ @step_name = ] N'step_name'

Имя шага этапа. @step_name — sysname без значения по умолчанию.

[ @subsystem = ] N'подсистема

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

значение	Описание
`ActiveScripting`	Активный скрипт. Важно. Эта функция будет удалена в будущей версии SQL Server. Избегайте использования этого компонента в новых разработках и запланируйте изменение существующих приложений, в которых он применяется.
`CmdExec`	Команда операционной системы или исполняемая программа.
`Distribution`	Задание агента распространения репликации.
`Snapshot`	Задание агента моментальных снимков репликации.
`LogReader`	Задание агента чтения журнала репликации.
`Merge`	Задание агента слияния репликации.
`QueueReader`	Задание агента чтения очереди репликации.
`ANALYSISQUERY`	Запрос служб Analysis Services (многомерные выражения, dmX)
`ANALYSISCOMMAND`	Команда Analysis Services (XMLA)
`SSIS`	Выполнение пакетов служб Integration Services
`PowerShell`	Скрипт PowerShell
`TSQL` (по умолчанию)	Инструкция Transact-SQL

[ @command = ] N'command'

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

Макрос escape-файла должен сопровождать все маркеры, используемые в шагах задания, или другие действия задания завершаются ошибкой. Кроме того, теперь имена токенов нужно заключать в круглые скобки и помещать в начале синтаксиса токена знак доллара ($). Например: $(ESCAPE_<macro name>(DATE)).

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

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

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

[ @additional_parameters = ] N'additional_parameters'

Указано только в ознакомительных целях. Не поддерживается. Совместимость с будущими версиями не гарантируется.

[ @cmdexec_success_code = ] cmdexec_success_code

Значение, возвращаемое командой CmdExec подсистемы, указывающее, что @command выполнен успешно. @cmdexec_success_code имеет значение int с значением по умолчанию0.

[ @on_success_action = ] on_success_action

Операция, выполняемая в случае успешного завершения этапа. @on_success_action крошечный и может быть одним из этих значений.

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

[ @on_success_step_id = ] on_success_step_id

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

[ @on_fail_action = ] on_fail_action

Действие, которое необходимо выполнить, если шаг завершился с ошибкой. @on_fail_action крошечный и может быть одним из этих значений.

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

[ @on_fail_step_id = ] on_fail_step_id

Идентификатор шага в этом задании, который выполняется, если шаг завершается ошибкой и @on_fail_action.4 @on_fail_step_id имеет значение int с значением по умолчанию0.

[ @server = ] N'server'

[ @database_name = ] N'database_name'

Имя базы данных, в которой выполняется шаг Transact-SQL. @database_name имеет имя sysname, при этом используется база данных по умолчаниюNULLmaster. Имена, заключенные в квадратные скобки ([]) не допускаются. Для шага задания ActiveX @database_name — это имя языка скриптов, который используется на шаге.

[ @database_user_name = ] N'database_user_name'

Имя учетной записи пользователя, используемой при выполнении шага Transact-SQL. @database_user_name — sysname с значением по умолчаниюNULL. При @database_user_nameNULLшаг выполняется в контексте пользователя владельца задания в @database_name. агент SQL Server включает этот параметр только в том случае, если владелец задания является системным администратором SQL Server. Если да, данный шаг Transact-SQL выполняется в контексте заданного имени пользователя SQL Server. Если владелец задания не является системным администратором SQL Server, то шаг 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 = ] os_run_priority

[ @output_file_name = ] N'output_file_name'

Имя файла, в котором будут сохранены выходные данные этого шага. @output_file_name — nvarchar(200) с значением по умолчаниюNULL. @output_file_name может включать один или несколько маркеров, перечисленных в @command. Этот параметр действителен только с командами, выполняемыми в подсистемах Transact-SQL, CmdExecPowerShellIntegration Services или Analysis Services.

[ @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не указан и не указан @database_user_name, шаг задания выполняется в качестве учетной записи службы для агент SQL Server.

[ @proxy_name = ] N'proxy_name'

Имя учетной записи-посредника, от имени которой выполняется шаг задания. @proxy_name — sysname с значением по умолчаниюNULL. Если @proxy_id не задано, @proxy_nameне указан и не указан @database_user_name, шаг задания выполняется в качестве учетной записи службы для агент SQL Server.

[ = ] @step_uid "step_uid" OUTPUT

@step_uid — это параметр OUTPUT типа uniqueidentifier.

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

0 (успешно) или 1 (сбой).

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

Нет.

Замечания

sp_add_jobstep должен выполняться из msdb базы данных.

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

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

Прокси-сервер может быть идентифицирован @proxy_name или @proxy_id.

Эта хранимая процедура использует имя аналогичного sp_add_jobstep объекта для службы заданий Elastic Azure для База данных SQL Azure. Сведения о версии эластичных заданий см. в разделе jobs.sp_add_jobstep (Задания Эластичных баз данных Azure) (Transact-SQL).

Разрешения

Эта хранимая процедура принадлежит роли db_owner . Вы можете предоставить EXECUTE разрешения для любого пользователя, но эти разрешения могут быть переопределены во время обновления SQL Server.

Другим пользователям необходимо предоставить одну из следующих агент SQL Server предопределенных ролей базы данных в msdb базе данных:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

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

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

Примеры

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

sp_add_jobstep (Transact-SQL)

Синтаксис

Аргументы

[ @job_id = ] 'job_id'

[ @job_name = ] N'job_name'

[ @step_id = ] step_id

[ @step_name = ] N'step_name'

[ @subsystem = ] N'подсистема

[ @command = ] N'command'

[ @additional_parameters = ] N'additional_parameters'

[ @cmdexec_success_code = ] cmdexec_success_code

[ @on_success_action = ] on_success_action

[ @on_success_step_id = ] on_success_step_id

[ @on_fail_action = ] on_fail_action

[ @on_fail_step_id = ] on_fail_step_id

[ @server = ] N'server'

[ @database_name = ] N'database_name'

[ @database_user_name = ] N'database_user_name'

[ @retry_attempts = ] retry_attempts

[ @retry_interval = ] retry_interval

[ @os_run_priority = ] os_run_priority

[ @output_file_name = ] N'output_file_name'

[ @flags = ] флаги

[ @proxy_id = ] proxy_id

[ @proxy_name = ] N'proxy_name'

[ = ] @step_uid "step_uid" OUTPUT

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

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

Замечания

Разрешения

Примеры

Обратная связь

Обратная связь

Дополнительные ресурсы

sp_add_jobstep (Transact-SQL)

Синтаксис

Аргументы

[ @job_id = ] 'job_id'

[ @job_name = ] N'job_name'

[ @step_id = ] step_id

[ @step_name = ] N'step_name'

[ @subsystem = ] N'подсистема

[ @command = ] N'command'

[ @additional_parameters = ] N'additional_parameters'

[ @cmdexec_success_code = ] cmdexec_success_code

[ @on_success_action = ] on_success_action

[ @on_success_step_id = ] on_success_step_id

[ @on_fail_action = ] on_fail_action

[ @on_fail_step_id = ] on_fail_step_id

[ @server = ] N'server'

[ @database_name = ] N'database_name'

[ @database_user_name = ] N'database_user_name'

[ @retry_attempts = ] retry_attempts

[ @retry_interval = ] retry_interval

[ @os_run_priority = ] os_run_priority

[ @output_file_name = ] N'output_file_name'

[ @flags = ] флаги

[ @proxy_id = ] proxy_id

[ @proxy_name = ] N'proxy_name'

[ = ] @step_uid "step_uid" OUTPUT

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

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

Замечания

Разрешения

Примеры

Связанный контент

Обратная связь

Обратная связь

Дополнительные ресурсы