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'
  SQL Server エージェント サービスが command を実行するために使用するサブシステム。 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 エージェントのジョブ ステップ トークンの構文が変更されています。 その結果、エスケープ マクロには、ジョブ ステップで使用するすべてのトークンを含める必要があります。すべてのトークンが含まれてないと、ジョブ ステップは失敗します。 また、トークン名はかっこで囲み、トークン構文の先頭にはドル記号 ($) を付けることが必要になりました。 例: $(ESCAPE_macro name(DATE))

  これらのトークンの詳細と、新しいトークン構文を使用するためのジョブ ステップの更新方法の詳細については、「ジョブ ステップでのトークンの使用」を参照してください。

  セキュリティに関する注意

  Windows イベント ログに対して書き込みのアクセス許可を持っている Windows ユーザーであればだれでも、SQL Server エージェントの警告または WMI 警告によってアクティブ化されるジョブ ステップにアクセスできます。 このようなセキュリティ上のリスクを回避するため、警告によって実行されるジョブで使用できる SQL Server エージェントのトークンは、既定では無効になっています。 このようなトークンには、A-DBN、A-SVR、A-ERR、A-SEV、A-MSG、および WMI(property) があります。 このリリースでは、トークンの使用はすべての警告に拡張されていることに注意してください。 これらのトークンを使用する必要がある場合は、まず、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 上のジョブ所有者のユーザー コンテキストを使用して実行されます。 このパラメーターが SQL Server エージェントに含まれるのは、ジョブ所有者が SQL Server sysadmin である場合だけです。 その場合、指定された 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 で示されているトークンを 1 つ以上含むことができます。 このパラメーターは、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
  ジョブ ステップを実行するプロキシの 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 固定サーバー ロールのメンバーは、すべてのプロキシへのアクセス権があります。 他のユーザーには、明示的にプロキシへのアクセスが付与される必要があります。

使用例

次の例では、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

関連項目

参照

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)

概念

ジョブの表示または変更