sp_add_jobstep (Transact-SQL)
在作业中添加一个步骤（操作）。
.gif "主题链接图标")
语法
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。.gif "注意")
注意必须指定 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'
活动脚本
.gif "重要说明")
重要提示
后续版本的 Microsoft SQL Server 将删除该功能。请避免在新的开发工作中使用该功能，并着手修改当前还在使用该功能的应用程序。'CMDEXEC'
操作系统命令或可执行程序
'DISTRIBUTION'
复制分发代理作业
'SNAPSHOT'
复制快照代理作业
'LOGREADER'
复制日志读取器代理作业
'MERGE'
复制合并代理作业
'QueueReader'
复制队列读取器代理作业
'ANALYSISQUERY'
Analysis Services 查询 (MDX、DMX)。
'ANALYSISCOMMAND'
Analysis Services 命令 (XMLA)。
'Dts'
Integration Services 包执行
'PowerShell'
PowerShell 脚本
'TSQL'（默认）
Transact-SQL 语句
[ @command= ] 'command'
SQLServerAgent 服务通过 subsystem 执行的命令。command 的数据类型为 nvarchar(max)，默认值为 NULL。SQL Server 代理提供令牌替换，在编写软件程序时，它可提供与变量相同的灵活性。重要提示在 SQL Server 2005 Service Pack 1 中，SQL Server 代理作业步骤的标记语法已发生更改。因此，作业步骤中使用的所有令牌现在必须附带转义宏，否则，这些作业步骤将失败。此外，使用方括号调用 SQL Server 2000 代理作业步骤标记的 SQL Server 语法（例如，“[DATE]”）也已发生更改。现在，必须用括号将令牌名称括起来，并在令牌语法的开头加上美元符号 ($)。例如：
$(ESCAPE_宏名(DATE))
有关这些令牌和更新作业步骤以使用新令牌语法的详细信息，请参阅在作业步骤中使用标记。
.gif "安全说明")
安全说明对 Windows 事件日志拥有写入权限的任何 Windows 用户都可以访问由 SQL Server 代理警报或 WMI 警报激活的作业步骤。为了确保安全，默认情况下，可在警报激活的作业中使用的 SQL Server 代理令牌处于禁用状态。这些令牌包括：A-DBN、A-SVR、A-ERR、A-SEV、A-MSG 和 WMI(property)。
如果您需要使用这些令牌，请首先确保只有可信任的 Windows 安全组（如 Administrators 组）成员才对安装 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 时，该作业中要执行的步骤的 ID。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 时，该作业中要执行的步骤的 ID。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 sysadmin 时，SQL Server 代理才包括此参数。如果是这样，则给定的 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 jobstep 要中止的信号
[ @proxy_id = ] proxy_id
作业步骤作为代理运行时，代理的 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（失败）
结果集
无
注释
必须从 msdb 数据库运行 sp_add_jobstep。
SQL Server Management Studio 为管理作业提供了一种图形化的简便方法，建议使用此方法来创建和管理作业基础结构。
除非作业步骤的创建者是 sysadmin 固定安全角色的成员，否则作业步骤必须指定一个代理。
代理可通过 proxy_name 或 proxy_id 标识。
权限
默认情况下，只有 sysadmin 固定服务器角色的成员才可以执行此存储过程。其他用户必须被授予 msdb 数据库中下列 SQL Server 代理固定数据库角色的权限之一：
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