sp_add_jobstep (Transact-SQL)

项目
06/18/2013

在作业中添加步骤（操作）。

语法

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 查询 (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 代理作业步骤的标记语法已发生变化。因此，作业步骤中使用的所有标记现在必须附带转义宏，否则，这些作业步骤将会失败。此外，您现在还必须用括号将标记名称括起来，并在标记语法开头加上美元符号 ($)。例如： $(ESCAPE_macro name(DATE))

在 SQL Server 2005 Service Pack 1 中，SQL Server 代理作业步骤的标记语法已发生变化。因此，作业步骤中使用的所有标记现在必须附带转义宏，否则，这些作业步骤将会失败。此外，您现在还必须用括号将标记名称括起来，并在标记语法开头加上美元符号 ($)。例如：

$(ESCAPE_macro name(DATE))

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

安全说明
对 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 代理”，选择“属性”，并在“警报系统”页上选择“为警报的所有作业响应替换标记”以启用这些标记。

对 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 子系统上运行的命令有效。

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

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

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