sp_add_jobstep (Transact-SQL)

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

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 查询 (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))

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

  安全说明
  对 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 中的作业所有者用户上下文中运行。

• [ @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 SQL Server Integration Services 或者 SQL Server Analysis Services 子系统上运行的命令有效。

• [ @flags= ] flags
  控制行为的选项。flags 的数据类型为 int，可以是下列值之一：

  值	说明
  0（默认值）	覆盖输出文件
  2	追加到输出文件
  4	将 Transact-SQL 作业步骤输出写入步骤历史记录
  8	将日志写入表（覆盖现有的历史记录）
  16	将日志写入表中（追加到现有历史记录）

• [ @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 固定服务器角色的成员可以访问所有代理。 其他用户必须经过显式授予才能访问代理。

示例

以下示例可创建一个作业步骤，将 AdventureWorks 数据库的访问权限更改为只读。 此外，此示例还指定了 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

请参阅

参考

sp_add_job (Transact-SQL)

sp_add_schedule (Transact-SQL)

sp_delete_jobstep (Transact-SQL)

sp_help_job (Transact-SQL)

sp_help_jobstep (Transact-SQL)

sp_update_jobstep (Transact-SQL)

系统存储过程 (Transact-SQL)

概念

查看和修改作业