sp_add_jobstep (Transact-SQL)

適用於：SQL ServerAzure SQL 受控執行個體

將步驟（作業）新增至 SQL Server Agent 作業。

Transact-SQL 語法慣例

重要

在 Azure SQL 受控執行個體 上，大部分但不支援所有 SQL Server Agent 作業類型。 如需詳細資料，請參閱 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 Agent 服務用來執行 @command的子系統。 @subsystem為 nvarchar（40），而且可以是下列其中一個值。

值	Description
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 Agent 服務要透過 @subsystem執行的命令。 @command為 nvarchar（max），預設值為 NULL。 SQL Server Agent 提供令牌替代，可讓您在撰寫軟體程式時提供變數所提供的相同彈性。

逸出宏必須伴隨作業步驟中使用的所有令牌，否則這些作業步驟會失敗。 此外，您現在必須將令牌名稱括在括弧中，並將貨幣符號 （$） 放在令牌語法的開頭。 例如： $(ESCAPE_<macro name>(DATE)) 。

如需這些令牌和更新作業步驟以使用新令牌語法的詳細資訊，請參閱 在作業步驟中使用令牌。

只要是具有 Windows 事件記錄檔寫入權限的 Windows 使用者，都可以存取由 SQL Server Agent 警示或 WMI 警示啟動的作業步驟。 為了避免此安全性風險，依預設會停用可在警示啟動作業中使用的 SQL Server Agent Token。 這些權杖包括：A-DBN、、A-ERRA-SVR、A-SEV、、A-MSG 和 WMI(<property>)。 在此版本中，令牌的使用會延伸至所有警示。

如果需要使用這些 Token，請先確認只有受信任的 Windows 安全性群組成員 (例如 Administrators 群組) 具有 SQL Server 所在電腦的事件記錄檔寫入權限。 然後以滑鼠右鍵按一下物件總管中的 [SQL Server Agent]、選取 [屬性]，然後在 [警示系統] 頁面上選取 [取代回應警示之所有作業的 Token]，以啟用這些 Token。

[ @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_action為 ，則此作業中要執行之步驟的標識碼。4 @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 @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 為 時，步驟會在作業擁有者的用戶內容中執行@database_name。NULL 只有在作業擁有者是 SQL Server 系統管理員時，SQL Server Agent 才會包含此參數。 如果是，則會在指定的 SQL Server 使用者名稱內容中執行指定的 Transact-SQL 步驟。 如果作業擁有者不是 SQL Server 系統管理員，則 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，而且可以是下列其中一個值。

值	Description
0 (預設值)	覆寫輸出檔案
2	附加至輸出檔案
4	將 Transact-SQL 作業步驟輸出寫入至步驟歷程記錄
8	將記錄寫入資料表（覆寫現有的歷程記錄）
16	將記錄寫入資料表（附加至現有記錄）
32	將所有輸出寫入作業歷程記錄
64	建立 Windows 事件以做為中止作業步驟的 cmd 訊號

[ @proxy_id = ] proxy_id

作業步驟執行之 Proxy 的標識碼。 @proxy_id為 int，預設值為 NULL。 如果未指定任何@proxy_id，則未指定任何@proxy_name，且未指定任何@database_user_name，作業步驟會以 SQL Server Agent 的服務帳戶執行。

[ @proxy_name = ] N'proxy_name'

作業步驟執行所在的 Proxy 名稱。 @proxy_name為 sysname，預設值為 NULL。 如果未指定任何@proxy_id，則未指定任何@proxy_name，且未指定任何@database_user_name，作業步驟會以 SQL Server Agent 的服務帳戶執行。

[ @step_uid = ] 'step_uid' OUTPUT

@step_uid是 uniqueidentifier 類型的 OUTPUT 參數。

傳回碼值

0 (成功) 或 1 (失敗)。

結果集

無。

備註

sp_add_jobstep 必須從 msdb 資料庫執行。

SQL Server Management Studio 提供易用的作業管理圖形介面，是建立及管理作業基礎結構的建議方式。

根據預設，除非指定另一個 Proxy，否則作業步驟會以 SQL Server Agent 的服務帳戶執行。 此帳戶的需求是 sysadmin 固定安全性角色的成員。

proxy 可由@proxy_name或@proxy_id來識別。

此預存程式會與 Azure SQL 資料庫 的 Azure Elastic Jobs 服務類似物件共用 的名稱sp_add_jobstep。 如需彈性作業版本的相關信息，請參閱 jobs.sp_add_jobstep （Azure Elastic Jobs） （Transact-SQL） 。

權限

此預存程式是由 db_owner 角色所擁有。 您可以授與 EXECUTE 任何用戶的許可權，但這些許可權可能會在 SQL Server 升級期間覆寫。

其他用戶必須在資料庫中獲得下列其中一個 SQL Server Agent 固定資料庫角色 msdb ：

• SQLAgentUserRole
• SQLAgentReaderRole
• SQLAgentOperatorRole

如需這些角色權限的詳細資訊，請參閱 SQL Server Agent 固定資料庫角色。

作業步驟的建立者必須能夠存取作業步驟的 Proxy。 系統管理員固定伺服器角色的成員可以存取所有 Proxy。 其他用戶必須明確授與 Proxy 的存取權。

範例

下列範例會建立作業步驟，以變更 Sales 資料庫的唯讀數據庫存取權。 此外，此範例會指定五次重試嘗試，每次重試會在 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)