sp_add_jobstep (Transact-SQL)

sp_add_jobstep (Transact-SQL) 

已更新： 2006 年 4 月 14 日

在作業中添加一個步驟（操作）。

文法

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'

Microsoft SQL Server Agent服務用於執行 command 的子系統。subsystem 的資料類型為 nvarchar(40)，可以是下列值之一：

值	說明
'ACTIVESCRIPTING'	動態指令碼處理
'CMDEXEC'	作業系統命令或可執行程式
'DISTRIBUTION'	複製分發代理作業
'SNAPSHOT'	複製快照代理作業
'LOGREADER'	複製記錄讀取器代理程式作業
'MERGE'	複製合并代理作業
'QueueReader'	複製佇列讀取器代理程式作業
'ANALYSISQUERY'	Analysis Services 查詢 (MDX、DMX)。
'ANALYSISCOMMAND'	Analysis Services 命令 (XMLA)。
'Dts'	Integration Services 包執行
'TSQL'（預設）	Transact-SQL 陳述式

[ @command = ] 'command'

SQLServerAgent 服務通過 subsystem 執行的命令。command 的資料類型為 nvarchar(max)，預設值為 NULL。SQL Server Agent提供令牌替換，在編寫軟體程式時，它可提供與變數相同的靈活性。

重要事項：
在 SQL Server 2005 Service Pack 1 中，SQL Server Agent作業步驟的標記文法已發生更改。因此，作業步驟中使用的所有令牌現在必須附帶轉義宏，否則，這些作業步驟將失敗。此外，使用方括弧調用 SQL Server 2000 代理作業步驟標記的 SQL Server 文法（例如，“[DATE]”）也已發生更改。現在，必須用括弧將令牌名稱括起來，並在令牌文法的開頭加上貨幣符號 ($)。例如： $(ESCAPE_宏名稱(DATE))

有關這些令牌和更新作業步驟以使用新令牌文法的詳細資料，請參閱在作業步驟中使用標記。

安全記事：
對 Windows 事件記錄具有寫入許可權的任何 Windows 使用者都可以訪問由 SQL Server Agent警報或 WMI 警報啟用的作業步驟。為了確保安全，預設情況下，可在警報啟用的作業中使用的 SQL Server Agent令牌處于禁用狀態。這些令牌是：A-DBN、A-SVR、A-ERR、A-SEV、A-MSG 和 WMI(property)。 如果您需要使用這些令牌，請首先確保只有可信任的 Windows 安全性群組（如 Administrators 組）成員才對安裝 SQL Server 的電腦的事件記錄具有寫入許可權。然後在物件總管中按右鍵“SQL Server Agent”，選擇“屬性”，並在“警報系統”頁上選擇“為警報的所有作業響應替換令牌”以啟用這些令牌。

[ @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 子系統上啟動並執行命令有效。

[ @flags = ] flags

控制行為的選項。flags 的資料類型為 int，可以是下列值之一：

值	說明
0（預設值）	覆蓋輸出檔案
2	追加到輸出檔案
4	將 Transact-SQL 作業步驟輸出寫入步驟記錄
8	將日誌寫入表（覆蓋現有的記錄）
16	將日誌寫入表中（追加到現有記錄）

[ @proxy_id = ] proxy_id

作業步驟作為代理運行時，代理的 識別碼。proxy_id 的資料類型為 int，預設值為 NULL。如果未指定 proxy_id、proxy_name 和 user_name，則作業步驟將作為 SQL Server Agent的服務帳戶運行。

[ @proxy_name = ] 'proxy_name'

作業步驟作為代理運行時，代理的名稱。proxy_name 的資料類型為 sysname，預設值為 NULL。如果未指定 proxy_id、proxy_name 和 user_name，則作業步驟將作為 SQL Server Agent的服務帳戶運行。

備忘

必須從 msdb 資料庫運行 sp_add_jobstep。

SQL Server Management Studio 為管理作業提供了一種圖形化的簡便方法，建議使用此方法來建立和管理作業基礎結構。

除非作業步驟的建立者是 sysadmin 固定資訊安全角色的成員，否則作業步驟必須指定一個代理。

代理可通過 proxy_name 或 proxy_id 標識。

傳回碼值

0（成功）或 1（失敗）

結果集

無

許可權

預設情況下，只有 sysadmin 固定伺服器角色的成員才可以執行此預存程序。其他使用者必須被授予 msdb 資料庫中下列 SQL Server Agent固定資料庫角色的許可權之一：

• SQLAgentUserRole
  
• SQLAgentReaderRole
  
• SQLAgentOperatorRole
  

有關這些角色的許可權的詳細資料，請參閱 SQL Server Agent固定資料庫角色。

作業步驟的建立者必須有權訪問作業步驟的代理。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'exec sp_dboption ''sales'', ''read only'', ''true''', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO