sp_add_jobstep (Transact-SQL)

適用対象: はいSQL Server (サポートされているすべてのバージョン) はいAzure SQL Managed Instance

エージェント ジョブにステップ (操作) SQL追加します。

トピック リンク アイコン Transact-SQL 構文表記規則

重要

Azure SQL Managed Instanceでは、すべての種類のエージェント ジョブSQL Serverほとんどがサポートされているというのではありません。 詳細については、Azure SQL Managed Instance と SQL Server の T-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 ジョブ ステップのシーケンス識別番号。 ステップ識別番号は 1 から始め、 ギャップなしでインクリメントされます。 既存のシーケンスにステップを挿入すると、シーケンス番号が自動的に調整されます。 値が指定されていない場合 step_id 値が指定されます。 step_idは int で、既定値は NULL です。

[ @step_name = ] 'step_name' ステップの名前。 step_nameは sysname で、 既定値はありません。

[ @subsystem = ] 'subsystem' エージェント サービスがコマンド を SQL Server 実行するために使用する サブシステムsubsystemnvarchar(40) で、これらの値の 1 つを指定できます。

説明
'ActiveScripting' アクティブ スクリプト

** 重要 ** この機能は、Microsoft SQL Server の将来のバージョンで削除されます。 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。
'CmdExec' オペレーティング システム コマンドまたは実行可能なプログラム
'ディストリビューション' レプリケーション ディストリビューション エージェント ジョブ
'Snapshot' レプリケーション スナップショット エージェント ジョブ
'LogReader' レプリケーション ログ リーダー エージェント ジョブ
'マージ' レプリケーション マージ エージェント ジョブ
'QueueReader' レプリケーション キュー リーダー エージェント ジョブ
'ANALYSISQUERY' Analysis Servicesクエリ (MDX、DMX)。
'ANALYSISCOMMAND' Analysis Services コマンド (XMLA)
'SSIS' Integration Services パッケージ実行
'PowerShell' PowerShell スクリプト
'TSQL' (既定値) Transact-SQL ステートメント

[ @command = ] 'command' サブシステム を介して SQLServerAgent サービスによって実行 される コマンドコマンドnvarchar(max) で、既定値は NULL です。 SQL Server エージェントでは、ソフトウェア プログラムを記述するときの変数と同じような柔軟性を持つトークン置換を使用できます。

重要

エスケープ マクロは、ジョブ ステップで使用されるトークンすべてと一緒に使用する必要があります。それ以外の場合、それらのジョブ ステップは失敗します。 さらに、トークン名をかっこで囲み、トークン構文の先頭にドル記号 ( ) を配置 $ する必要があります。 次に例を示します。

$(ESCAPE_マクロ名 (DATE))

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

重要

Windows イベント ログに対して書き込みのアクセス許可を持っている Windows ユーザーであればだれでも、 SQL Server エージェントの警告または WMI 警告によってアクティブ化されるジョブ ステップにアクセスできます。 このセキュリティ上のリスクを避けるために、警告によってアクティブになるジョブで使用できる SQL Server エージェント トークンは、既定で無効になっています。 このようなトークンには、A-DBNA-SVRA-ERRA-SEVA-MSGWMI( property ) があります。 このリリースでは、トークンの使用はすべての警告に拡張されていることに注意してください。

これらのトークンを使用する必要がある場合は、まず、Administrators グループなどの信頼されている Windows セキュリティ グループのメンバーのみが、 SQL Server が存在するコンピューターのイベント ログに対して書き込みのアクセス許可を持っていることを確認してください。 確認したら、[オブジェクト エクスプローラー] で [SQL Server エージェント] を右クリックし、 [プロパティ] をクリックします。次に、 [警告システム] ページで、 [警告に応答するすべてのジョブのトークンを置き換える] チェック ボックスをオンにして、これらのトークンを有効にします。

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

[ @cmdexec_success_code = ] code コマンドが正常に実行されたことを示すために CmdExec サブシステム コマンド によって返される 値。 codeint で、既定値は 0 です

[ @on_success_action = ] success_action ステップが成功した場合に実行するアクション。 success_action tinyint であり、これらの値の 1 つを指定できます。

説明 (アクション)
1 (既定値) 成功して終了する
2 失敗した状態で終了します。
3 次のステップに進みます。
4 手順に進 on_success_step_id

[ @on_success_step_id = ] success_step_idステップが成功し、ステップが 4 の場合に実行 success_actionID。 success_step_id int で、 既定値は 0 です

[ @on_fail_action = ] fail_action ステップが失敗した場合に実行するアクション。 fail_action tinyint であり、これらの値の 1 つを指定できます。

説明 (アクション)
1 成功して終了する
2 (既定値) 失敗した状態で終了します。
3 次のステップに進みます。
4 手順に進 on_fail_step_id

[ @on_fail_step_id = ] fail_step_idステップが失敗し、ステップが 4 の場合に実行 fail_actionのID。 fail_step_id int で、 既定値は 0 です

[ @server = ] 'server'単に情報を示すためだけに特定されます。 サポートされていません。 将来の互換性は保証されません。 servernvarchar(30) で、既定値は NULL です。

[ @database_name = ] 'database' ステップを実行するデータベースの Transact-SQL 名前。 databasesysname で、既定値は NULL です。この場合 、master データベースが使用されます。 角かっこ ([ ]) で囲まれた名前は使用されません。 ジョブ ステップActiveX、データベースはステップ で使用されるスクリプト言語の名前です。

[ @database_user_name = ] 'user' ステップの実行時に使用するユーザー アカウントの Transact-SQL 名前。 usersysname で、既定値は NULL です。 ユーザー NULL の場合、ステップはデータベース のジョブ所有者のユーザー コンテキストで実行 されます。 SQL Serverは、ジョブ所有者が sysadmin の管理者である場合にのみ、このSQL Serverされます。 その場合、指定された 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 コマンド の下に一覧表示されている 1 つ以上のトークンを含 めできます。 このパラメーターは Transact-SQL 、、CmdExec、PowerShell、 または サブシステムで実行されているコマンド Integration Services でのみ Analysis Services 有効です。

[ @flags = ] flags 動作を制御するオプションです。 flagsint であり、これらの値の 1 つを指定できます。

説明
0 (既定値) 出力ファイルを上書きする
2 出力ファイルに追加する
4 ステップ Transact-SQL 履歴へのジョブ ステップ出力の書き込み
8 テーブルにログを書き込む (既存の履歴を上書きする)
16 テーブルにログを書き込む (既存の履歴に追加)
32 すべての出力をジョブ履歴に書き込みます。
64 Cmd ジョブ ステップWindows中止するシグナルとして使用する新しいイベントを作成する

[ @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 エージェントのサービス アカウントとして実行されます。 このアカウントの要件は 、sysadmin 固定セキュリティ ロールのメンバーである必要があります。

プロキシは、 または で識別 proxy_name 場合 proxy_id。

アクセス許可

既定では、このストアド プロシージャを実行できるのは、 sysadmin 固定サーバー ロールのメンバーです。 他のユーザーには、 SQL Server msdb データベースの次のいずれかの エージェント固定データベース ロールが許可されている必要があります。

  • 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

次のステップ