[アーティクル]
04/01/2012

sp_add_jobstep (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 で、既定値はありません。

注
job_id または job_name のいずれかを指定する必要があります。両方を指定することはできません。

[ @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))

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 エージェント] を右クリックし、[プロパティ] をクリックします。次に、[警告システム] ページで、[警告に応答するすべてのジョブのトークンを置き換える] チェックボックスをオンにして、これらのトークンを有効にします。

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 上のジョブ所有者のユーザーコンテキストを使用して実行されます。このパラメーターが 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_jobstep (Transact-SQL)

構文

引数

リターンコードの値

結果セット

説明

権限

例

関連項目

参照

概念

その他のリソース

次の方法で共有

sp_add_jobstep (Transact-SQL)

構文

引数

リターン コードの値

結果セット

説明

権限

例

関連項目

参照

概念

その他のリソース

リターンコードの値