sp_add_jobstep (Transact-SQL)sp_add_jobstep (Transact-SQL)

適用対象: yesSQL Server yesAzure SQL Database (Managed Instance のみ) noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database (Managed Instance only) noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

SQL エージェントジョブにステップ (操作) を追加します。Adds a step (operation) to a SQL Agent job.

トピックリンクアイコン Transact-sql 構文表記規則Topic link icon Transact-SQL Syntax Conventions

重要

Azure SQL Database Managed Instanceでは、ほとんどの SQL Server エージェントジョブの種類はサポートされていません。On Azure SQL Database Managed Instance, most, but not all SQL Server Agent job types are supported. 詳細については、「Azure SQL Database Managed Instance t-sql の相違 SQL Server 点」を参照してください。See Azure SQL Database Managed Instance T-SQL differences from SQL Server for details.

構文Syntax

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' } ]  

引数Arguments

[ @job_id = ] job_idステップを追加するジョブの識別番号を指定します。[ @job_id = ] job_id The identification number of the job to which to add the step. job_iduniqueidentifier,、既定値は NULL です。job_id is uniqueidentifier, with a default of NULL.

[ @job_name = ] 'job_name'ステップを追加するジョブの名前を指定します。[ @job_name = ] 'job_name' The name of the job to which to add the step. job_namesysname,、既定値は NULL です。job_name is sysname, with a default of NULL.

注意

Job_idまたはjob_nameのいずれかを指定する必要がありますが、両方を指定することはできません。Either job_id or job_name must be specified, but both cannot be specified.

[ @step_id = ] step_idジョブステップのシーケンス識別番号を指定します。[ @step_id = ] step_id The sequence identification number for the job step. ステップの識別番号は1から始まり、ギャップなしで増分されます。Step identification numbers start at 1 and increment without gaps. 既存のシーケンスにステップを挿入すると、シーケンス番号が自動的に調整されます。If a step is inserted in the existing sequence, the sequence numbers are adjusted automatically. Step_idが指定されていない場合は、値が指定されます。A value is provided if step_id is not specified. step_idint,、既定値は NULL です。step_id is int, with a default of NULL.

[ @step_name = ] 'step_name'ステップの名前。[ @step_name = ] 'step_name' The name of the step. step_namesysnameであり、既定値はありません。step_name is sysname, with no default.

[ @subsystem = ] 'subsystem'エージェントサービスがSQL ServerSQL Server コマンドを実行するために使用するサブシステム。[ @subsystem = ] 'subsystem' The subsystem used by the SQL ServerSQL Server Agent service to execute command. サブシステムnvarchar (40),、これらの値のいずれかを指定することができます。subsystem is nvarchar(40), and can be one of these values.

Value 説明Description
'ACTIVESCRIPTING''ACTIVESCRIPTING' アクティブスクリプトActive Script

** *重要* * **この機能はメンテナンス モードであり、Microsoft SQL Server の将来のバージョンで削除される可能性があります。This feature is in maintenance mode and may be removed in a future version of Microsoft SQL Server. 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。Avoid using this feature in new development work, and plan to modify applications that currently use this feature.** Important ** この機能はメンテナンス モードであり、Microsoft SQL Server の将来のバージョンで削除される可能性があります。This feature is in maintenance mode and may be removed in a future version of Microsoft SQL Server. 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。Avoid using this feature in new development work, and plan to modify applications that currently use this feature.
'CMDEXEC''CMDEXEC' オペレーティング システム コマンドまたは実行可能なプログラムOperating-system command or executable program
'DISTRIBUTION''DISTRIBUTION' レプリケーションディストリビューションエージェントジョブReplication Distribution Agent job
'SNAPSHOT''SNAPSHOT' レプリケーションスナップショットエージェントジョブReplication Snapshot Agent job
"ログリーダー"'LOGREADER' レプリケーションログリーダーエージェントジョブReplication Log Reader Agent job
'MERGE''MERGE' レプリケーション マージ エージェント ジョブReplication Merge Agent job
'QueueReader''QueueReader' レプリケーションキューリーダーエージェントジョブReplication Queue Reader Agent job
'ANALYSISQUERY''ANALYSISQUERY' Analysis Services クエリ (MDX、DMX)。Analysis Services query (MDX, DMX).
'ANALYSISCOMMAND''ANALYSISCOMMAND' Analysis Services コマンド (XMLA)Analysis Services command (XMLA).
'Dts''Dts' Integration ServicesIntegration Servicesパッケージの実行package execution
'PowerShell''PowerShell' PowerShell スクリプトPowerShell Script
'TSQL' (既定値)'TSQL' (default) Transact-SQLTransact-SQL諸表statement

[ @command = ] 'command'サブシステムを介してSQLServerAgentサービスによって実行されるコマンドです。[ @command = ] 'command' The commands to be executed by SQLServerAgent service through subsystem. コマンドnvarchar (max),、既定値は NULL です。command is nvarchar(max), with a default of NULL. SQL Server エージェントでは、ソフトウェア プログラムを記述するときの変数と同じような柔軟性を持つトークン置換を使用できます。SQL Server Agent provides token substitution that gives you the same flexibility that variables provide when you write software programs.

重要

エスケープマクロには、ジョブステップで使用されるすべてのトークンが含まれている必要があります。そうでない場合、これらのジョブステップは失敗します。An escape macro must now accompany all tokens used in job steps, or else those job steps will fail. さらに、トークン名をかっこで囲み、トークン構文の先頭にドル記号$() を付ける必要があります。In addition, you must now enclose token names in parentheses and place a dollar sign ($) at the beginning of the token syntax. 例:For example:

$(ESCAPE_マクロ名(DATE))$(ESCAPE_ macro name (DATE))

これらのトークンの詳細と、新しいトークン構文を使用するジョブステップの更新については、「ジョブステップでのトークンの使用」を参照してください。For more information about these tokens and updating your job steps to use the new token syntax, see Use Tokens in Job Steps.

重要

Windows イベント ログに対して書き込みのアクセス許可を持っている Windows ユーザーであればだれでも、 SQL ServerSQL Server エージェントの警告または WMI 警告によってアクティブ化されるジョブ ステップにアクセスできます。Any Windows user with write permissions on the Windows Event Log can access job steps that are activated by SQL ServerSQL Server Agent alerts or WMI alerts. このセキュリティ上のリスクを避けるために、警告によってアクティブになるジョブで使用できる SQL ServerSQL Server エージェント トークンは、既定で無効になっています。To avoid this security risk, SQL ServerSQL Server Agent tokens that can be used in jobs activated by alerts are disabled by default. これらのトークンは次のとおりです。- DBN-SVR-ERR重大度a-MSG、およびWMI (プロパティ)These tokens are: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG., and WMI(property). このリリースでは、トークンの使用はすべての警告に拡張されていることに注意してください。Note that in this release, use of tokens is extended to all alerting.

これらのトークンを使用する必要がある場合は、まず、Administrators グループなどの信頼されている Windows セキュリティ グループのメンバーのみが、 SQL ServerSQL Server が存在するコンピューターのイベント ログに対して書き込みのアクセス許可を持っていることを確認してください。If you need to use these tokens, first ensure that only members of trusted Windows security groups, such as the Administrators group, have write permissions on the Event Log of the computer where SQL ServerSQL Server resides. 確認したら、[オブジェクト エクスプローラー] で [SQL Server エージェント] を右クリックし、 [プロパティ] をクリックします。次に、 [警告システム] ページで、 [警告に応答するすべてのジョブのトークンを置き換える] チェック ボックスをオンにして、これらのトークンを有効にします。Then, right-click SQL Server Agent in Object Explorer, select Properties, and on the Alert System page, select Replace tokens for all job responses to alerts to enable these tokens.

[ @additional_parameters = ] 'parameters'単に情報を示すためだけに特定されます。Identified for informational purposes only. サポートされていません。Not supported. 将来の互換性は保証されません。Future compatibility is not guaranteed. パラメーターntext,、既定値は NULL です。[ @additional_parameters = ] 'parameters' 単に情報を示すためだけに特定されます。Identified for informational purposes only. サポートされていません。Not supported. 将来の互換性は保証されません。Future compatibility is not guaranteed. parameters is ntext, with a default of NULL.

[ @cmdexec_success_code = ] codeコマンドが正常に実行されたことを示すために、 CmdExecサブシステムコマンドによって返される値。[ @cmdexec_success_code = ] code The value returned by a CmdExec subsystem command to indicate that command executed successfully. コードint,、既定値は0です。code is int, with a default of 0.

[ @on_success_action = ] success_actionステップが成功した場合に実行するアクション。[ @on_success_action = ] success_action The action to perform if the step succeeds. success_actiontinyintで、次のいずれかの値を指定できます。success_action is tinyint, and can be one of these values.

Value 説明 (アクション)Description (action)
1 (既定値)1 (default) 成功時に終了Quit with success
32 失敗した状態で終了します。Quit with failure
3 次のステップに進みます。Go to next step
4/44 手順に進むon_success_step_idGo to step on_success_step_id

[ @on_success_step_id = ] success_step_idステップが成功しsuccess_action4の場合に実行する、このジョブのステップの ID。[ @on_success_step_id = ] success_step_id The ID of the step in this job to execute if the step succeeds and success_action is 4. success_step_idint,、既定値は0です。success_step_id is int, with a default of 0.

[ @on_fail_action = ] fail_actionステップが失敗した場合に実行するアクション。[ @on_fail_action = ] fail_action The action to perform if the step fails. fail_actiontinyintで、次のいずれかの値を指定できます。fail_action is tinyint, and can be one of these values.

Value 説明 (アクション)Description (action)
1 で保護されたプロセスとして起動されました1 成功時に終了Quit with success
2 (既定値)2 (default) 失敗した状態で終了します。Quit with failure
3 次のステップに進みます。Go to next step
4/44 手順に進むon_fail_step_idGo to step on_fail_step_id

[ @on_fail_step_id = ] fail_step_idステップが失敗し、 fail_action4の場合に実行する、このジョブのステップの ID。[ @on_fail_step_id = ] fail_step_id The ID of the step in this job to execute if the step fails and fail_action is 4. fail_step_idint,、既定値は0です。fail_step_id is int, with a default of 0.

[ @server = ] 'server'単に情報を示すためだけに特定されます。Identified for informational purposes only. サポートされていません。Not supported. 将来の互換性は保証されません。Future compatibility is not guaranteed. サーバーnvarchar (30),、既定値は NULL です。[ @server = ] 'server' 単に情報を示すためだけに特定されます。Identified for informational purposes only. サポートされていません。Not supported. 将来の互換性は保証されません。Future compatibility is not guaranteed. server is nvarchar(30), with a default of NULL.

[ @database_name = ] 'database'ステップをTransact-SQLTransact-SQL実行するデータベースの名前です。[ @database_name = ] 'database' The name of the database in which to execute a Transact-SQLTransact-SQL step. データベースのデータ型はsysnameで、既定値は NULL です。この場合、 masterデータベースが使用されます。database is sysname, with a default of NULL, in which case the master database is used. 角かっこ ([]) で囲まれた名前は使用できません。Names that are enclosed in brackets ([ ]) are not allowed. ActiveX ジョブステップの場合、データベースは、ステップで使用するスクリプト言語の名前です。For an ActiveX job step, the database is the name of the scripting language that the step uses.

[ @database_user_name = ] 'user'Transact-SQLTransact-SQLステップの実行時に使用するユーザーアカウントの名前。[ @database_user_name = ] 'user' The name of the user account to use when executing a Transact-SQLTransact-SQL step. userの部分はsysnameで、既定値は NULL です。user is sysname, with a default of NULL. ユーザーが NULL の場合、ステップはデータベースのジョブ所有者のユーザーコンテキストで実行されます。When user is NULL, the step runs in the job owner's user context on database. このパラメーターは、ジョブの所有者が SQL Server sysadmin である場合にのみ SQL Server エージェントに含まれます。SQL Server Agent will include this parameter only if the job owner is a SQL Server sysadmin. その場合、指定された Transact-sql ステップは、指定された SQL Server ユーザー名のコンテキストで実行されます。If so, the given Transact-SQL step will be executed in the context of the given SQL Server user name. ジョブの所有者が SQL Server sysadmin でない場合、Transact-sql ステップは常にこのジョブを所有するログインのコンテキストで実行され、 @database_user_nameパラメーターは無視されます。If the job owner is not a SQL Server sysadmin, then the Transact-SQL step will always be executed in the context of the login that owns this job, and the @database_user_name parameter will be ignored.

[ @retry_attempts = ] retry_attemptsこのステップが失敗した場合に使用する再試行回数。[ @retry_attempts = ] retry_attempts The number of retry attempts to use if this step fails. retry_attemptsint,、既定値は0,、これは再試行がないことを示します。retry_attempts is int, with a default of 0, which indicates no retry attempts.

[ @retry_interval = ] retry_interval再試行の間隔 (分) です。[ @retry_interval = ] retry_interval The amount of time in minutes between retry attempts. retry_intervalint,、既定値は0,、 0分間隔を示します。retry_interval is int, with a default of 0, which indicates a 0-minute interval.

[ @os_run_priority = ] run_priority確保.[ @os_run_priority = ] run_priority Reserved.

[ @output_file_name = ] 'file_name'このステップの出力が保存されるファイルの名前。[ @output_file_name = ] 'file_name' The name of the file in which the output of this step is saved. file_namenvarchar (200),、既定値は NULL です。file_name is nvarchar(200), with a default of NULL. file_nameには、[コマンド] に一覧表示されているトークンを1つ以上含めることができます。file_name can include one or more of the tokens listed under command. Transact-SQLTransact-SQLこのパラメーターは、、 CmdExecPowerShellIntegration ServicesIntegration Services、またはAnalysis ServicesAnalysis Servicesサブシステムで実行されているコマンドでのみ有効です。This parameter is valid only with commands running on the Transact-SQLTransact-SQL, CmdExec, PowerShell, Integration ServicesIntegration Services, or Analysis ServicesAnalysis Services subsystems.

[ @flags = ] flagsは、動作を制御するオプションです。[ @flags = ] flags Is an option that controls behavior. フラグint,、これらの値のいずれかを指定できます。flags is int, and can be one of these values.

Value 説明Description
0 (既定値)0 (default) 出力ファイルを上書きするOverwrite output file
32 出力ファイルに追加Append to output file
4/44 ジョブTransact-SQLTransact-SQLステップの出力をステップ履歴に書き込むWrite Transact-SQLTransact-SQL job step output to step history
88 テーブルにログを書き込む (既存の履歴を上書きする)Write log to table (overwrite existing history)
まで16 ログをテーブルに書き込む (既存の履歴に追加する)Write log to table (append to existing history)
3232 すべての出力をジョブ履歴に書き込みます。Write all output to job history
6464 Windows イベントを作成して、Cmd jobstep が中止するシグナルとして使用するCreate a Windows event to use as a signal for the Cmd jobstep to abort

[ @proxy_id = ] proxy_idジョブステップを実行するプロキシの id 番号を指定します。[ @proxy_id = ] proxy_id The id number of the proxy that the job step runs as. proxy_idの型はintで、既定値は NULL です。proxy_id is type int, with a default of NULL. Proxy_idが指定されておらず、 proxy_nameが指定されておらず、 user_nameが指定されていないSQL ServerSQL Server場合、ジョブステップはエージェントのサービスアカウントとして実行されます。If no proxy_id is specified, no proxy_name is specified, and no user_name is specified, the job step runs as the service account for SQL ServerSQL Server Agent.

[ @proxy_name = ] 'proxy_name'ジョブステップを実行するプロキシの名前を指定します。[ @proxy_name = ] 'proxy_name' The name of the proxy that the job step runs as. proxy_nameの型はsysnameで、既定値は NULL です。proxy_name is type sysname, with a default of NULL. Proxy_idが指定されておらず、 proxy_nameが指定されておらず、 user_nameが指定されていないSQL ServerSQL Server場合、ジョブステップはエージェントのサービスアカウントとして実行されます。If no proxy_id is specified, no proxy_name is specified, and no user_name is specified, the job step runs as the service account for SQL ServerSQL Server Agent.

リターン コードの値Return Code Values

0 (成功) または1 (失敗)0 (success) or 1 (failure)

結果セットResult Sets

NoneNone

コメントRemarks

sp_add_jobstepは、 msdbデータベースから実行する必要があります。sp_add_jobstep must be run from the msdb database.

SQL Server Management Studio は、簡単かつ直観的な方法でジョブを管理するためのツールで、ジョブ体系の作成および管理に最適です。SQL Server Management Studio provides an easy, graphical way to manage jobs, and is the recommended way to create and manage the job infrastructure.

既定では、別のプロキシが指定されていSQL ServerSQL Serverない限り、ジョブステップはエージェントのサービスアカウントとして実行されます。By default, a job step will run as the service account for SQL ServerSQL Server Agent unless another proxy is specified. このアカウントの要件は、 sysadmin固定セキュリティロールのメンバーである必要があります。A requirement of this account is to be a member of the sysadmin fixed security role.

プロキシはproxy_nameまたはproxy_idによって識別できます。A proxy may be identified by proxy_name or proxy_id.

アクセス許可Permissions

既定では、 sysadmin固定サーバーロールのメンバーは、このストアドプロシージャを実行できます。By default, members of the sysadmin fixed server role can execute this stored procedure. 他のユーザーには、 SQL ServerSQL Server msdb データベースの次のいずれかの エージェント固定データベース ロールが許可されている必要があります。Other users must be granted one of the following SQL ServerSQL Server Agent fixed database roles in the msdb database:

  • SQLAgentUserRoleSQLAgentUserRole

  • SQLAgentReaderRoleSQLAgentReaderRole

  • SQLAgentOperatorRoleSQLAgentOperatorRole

これらのロールの権限の詳細については、「 SQL Server エージェントの固定データベース ロール」を参照してください。For details about the permissions of these roles, see SQL Server Agent Fixed Database Roles.

ジョブステップの作成者は、ジョブステップのプロキシへのアクセス権を持っている必要があります。The creator of the job step must have access to the proxy for the job step. Sysadmin固定サーバーロールのメンバーは、すべてのプロキシにアクセスできます。Members of the sysadmin fixed server role have access to all proxies. 他のユーザーには、明示的にプロキシへのアクセスを許可する必要があります。Other users must be explicitly granted access to a proxy.

Examples

次の例では、Sales データベースのデータベースアクセスを読み取り専用に変更するジョブステップを作成します。The following example creates a job step that changes database access to read-only for the Sales database. さらに、この例では、5分間待機した後に再試行が5回発生する5回の再試行が指定されています。In addition, this example specifies 5 retry attempts, with each retry to occur after a 5 minute wait.

注意

この例では、 Weekly Sales Data Backupジョブが既に存在していることを前提としています。This example assumes that the Weekly Sales Data Backup job already exists.

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  

参照See Also

ジョブの表示または変更 View or Modify Jobs
sp_add_job (Transact-sql) sp_add_job (Transact-SQL)
sp_add_schedule (Transact-sql) sp_add_schedule (Transact-SQL)
sp_delete_jobstep (Transact-sql) sp_delete_jobstep (Transact-SQL)
sp_help_job (Transact-sql) sp_help_job (Transact-SQL)
sp_help_jobstep (Transact-sql) sp_help_jobstep (Transact-SQL)
sp_update_jobstep (Transact-sql) sp_update_jobstep (Transact-SQL)
システムストアドプロシージャ (Transact-sql)System Stored Procedures (Transact-SQL)