sp_add_jobstep (Transact-SQL)
適用対象: 
SQL Server Azure SQL Managed Instance
SQL Server エージェント ジョブにステップ (操作) を追加します。
重要
Azure SQL Managed Instance ではほとんどのジョブの種類がサポートされていますが、すべてのSQL Server エージェントジョブの種類がサポートされているわけではありません。 詳細については、Azure SQL Managed Instance と SQL Server の T-SQL の相違点に関するページを参照してください。
構文
sp_add_jobstep
[ [ @job_id = ] 'job_id' ]
[ , [ @job_name = ] N'job_name' ]
[ , [ @step_id = ] step_id ]
, [ @step_name = ] N'step_name'
[ , [ @subsystem = ] N'subsystem' ]
[ , [ @command = ] N'command' ]
[ , [ @additional_parameters = ] N'additional_parameters' ]
[ , [ @cmdexec_success_code = ] cmdexec_success_code ]
[ , [ @on_success_action = ] on_success_action ]
[ , [ @on_success_step_id = ] on_success_step_id ]
[ , [ @on_fail_action = ] on_fail_action ]
[ , [ @on_fail_step_id = ] on_fail_step_id ]
[ , [ @server = ] N'server' ]
[ , [ @database_name = ] N'database_name' ]
[ , [ @database_user_name = ] N'database_user_name' ]
[ , [ @retry_attempts = ] retry_attempts ]
[ , [ @retry_interval = ] retry_interval ]
[ , [ @os_run_priority = ] os_run_priority ]
[ , [ @output_file_name = ] N'output_file_name' ]
[ , [ @flags = ] flags ]
[ , [ @proxy_id = ] proxy_id ]
[ , [ @proxy_name = ] N'proxy_name' ]
[ , [ @step_uid = ] 'step_uid' OUTPUT ]
[ ; ]
引数
[ @job_id = ] 'job_id'
ステップを追加するジョブの識別番号を指定します。 @job_id は uniqueidentifier で、既定値は NULL です。
@job_idまたは@job_nameを指定する必要がありますが、両方を指定することはできません。
[ @job_name = ] N'job_name'
ステップを追加するジョブの名前。 @job_name は sysname で、既定値は NULL です。
@job_idまたは@job_nameを指定する必要がありますが、両方を指定することはできません。
[ @step_id = ] step_id
ジョブ ステップのシーケンス ID 番号を指定します。 @step_id は int で、既定値は NULL です。 ステップ識別番号は 1 から始まり、ギャップなしでインクリメントされます。 既存のシーケンスにステップを挿入すると、シーケンス番号が自動的に調整されます。 @step_idが指定されていない場合は、値が指定されます。
[ @step_name = ] N'step_name'
ステップの名前。 @step_name は sysname で、既定値はありません。
[ @subsystem = ] N'subsystem'
@commandを実行するためにSQL Server エージェント サービスによって使用されるサブシステム。 @subsystem は nvarchar(40)であり、これらの値のいずれかを指定できます。
| Value | 説明 |
|---|---|
ActiveScripting |
アクティブ スクリプト 重要: この機能は、今後のバージョンの SQL Server で削除される予定です。 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。 |
CmdExec |
オペレーティング システム コマンドまたは実行可能なプログラム |
Distribution |
レプリケーション ディストリビューション エージェント ジョブ |
Snapshot |
レプリケーション スナップショット エージェント ジョブ |
LogReader |
レプリケーション ログ リーダー エージェント ジョブ |
Merge |
レプリケーション マージ エージェント ジョブ |
QueueReader |
レプリケーション キュー リーダー エージェント ジョブ |
ANALYSISQUERY |
Analysis Services クエリ (MDX、DMX) |
ANALYSISCOMMAND |
Analysis Services コマンド (XMLA) |
SSIS |
Integration Services パッケージの実行 |
PowerShell |
PowerShell スクリプト |
TSQL (既定) |
Transact-SQL ステートメント |
[ @command = ] N'command'
@subsystemを介してSQL Server エージェント サービスによって実行されるコマンド。 @command は nvarchar(max) で、既定値は NULL です。 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 = ] N'additional_parameters'
単に情報を示すためだけに特定されます。 サポートされていません。 将来の互換性は保証されません。
[ @cmdexec_success_code = ] cmdexec_success_code
@commandが正常に実行されたことを示すために、CmdExec サブシステム コマンドによって返される値。 @cmdexec_success_code は int で、既定値は 0 です。
[ @on_success_action = ] on_success_action
ステップが成功した場合に実行するアクション。 @on_success_action は tinyint であり、これらの値のいずれかを指定できます。
| Value | 説明 (アクション) |
|---|---|
1 (既定) |
成功した状態で終了する |
2 |
失敗した状態で終了します。 |
3 |
次のステップに進みます。 |
4 |
手順の @on_success_step_idに移動する |
[ @on_success_step_id = ] on_success_step_id
ステップが成功し、 @on_success_action が 4された場合に実行する、このジョブ内のステップの ID。 @on_success_step_id は int で、既定値は 0 です。
[ @on_fail_action = ] on_fail_action
ステップが失敗した場合に実行するアクション。 @on_fail_action は tinyint であり、これらの値のいずれかを指定できます。
| Value | 説明 (アクション) |
|---|---|
1 |
成功した状態で終了する |
2 (既定) |
失敗した状態で終了します。 |
3 |
次のステップに進みます。 |
4 |
手順 @on_fail_step_idに進む |
[ @on_fail_step_id = ] on_fail_step_id
ステップが失敗し、 @on_fail_action が 4された場合に実行する、このジョブのステップの ID。 @on_fail_step_id は int で、既定値は 0 です。
[ @server = ] N'server'
単に情報を示すためだけに特定されます。 サポートされていません。 将来の互換性は保証されません。
[ @database_name = ] N'database_name'
Transact-SQL ステップを実行するデータベースの名前。 @database_name は sysname で、既定値は NULL です。この場合、 master データベースが使用されます。 角かっこ ([]) で囲まれた名前は使用できません。 ActiveX ジョブ ステップの場合、 @database_name は、ステップで使用されるスクリプト言語の名前です。
[ @database_user_name = ] N'database_user_name'
Transact-SQL ステップの実行時に使用するユーザー アカウントの名前。 @database_user_name は sysname で、既定値は NULL です。 @database_user_nameがNULLされると、@database_nameに対するジョブ所有者のユーザー コンテキストでステップが実行されます。 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 = ] os_run_priority
単に情報を示すためだけに特定されます。 サポートされていません。 将来の互換性は保証されません。
[ @output_file_name = ] N'output_file_name'
この手順の出力が保存されるファイルの名前。 @output_file_name は nvarchar(200) で、既定値は NULL です。 @output_file_name には、 @commandの下に一覧表示されている 1 つ以上のトークンを含めることができます。 このパラメーターは、Transact-SQL、 CmdExec、 PowerShell、Integration Services、または Analysis Services サブシステムで実行されているコマンドでのみ有効です。
[ @flags = ] フラグ
動作を制御するオプション。 @flags は int であり、これらの値のいずれかを指定できます。
| Value | 説明 |
|---|---|
0 (既定値) |
出力ファイルを上書きする |
2 |
出力ファイルに追加する |
4 |
Transact-SQL ジョブ ステップの出力をステップ履歴に書き込む |
8 |
テーブルにログを書き込む (既存の履歴を上書きする) |
16 |
テーブルにログを書き込む (既存の履歴に追加) |
32 |
すべての出力をジョブ履歴に書き込みます。 |
64 |
cmd ジョブ ステップを中止するためのシグナルとして使用する Windows イベントを作成する |
[ @proxy_id = ] proxy_id
ジョブ ステップが実行されるプロキシの ID 番号。 @proxy_id は int で、既定値は NULL です。 @proxy_idが指定されておらず、@proxy_nameも指定されておらず、@database_user_nameも指定されていない場合、ジョブ ステップはSQL Server エージェントのサービス アカウントとして実行されます。
[ @proxy_name = ] N'proxy_name'
ジョブ ステップが実行されるプロキシの名前。 @proxy_name は sysname で、既定値は NULL です。 @proxy_idが指定されておらず、@proxy_nameも指定されておらず、@database_user_nameも指定されていない場合、ジョブ ステップはSQL Server エージェントのサービス アカウントとして実行されます。
[ @step_uid = ] 'step_uid' OUTPUT
@step_uid は、 uniqueidentifier 型の OUTPUT パラメーターです。
リターン コードの値
0 (成功) または 1 (失敗)。
結果セット
ありません。
解説
sp_add_jobstep は、 msdb データベースから実行する必要があります。
SQL Server Management Studio は、簡単かつ直観的な方法でジョブを管理するためのツールで、ジョブ体系の作成および管理に最適です。
既定では、別のプロキシが指定されていない限り、ジョブ ステップはSQL Server エージェントのサービス アカウントとして実行されます。 このアカウントの要件は、 sysadmin 固定セキュリティ ロールのメンバーである必要があります。
プロキシは、 @proxy_name または @proxy_idによって識別される場合があります。
このストアド プロシージャは、azure SQL Database 用の Azure Elastic Jobs サービスの同様のオブジェクトとsp_add_jobstepの名前を共有。 エラスティック ジョブのバージョンについては、「 jobs.sp_add_jobstep (Azure エラスティック ジョブ) (Transact-SQL)」を参照してください。
アクセス許可
このストアド プロシージャは、 db_owner ロールによって所有されています。 EXECUTEアクセス許可は任意のユーザーに付与できますが、SQL Server のアップグレード中にこれらのアクセス許可がオーバーライドされる可能性があります。
他のユーザーには、msdb データベース内の次SQL Server エージェント固定データベース ロールのいずれかを付与する必要があります。
- SQLAgentUserRole
- SQLAgentReaderRole
- SQLAgentOperatorRole
これらのロールの権限の詳細については、「 SQL Server エージェントの固定データベース ロール」を参照してください。
ジョブ ステップの作成者は、ジョブ ステップのプロキシにアクセスできる必要があります。 sysadmin固定サーバー ロールのメンバーは、すべてのプロキシにアクセスできます。 他のユーザーには、プロキシへのアクセス権を明示的に付与する必要があります。
例
次の例では、Sales データベースの読み取り専用にデータベース アクセスを変更するジョブ ステップを作成します。 さらに、この例では 5 回の再試行を指定し、各再試行は 5 分間の待機後に行われます。
Note
この例では、 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
関連するコンテンツ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示