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。[!附註]
您必須指定 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 Agent 服務用於執行 command 的子系統。subsystem 是 nvarchar(40)，可以是這些其中一個值。值
描述
'ACTIVESCRIPTING'
Active Script
.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'
透過 subsystem，由 SQLServerAgent 服務來執行的命令。command 是 nvarchar(max)，預設值是 NULL。 SQL Server Agent 所提供的 Token 替代可在您撰寫軟體程式時，提供變數所提供的同等彈性。重要事項在 SQL Server 2005 Service Pack 1 中，SQL Server Agent 作業步驟的 Token 語法已變更。 因此，逸出巨集現在必須伴隨著作業步驟中使用的所有 Token 一起執行，否則這些作業步驟將會失敗。 此外，原本使用方括號來呼叫 SQL Server Agent 作業步驟 Token (例如 "[DATE]") 的 SQL Server 2000 語法也已變更。 現在必須改用括號括住 Token 名稱，並且在 Token 語法的開頭加上錢幣符號 ($)。 例如：
$(ESCAPE_macro name(DATE))
如需有關這些 Token 以及如何更新作業步驟以利用新 Token 語法的詳細資訊，請參閱＜在作業步驟使用 Token＞。
.gif "安全性注意事項")
安全性注意事項對 Windows 事件記錄檔具有寫入權限的任何 Windows 使用者，都可以存取由 SQL Server Agent 警示或 WMI 警示啟動的作業步驟。 為了避免此安全性風險，依預設會停用在警示啟動的作業中可以使用的 SQL Server Agent Token。 這些 Token 包括：A-DBN、A-SVR、A-ERR、A-SEV、A-MSG 及 WMI(property)。
如果需要使用這些 Token，請先確定只有受信任的 Windows 安全性群組的成員 (例如管理員群組)，才對 SQL Server 所在電腦的事件記錄檔具有寫入權限。 然後以滑鼠右鍵按一下 [物件總管] 中的 [SQL Server Agent]，選取 [屬性]，然後在 [警示系統] 頁面上選取 [取代回應警示之所有作業的 Token]，以啟用這些 Token。
[ @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，則這是此作業中要執行之步驟的識別碼。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，則這是此作業中要執行之步驟的識別碼。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 Agent 才會包含此參數。 在此情況下，指定的 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 之下所列出的一個或多個 Token。 這個參數只對 Transact-SQL、CmdExec、PowerShell、Integration Services 或 Analysis Services 子系統上執行的命令有效。[ @flags= ] flags
這是一個控制行為的選項。flags 是 int，它可以是下列值之一。值
描述
0 (預設值)
覆寫輸出檔
2
附加至輸出檔
4
將 Transact-SQL 作業步驟輸出寫入步驟記錄。
8
將記錄寫入資料表 (覆寫現有的記錄)
16
將記錄寫入資料表 (附加至現有的記錄)
32
將所有輸出寫入作業記錄
64
建立 Windows 事件以做為 CMD 工作步驟要中止的訊號
[ @proxy_id = ] proxy_id
用於執行作業步驟之 Proxy 的識別碼。proxy_id 的類型是 int，預設值是 NULL。 如果 proxy_id、proxy_name 和 user_name 都沒有指定，就會用 SQL Server Agent 的服務帳戶來執行作業步驟。[ @proxy_name = ] 'proxy_name'
用來執行作業步驟之 Proxy 的名稱。proxy_name 的類型是 sysname，預設值是 NULL。 如果 proxy_id、proxy_name 和 user_name 都沒有指定，就會用 SQL Server Agent 的服務帳戶來執行作業步驟。
傳回碼值
0 (成功) 或 1 (失敗)
結果集
無
備註
sp_add_jobstep 必須從 msdb 資料庫中執行。
SQL Server Management Studio 提供了一種簡單的圖形方式供您管理各項作業，建議您利用這個方式來建立和管理作業基礎結構。
除非作業步驟的建立者是 系統管理員 (sysadmin) 固定安全性角色的成員，否則，作業步驟必須指定 Proxy。
Proxy 可以用 proxy_name 或 proxy_id 來識別。
權限
依預設，只有系統管理員 (sysadmin) 固定伺服器角色的成員，才能夠執行這個預存程序。 其他使用者必須被授與 msdb 資料庫的下列其中一個 SQL Server Agent 固定資料庫角色。
SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole
如需有關這些角色權限的詳細資料，請參閱＜SQL Server Agent 固定資料庫角色＞。
作業步驟的建立者必須有權存取作業步驟的 Proxy。 系統管理員 (sysadmin) 固定伺服器角色的成員有權存取所有 Proxy。 其他使用者需要明確授與 Proxy 的存取權。
範例
下列範例會建立一個作業步驟，以將 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