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
  ジョブ ステップのシーケンス ID 番号を指定します。 ステップ ID 番号は 1 から始まり、間隔を置かずに増加します。 既存のシーケンスにステップを挿入すると、シーケンス番号が自動的に調整されます。 step_id を指定しない場合は、値が設定されます。step_id のデータ型は int で、既定値は NULL です。

• [ @step_name = ] 'step_name'
  ステップの名前を指定します。step_name のデータ型は sysname で、既定値はありません。

• [ @subsystem = ] 'subsystem'
  command を実行するために SQL Server エージェント サービスによって使用されるサブシステムを指定します。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'
  subsystem を使用して SQLServerAgent サービスで実行されるコマンドを指定します。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 (プロパティ) です。 これらのトークンを使用する必要がある場合は、まず、Administrators グループなどの信頼されている Windows セキュリティ グループのメンバーのみが、SQL Server がインストールされているコンピューターのイベント ログに対して書き込みのアクセス許可を持っていることを確認してください。 確認したら、[オブジェクト エクスプローラー] で [SQL Server エージェント] を右クリックし、[プロパティ] をクリックします。次に、[警告システム] ページで、[警告に応答するすべてのジョブのトークンを置き換える] チェック ボックスをオンにして、これらのトークンを有効にします。

• [ @additional_parameters= ] 'parameters'
  単に情報を示すためだけに特定されます。 サポートされていません。 将来の互換性は保証されません。parameters のデータ型は ntext で、既定値は NULL です。

• [ @cmdexec_success_code = ] code
  command が正常に実行されたことを示すために、CmdExec サブシステム コマンドによって返される値を指定します。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 で説明したトークンを 1 つ以上含めることができます。 このパラメーターは、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 (失敗)

結果セット

なし

説明

sp_add_jobstep は msdb データベースから実行する必要があります。

SQL Server Management Studio は、ジョブを簡単に管理できるグラフィカルなツールです。ジョブのインフラストラクチャを作成し、管理するには、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)

概念

ジョブの表示と変更