jobs.sp_add_jobstep （Azure 弹性作业）（Transact-SQL）

项目
08/21/2024

将步骤添加到 Azure 弹性作业服务中用于Azure SQL 数据库的现有作业。使用 jobs.sp_update_jobstep 修改现有的弹性作业步骤。

此存储过程与 SQL Server 中用于SQL Server 代理服务的类似对象共享名称sp_add_jobstep。有关SQL Server 代理版本的信息，请参阅sp_add_jobstep。

语法

[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

作业步骤的序列标识号。步骤标识号从 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，则第二次重试的延迟为 10 秒，第三次重试的延迟为 20 秒。 retry_interval_backoff_multiplier是实际数据类型，默认值为 2.0。

@retry_attempts

重试执行的次数，前提是初始尝试失败。例如，如果 retry_attempts 值为 10，则会出现 1 次初始尝试和 10 次重试尝试，总共尝试 11 次。如果最终重试尝试失败，则作业执行将终止lifecycleFailed并记录在jobs.job_executions中。 retry_attempts为 int，默认值为 10。

@step_timeout_seconds

允许步骤执行的最长时间。如果超过此时间，则作业执行将以记录在 jobs.job_executions 中终止lifecycleTimedOut。 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 和 INSERT 数据到表中所需的权限。

@job_version 输出

一个输出参数，将会为其分配新作业版本号。 job_version为 int。

@max_parallelism 输出

每个弹性池的最大并行度级别。

如果设置此项，则作业步骤会受到限制，每个弹性池中可以在其上运行作业步骤的数据库会有一个最大数目。这适用于每个特定的弹性池，该弹性池直接包括在目标组中，或者服务器的弹性池中，而该服务器则包括在目标组中。 max_parallelism为 int。

返回代码值

0（成功）或 1（失败）。

注解

成功后 sp_add_jobstep ，作业的当前版本号会递增。下次执行作业时，会使用新版本。如果作业目前正在执行，该执行不会包含新步骤。

使用 Microsoft Entra 身份验证向目标服务器/数据库进行身份验证时，不应为sp_add_jobstepsp_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 数据库中收集结果。以下示例用于 jobs.sp_add_jobstep 在命名的作业中创建作业 ResultsJob步骤，以在目标组 PoolGroup上执行。结果记录在服务器中命名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';

通过

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）