jobs.sp_add_jobstep （Azure 彈性作業）（Transact-SQL）

發行項
02/01/2024

將步驟新增至適用於 Azure 的 Azure 彈性作業服務中的現有作業 SQL 資料庫。使用 jobs.sp_update_jobstep 修改現有的彈性作業步驟。

這個預存程式會與 SQL Server Agent 服務中的類似物件共用的名稱 sp_add_jobstep 。如需 SQL Server Agent 版本的相關信息，請參閱 sp_add_jobstep （Transact-SQL）。

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

作業步驟的順序識別碼。步驟識別碼從 1 開始，並漸次遞增而不會跳號。如果現有的步驟已有此標識符，則該步驟和所有下列步驟都會遞增其標識碼，以便將這個新步驟插入序列中。如果未指定， 則會自動將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

允許執行步驟的時間長度上限。如果超過這個時間，則作業執行將會終止，並lifecycleTimedOut記錄在 jobs.job_executions。 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 訂用帳戶標識碼。預設為作業代理程式的訂用帳戶。 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_jobstep 或 sp_update_jobstep提供@credential_name和@output_credential_name自變數。
使用資料庫範圍的認證來驗證目標伺服器/資料庫時 sp_add_jobstep 和 sp_update_jobstep需要 @credential_name 參數。例如： @credential_name = 'job_credential' 。

權限

依預設，只有系統管理員 (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）