jobs.sp_add_jobstep (Azure エラスティック ジョブ) (Transact-SQL)
適用対象:
Azure SQL Database
Azure SQL Database の Azure エラスティック ジョブ サービスの既存のジョブに ステップを追加します。 jobs.sp_update_jobstepを使用して、既存のエラスティック ジョブ ステップを変更します。
このストアド プロシージャは、SQL Server エージェント サービスの sp_add_jobstep SQL Server の同様のオブジェクトと名前を共有します。 SQL Server エージェントバージョンの詳細については、「sp_add_jobstep (Transact-SQL)」を参照してください。
構文
[jobs].sp_add_jobstep [ @job_name = ] 'job_name'
[ , [ @step_id = ] step_id ]
[ , [ @step_name = ] step_name ]
[ , [ @command_type = ] 'command_type' ]
[ , [ @command_source = ] 'command_source' ]
, [ @command = ] 'command'
[, [ @credential_name = ] 'credential_name' ]
, [ @target_group_name = ] 'target_group_name'
[ , [ @initial_retry_interval_seconds = ] initial_retry_interval_seconds ]
[ , [ @maximum_retry_interval_seconds = ] maximum_retry_interval_seconds ]
[ , [ @retry_interval_backoff_multiplier = ] retry_interval_backoff_multiplier ]
[ , [ @retry_attempts = ] retry_attempts ]
[ , [ @step_timeout_seconds = ] step_timeout_seconds ]
[ , [ @output_type = ] 'output_type' ]
[ , [ @output_credential_name = ] 'output_credential_name' ]
[ , [ @output_subscription_id = ] 'output_subscription_id' ]
[ , [ @output_resource_group_name = ] 'output_resource_group_name' ]
[ , [ @output_server_name = ] 'output_server_name' ]
[ , [ @output_database_name = ] 'output_database_name' ]
[ , [ @output_schema_name = ] 'output_schema_name' ]
[ , [ @output_table_name = ] 'output_table_name' ]
[ , [ @job_version = ] job_version OUTPUT ]
[ , [ @max_parallelism = ] max_parallelism ]
引数
@job_name
ステップを追加するジョブの名前。 job_nameは nvarchar(128) です。
@step_id
ジョブ ステップのシーケンス ID 番号を指定します。 ステップ ID 番号は 1 から始まり、隙間なく増加します。 既存のステップにこの ID が既に含まれている場合、そのステップとその後のすべてのステップで ID がインクリメントされ、この新しいステップをシーケンスに挿入できるようになります。 指定しない場合、 step_id は一連の手順で最後に自動的に割り当てられます。 step_idは int です。
@step_name
ステップの名前。 (便宜上) 既定の名前 JobStepを持つジョブの最初のステップを除き、指定する必要があります。 step_nameは nvarchar(128) です。
@command_type
このジョブ ステップによって実行されるコマンドの種類。 command_typeは nvarchar(50) で、既定値は TSql@command_type パラメーターの値が T-SQL スクリプトであることを意味します。
指定する場合、値 TSqlは .
@command_source
コマンドが格納される場所の種類。 command_sourceは nvarchar(50) で、既定値は Inline@command パラメーターの値がコマンドのリテラル テキストであることを意味します。
指定する場合、値 Inlineは .
@command
このジョブ ステップで実行される有効な T-SQL スクリプト。 コマンド は nvarchar(max) で、既定値は NULL.
@credential_name
このステップの実行時にターゲット グループ内の各ターゲット データベースに接続するために使用される、このジョブ 制御データベースに格納されているデータベース スコープの資格情報の名前。 credential_nameは nvarchar(128) です。
Microsoft Entra 認証 (旧称 Azure Active Directory) を使用する場合は、@credential_name パラメーターを省略します。これは、データベース スコープの資格情報を使用する場合にのみ指定する必要があります。
@target_group_name
ジョブ ステップが実行されるターゲット データベースを含むターゲット グループの名前。 target_group_nameは nvarchar(128) です。
@initial_retry_interval_seconds
ジョブ ステップの最初の実行の試行が失敗した場合に、最初の再試行を試みるまでの遅延。 initial_retry_interval_secondsは int で、既定値は 1 です。
@maximum_retry_interval_seconds
再試行の間の最大遅延。 再試行の間の遅延がこの値より大きくなった場合は、この値に制限されます。 maximum_retry_interval_secondsは int で、既定値は 120 です。
@retry_interval_backoff_multiplier
ジョブ ステップの実行が複数回にわたり失敗した場合に、再試行の遅延に適用する乗数。 たとえば、最初の再試行の遅延が 5 秒で、バックオフ乗数が 2.0 の場合、2 回目の再試行の遅延は 10 秒、3 回目の再試行の遅延は 20 秒になります。 retry_interval_backoff_multiplierは実際のデータ型で、既定値は 2.0 です。
@retry_attempts
最初の試行が失敗した場合に、実行を再試行する回数。 たとえば、retry_attempts値が 10 の場合、最初の試行は 1 回、再試行回数は 10 回になり、合計で 11 回の試行が行われます。 最後の再試行が失敗した場合、ジョブの実行は jobs.job_executions に記録された状態Failedで終了lifecycleします。 retry_attemptsは int で、既定値は 10 です。
@step_timeout_seconds
ステップの実行に許可されている最大時間。 この時間を超えた場合、ジョブの実行は jobs.job_executions に記録された状態TimedOutで終了lifecycleします。 step_timeout_secondsは int で、既定値は 43,200 秒 (12 時間) です。
@output_type
そうでないNULL場合は、コマンドの最初の結果セットの書き込み先の型。 output_typeは nvarchar(50) で、既定値は NULL.
指定する場合、値 SqlDatabaseは .
@output_credential_name
null でない場合、出力先データベースへの接続に使用されるデータベース スコープの資格情報の名前。 output_typeが等しい場合 は 、指定する SqlDatabase必要があります。 output_credential_nameは nvarchar(128) で、既定値は NULL.
Microsoft Entra 認証 (旧称 Azure Active Directory) を使用する場合は、@output_credential_name パラメーターを省略します。これは、データベース スコープの資格情報を使用する場合にのみ指定する必要があります。
@output_subscription_id
出力に使用する Azure サブスクリプション ID。 既定では、ジョブ エージェントのサブスクリプションが使用されます。 output_subscription_idは uniqueidentifier です。
@output_resource_group_name
出力データベースが存在するリソース グループの名前。 既定では、ジョブ エージェントのリソース グループが使用されます。 output_resource_group_nameは nvarchar(128) です。
@output_server_name
そうでないNULL場合は、出力先データベースを含むサーバーの完全修飾 DNS 名 。例: @output_server_name = 'server1.database.windows.net' output_typeが等しい場合 は 、指定する SqlDatabase必要があります。 output_server_nameは nvarchar(256) で、既定値は NULL.
@output_database_name
そうでない NULL場合は、出力先テーブルを含むデータベースの名前。 output_typeが等しい場合 は 、指定する SqlDatabase必要があります。 output_database_nameは nvarchar(128) で、既定値は NULL.
@output_schema_name
そうでない NULL場合は、出力先テーブルを含む SQL スキーマの名前。 output_typeが等しいSqlDatabase場合、既定値は dbo. output_schema_nameは nvarchar(128) です。
@output_table_name
そうでないNULL場合は、コマンドの最初の結果セットの書き込み先となるテーブルの名前。 テーブルがまだ存在しない場合は、返される結果セットのスキーマに基づいて作成されます。 output_typeが等しい場合 は 、指定する SqlDatabase必要があります。 output_table_nameは nvarchar(128) で、既定値は NULL.
output_table_nameを指定する場合は、ジョブ エージェント UMI またはデータベース スコープの資格情報に、テーブルへの CREATE TABLE および IN Standard Edition RT データに対する必要なアクセス許可を付与する必要があります。
@job_version 出力
新しいジョブのバージョン番号が割り当てられる出力パラメーター。 job_versionは int です。
@max_parallelism 出力
エラスティック プールあたりの並列処理の最大レベル。
設定した場合、ジョブ ステップはエラスティック プールあたり最大でもその指定数のデータベースでのみ実行するように制限されます。 これは、ターゲット グループに直接含まれる各エラスティック プール、またはターゲット グループに含まれるサーバー内に存在するエラスティック プールに適用されます。 max_parallelismは int です。
リターン コードの値
0 (成功) または 1 (失敗)
解説
成功すると sp_add_jobstep 、ジョブの現在のバージョン番号がインクリメントされます。 次にジョブを実行するときは、新しいバージョンが使われます。 ジョブが現在実行中の場合、その実行には新しいステップは含まれません。
- Microsoft Entra 認証を使用してターゲット サーバー/データベースに対する認証を行う場合、@credential_name引数と @output_credential_name 引数は指定
sp_add_jobstepsp_update_jobstepしないでください。 - データベース スコープの資格情報を使用してターゲット サーバー/データベースに対する認証を行う場合、
sp_add_jobstepおよびsp_update_jobstepには @credential_name パラメーターが必要です。 たとえば、@credential_name = 'job_credential'のようにします。
アクセス許可
既定では、このストアド プロシージャを実行できるのは、 sysadmin 固定サーバー ロールのメンバーです。 このストアド プロシージャを使って、他のユーザーが所有するジョブの属性を編集できるのは、sysadmin のメンバーだけです。
例
T-SQL ステートメントを実行するジョブ ステップを作成する
次の例は、エラスティック ジョブで T-SQL ステートメントを実行するエラスティック ジョブを作成する方法を示しています。 次の例では、ターゲット グループPoolGroupで実行される 、という名前CreateTableTestのジョブにジョブ ステップを作成するために使用jobs.sp_add_jobstepします。
job_database に接続して、次のコマンドを実行します。
--Connect to the job database specified when creating the job agent
--Add job for create table
EXEC jobs.sp_add_job @job_name = 'CreateTableTest', @description = 'Create Table Test';
-- Add job step for create table
EXEC jobs.sp_add_jobstep @job_name = 'CreateTableTest',
@command = N'IF NOT EXISTS (SELECT * FROM sys.tables WHERE object_id = object_id(''Test''))
CREATE TABLE [dbo].[Test]([TestId] [int] NOT NULL);',
@target_group_name = 'PoolGroup';
T-SQL ステートメントを実行して結果を収集するジョブ ステップを作成する
次の例は、エラスティック ジョブで T-SQL ステートメントを実行し、Azure SQL Database で結果を収集するエラスティック ジョブを作成する方法を示しています。 次の例では、ターゲット グループPoolGroupで実行される 、という名前ResultsJobのジョブにジョブ ステップを作成するために使用jobs.sp_add_jobstepします。 結果は、サーバーで指定されたデータベースに名前が付けられたdbo.results_tableResultsテーブルに記録されますserver1.database.windows.net。
--Connect to the job database specified when creating the job agent
-- Add a job to collect perf results
EXEC jobs.sp_add_job @job_name ='ResultsJob', @description='Collection Performance data from all customers'
-- Add a job step w/ schedule to collect results
EXEC jobs.sp_add_jobstep
@job_name = 'ResultsJob',
@command = N' SELECT DB_NAME() DatabaseName, $(job_execution_id) AS job_execution_id, * FROM sys.dm_db_resource_stats WHERE end_time > DATEADD(mi, -20, GETDATE());',
@target_group_name = 'PoolGroup',
@output_type = 'SqlDatabase',
@output_server_name = 'server1.database.windows.net',
@output_database_name = 'Results',
@output_schema_name = 'dbo',
@output_table_name = 'results_table';
関連するコンテンツ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示