sp_add_jobstep (Transact-SQL)

项目
12/22/2023

将步骤（操作）添加到SQL Server 代理作业。

重要

在Azure SQL 托管实例，支持大多数但并非所有SQL Server 代理作业类型。有关详细信息，请参阅 Azure SQL 托管实例与 SQL Server 的 T-SQL 区别。

语法

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是 uniqueidentifier，默认值为 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'subsystem'

SQL Server 代理服务用来执行@command的子系统。 @subsystem为 nvarchar（40），可以是以下值之一。

值	说明
`ActiveScripting`	活动脚本重要说明：将在 SQL Server 的未来版本中删除此功能。请避免在新的开发工作中使用该功能，并着手修改当前还在使用该功能的应用程序。
`CmdExec`	操作系统命令或可执行程序
`Distribution`	复制分发代理作业
`Snapshot`	复制快照代理作业
`LogReader`	复制日志读取器代理作业
`Merge`	复制合并代理作业
`QueueReader`	复制队列读取器代理作业
`ANALYSISQUERY`	Analysis Services 查询（MDX、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_<macro name>(DATE))。

有关这些令牌和更新作业步骤以使用新令牌语法的详细信息，请参阅 “在作业步骤中使用令牌”。

对 Windows 事件日志拥有写入权限的任何 Windows 用户都可以访问由 SQL Server 代理警报或 WMI 警报激活的作业步骤。为了防范此安全隐患，默认情况下，可以在由警报激活的作业中使用的特定 SQL Server 代理标记已被禁用。这些标记包括：A-DBN、、A-SVR、A-SEVA-ERR、 A-MSG和WMI(<property>)。在此版本中，对标记的使用扩展至所有警报。

如果您需要使用这些标记，请首先确保只有可信任的 Windows 安全组（如 Administrators 组）成员才对安装 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 是 tinyint，可以是这些值之一。

值	说明（操作）
`1`（默认值）	成功退出
`2`	失败后退出
`3`	转到下一步
`4`	转到步骤 @on_success_step_id

[ @on_success_step_id = ] on_success_step_id

如果步骤成功且@on_success_action4，则执行此作业中步骤的 ID。 @on_success_step_id为 int，默认值为 0.

[ @on_fail_action = ] on_fail_action

步骤失败时执行的操作。 @on_fail_action 是 tinyint，可以是这些值之一。

值	说明（操作）
`1`	成功退出
`2`（默认值）	失败后退出
`3`	转到下一步
`4`	转到步骤 @on_fail_step_id

[ @on_fail_step_id = ] on_fail_step_id

如果步骤失败且@on_fail_action，4则此作业中要执行的步骤的 ID。 @on_fail_step_id为 int，默认值为 0.

[ @server = ] N'server'

标识为仅供参考。不支持。不保证以后的兼容性。

[ @database_name = ] N'database_name'

要在其中执行 Transact-SQL 步骤的数据库的名称。 @database_name为 sysname，NULL默认值为使用master数据库。不允许括在括号（[]）中的名称。对于 ActiveX 作业步骤， @database_name 是该步骤使用的脚本语言的名称。

[ @database_user_name = ] N'database_user_name'

执行 Transact-SQL 步骤时要使用的用户帐户的名称。 @database_user_name为 sysname，默认值为 NULL. 当@database_user_name时NULL，该步骤将在作业所有者的用户上下文中运行@database_name。仅当作业所有者为 SQL Server sysadmin 时，SQL Server 代理才包含此参数。如果是这样，则会在给定 SQL Server 用户名的上下文中执行给定的 Transact-SQL 步骤。如果作业所有者不是 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，表示间隔为 -minute。

[ @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

作业步骤作为代理运行时，代理的 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是 uniqueidentifier 类型的 OUTPUT 参数。

返回代码值

0（成功）或 1（失败）。

结果集

无。

注解

sp_add_jobstep 必须从 msdb 数据库运行。

SQL Server Management Studio 为管理作业提供了一种图形化的简便方法，建议使用此方法来创建和管理作业基础结构。

默认情况下，除非指定了另一个代理，否则作业步骤将作为SQL Server 代理的服务帐户运行。此帐户的要求是成为 sysadmin 固定安全角色的成员。

代理可以通过@proxy_name或@proxy_id进行标识。

此存储过程与用于Azure SQL 数据库的 Azure 弹性作业服务的类似对象共享名称sp_add_jobstep。有关弹性作业版本的信息，请参阅jobs.sp_add_jobstep（Azure 弹性作业）（Transact-SQL）。

权限

此存储过程由 db_owner 角色拥有。你可以为任何用户授予 EXECUTE 权限，但这些权限可能会在 SQL Server 升级期间被重写。

其他用户必须被授予数据库中以下SQL Server 代理固定数据库角色msdb之一：

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

有关这些角色的权限的详细信息，请参阅 SQL Server 代理固定数据库角色。

作业步骤的创建者必须有权访问作业步骤的代理。 sysadmin 固定服务器角色的成员有权访问所有代理。其他用户必须经过显式授予才能访问代理。

示例

以下示例可创建一个作业步骤，将销售数据库的访问权限更改为只读。此外，此示例还指定了五次重试尝试，每次重试在等待 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'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 = ] 标志

[ @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'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 = ] 标志

[ @proxy_id = ] proxy_id

[ @proxy_name = ] N'proxy_name'

[ @step_uid = ] 'step_uid' OUTPUT

返回代码值

结果集

注解

权限

示例

相关内容

反馈

反馈

其他资源