sp_add_jobstep (Transact-SQL)
適用対象: 
SQL ServerAzure 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-DBNA-SVRA-ERRA-SEVA-MSGWMI(<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
ステップが成功し4、@on_success_actionが . @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
ステップが失敗し4、@on_fail_actionが . @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-minute 間隔を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、、Integration Services、CmdExecPowerShellまたは Analysis Services サブシステムで実行されているコマンドでのみ有効です。
[ @flags = ] フラグ
動作を制御するオプション。 @flagsは int であり、これらの値のいずれかになります。
| Value | 説明 |
|---|---|
0 (既定値) |
出力ファイルを上書きする |
2 |
出力ファイルに追加する |
4 |
Transact-SQL ジョブ ステップの出力をステップ履歴に書き込む |
8 |
テーブルにログを書き込む (既存の履歴を上書きする) |
16 |
テーブルにログを書き込む (既存の履歴に追加) |
32 |
すべての出力をジョブ履歴に書き込みます。 |
64 |
ジョブ ステップを中止するためのシグナルとして使用する Windows イベントを cmd 作成する |
[ @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 の sp_add_jobstep Azure Elastic Jobs サービスの同様の オブジェクトと名前を共有します。 エラスティック ジョブのバージョンについては、「jobs.sp_add_jobstep (Azure エラスティック ジョブ) (Transact-SQL)」を参照してください。
アクセス許可
このストアド プロシージャは、db_owner ロールによって所有されています。 任意のユーザーにアクセス許可を付与 EXECUTE できますが、SQL Server のアップグレード中にこれらのアクセス許可がオーバーライドされる可能性があります。
他のユーザーには、データベース内の固定データベース ロールSQL Server エージェント次のいずれかを付与するmsdb必要があります。
- 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」を参照してください。
フィードバックの送信と表示