jobs.sp_add_jobstep (Azure エラスティックジョブ) (Transact-SQL)

[アーティクル]
08/21/2024

Azure SQL Database の Azure エラスティックジョブサービスの既存のジョブにステップを追加します。 jobs.sp_update_jobstepを使用して、既存のエラスティックジョブステップを変更します。

このストアドプロシージャは、SQL Server エージェントサービスの SQL Server の同様のオブジェクトとsp_add_jobstepの名前を共有します。 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 スクリプト。 command は 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 は real データ型で、既定値は 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しない場合は、command の最初の結果セットの書き込み先の種類です。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_typeSqlDatabaseと等しい場合、既定値はdbo。 output_schema_name は nvarchar(128) です。

@output_table_name

NULLしない場合は、command の最初の結果セットが書き込まれるテーブルの名前。テーブルがまだ存在しない場合は、返される結果セットのスキーマに基づいて作成されます。 output_typeがSqlDatabaseと等しい場合は、指定する必要があります。 output_table_name は nvarchar(128) で、既定値は NULL です。

output_table_nameを指定する場合は、ジョブエージェント UMI またはデータベーススコープの資格情報に、CREATE TABLE と INSERT データに対する必要なアクセス許可をテーブルに付与する必要があります。

@job_version アウトプット

新しいジョブのバージョン番号が割り当てられる出力パラメーター。 job_version は int です。

@max_parallelism アウトプット

エラスティックプールあたりの並列処理の最大レベル。

設定した場合、ジョブステップはエラスティックプールあたり最大でもその指定数のデータベースでのみ実行するように制限されます。これは、ターゲットグループに直接含まれる各エラスティックプール、またはターゲットグループに含まれるサーバー内に存在するエラスティックプールに適用されます。 max_parallelism は int です。

リターンコードの値

0 (成功) または 1 (失敗)。

解説

sp_add_jobstep成功すると、ジョブの現在のバージョン番号がインクリメントされます。次にジョブを実行するときは、新しいバージョンが使われます。ジョブが現在実行中の場合、その実行には新しいステップは含まれません。

Microsoft Entra 認証を使用してターゲットサーバー/データベースに対して認証する場合、sp_add_jobstepまたはsp_update_jobstepに対して@credential_name引数と@output_credential_name引数を指定しないでください。
データベーススコープの資格情報を使用してターゲットサーバー/データベースに対する認証を行う場合、sp_add_jobstep および sp_update_jobstep には @credential_name パラメーターが必要です。たとえば、@credential_name = 'job_credential' のようにします。

アクセス許可

既定では、このストアドプロシージャを実行できるのは、 sysadmin 固定サーバーロールのメンバーです。このストアドプロシージャを使って、他のユーザーが所有するジョブの属性を編集できるのは、sysadmin のメンバーだけです。

例

T-SQL ステートメントを実行するジョブステップを作成する

次の例は、エラスティックジョブで T-SQL ステートメントを実行するエラスティックジョブを作成する方法を示しています。次の例では、 jobs.sp_add_jobstep を使用して、 CreateTableTest という名前のジョブステップを作成し、ターゲットグループ PoolGroupで実行します。

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 で結果を収集するエラスティックジョブを作成する方法を示しています。次の例では、 jobs.sp_add_jobstep を使用して、 ResultsJob という名前のジョブステップを作成し、ターゲットグループ PoolGroupで実行します。結果は、サーバー server1.database.windows.netの Results という名前のデータベース内の dbo.results_table という名前のテーブルに記録されます。

--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';

次の方法で共有

jobs.sp_add_jobstep (Azure エラスティックジョブ) (Transact-SQL)

構文

引数

@job_name

@step_id

@step_name

@command_type

@command_source

@command

@credential_name

@target_group_name

@initial_retry_interval_seconds

@maximum_retry_interval_seconds

@retry_interval_backoff_multiplier

@retry_attempts

@step_timeout_seconds

@output_type

@output_credential_name

@output_subscription_id

@output_resource_group_name

@output_server_name

@output_database_name

@output_schema_name

@output_table_name

@job_version アウトプット

@max_parallelism アウトプット

リターンコードの値

解説

アクセス許可

例

T-SQL ステートメントを実行するジョブステップを作成する

T-SQL ステートメントを実行して結果を収集するジョブステップを作成する

フィードバック

その他のリソース

次の方法で共有

jobs.sp_add_jobstep (Azure エラスティック ジョブ) (Transact-SQL)

構文

引数

@job_name

@step_id

@step_name

@command_type

@command_source

@command

@credential_name

@target_group_name

@initial_retry_interval_seconds

@maximum_retry_interval_seconds

@retry_interval_backoff_multiplier

@retry_attempts

@step_timeout_seconds

@output_type

@output_credential_name

@output_subscription_id

@output_resource_group_name

@output_server_name

@output_database_name

@output_schema_name

@output_table_name

@job_version アウトプット

@max_parallelism アウトプット

リターン コードの値

解説

アクセス許可

例

T-SQL ステートメントを実行するジョブ ステップを作成する

T-SQL ステートメントを実行して結果を収集するジョブ ステップを作成する

関連するコンテンツ

フィードバック

その他のリソース

jobs.sp_add_jobstep (Azure エラスティックジョブ) (Transact-SQL)

リターンコードの値

T-SQL ステートメントを実行するジョブステップを作成する

T-SQL ステートメントを実行して結果を収集するジョブステップを作成する