sp_add_jobstep (Transact-SQL)

适用于： SQL Server Azure SQL 托管实例

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

Transact-SQL 语法约定

重要

在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 弹性作业）。

权限

此存储过程由 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_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)