jobs.sp_update_jobstep （Azure 彈性作業） （Transact-SQL）
適用於：
Azure SQL 資料庫
在適用於 Azure SQL 資料庫 的 Azure 彈性作業服務中，修改現有作業中的作業步驟。 使用 jobs.sp_add_jobstep 將作業步驟新增至作業。
這個預存程式會與 SQL Server Agent 服務中的類似物件共用 的名稱 sp_update_jobstep 。 如需 SQL Server Agent 版本的相關信息，請參閱 sp_update_jobstep。
語法
[jobs].sp_update_jobstep [ @job_name = ] 'job_name'
[ , [ @step_id = ] step_id ]
[ , [ @step_name = ] 'step_name' ]
[ , [ @new_id = ] new_id ]
[ , [ @new_name = ] 'new_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_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
要修改的作業步驟的識別碼。 必須指定step_id或step_name。 step_id是 int。
@step_name
要修改的步驟名稱。 必須指定step_id或step_name。 step_name是 nvarchar（128）。
@new_id
作業步驟的新序列識別碼。 步驟識別碼從 1 開始，並漸次遞增而不會跳號。 如果某個步驟重新排序，其他步驟將會自動重新編碼。
@new_name
步驟的新名稱。 new_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 NULL的值重設為 ，請將此參數的值設定為 '' （空字串）。 output_type為 nvarchar（50），預設值為 NULL。
如果指定，此值必須是 SqlDatabase。
@output_credential_name
如果不是 NULL，則為用來連接到輸出目的地資料庫的資料庫範圍認證名稱。 如果 output_type 等於 SqlDatabase，必須指定 。 若要將 output_credential_name 的值重設為 ，請將此參數的值設定為 NULL'' （空字串）。 output_credential_name為 nvarchar（128），預設值為 NULL。
使用 Microsoft Entra 驗證時（先前稱為 Azure Active Directory），請省略 @output_credential_name 參數，只有在使用資料庫範圍認證時才應該提供此參數。
@output_server_name
如果不是 NULL，則為包含輸出目的地資料庫之伺服器的完整 DNS 名稱，例如 @output_server_name = 'server1.database.windows.net'。 如果 output_type 等於 SqlDatabase，必須指定 。 若要將 output_server_name NULL的值重設為 ，請將此參數的值設定為 '' （空字串）。 output_server_name為 nvarchar（256），預設值為 NULL。
@output_database_name
如果不是 NULL，則為包含輸出目的地數據表的資料庫名稱。 如果 output_type 等於 SqlDatabase，必須指定 。 若要將 output_database_name 的值重設為 ，請將此參數的值設定為 NULL'' （空字串）。 output_database_name為 nvarchar（128），預設值為 NULL。
@output_schema_name
如果不是 NULL，則為包含輸出目的地數據表的 SQL 架構名稱。 如果output_type等於SqlDatabase，則預設值為 dbo。 若要將 output_schema_name NULL的值重設為 ，請將此參數的值設定為 '' （空字串）。 output_schema_name是 nvarchar（128）。
@output_table_name
如果不是 NULL，則會寫入命令第一個結果集的數據表名稱。 如果資料表尚不存在，則會根據傳回的結果集所具備的結構描述建立資料表。 如果 output_type 等於 SqlDatabase，必須指定 。 若要將 output_server_name NULL的值重設為 ，請將此參數的值設定為 '' （空字串）。 output_table_name為 nvarchar（128），預設值為 NULL。
如果指定 output_table_name，應該授與作業代理程式 UMI 或資料庫範圍認證，才能將 CREATE TABLE 和 INSERT 數據授與數據表。
@job_version 輸出
將會被指派新的作業版本號碼的輸出參數。 job_version為 int。
@max_parallelism 輸出
每個彈性集區的平行處理原則最大層級。 如果設定，則作業步驟將會限定為最多僅為每個彈性集區執行該數量的資料庫。 這會套用至直接包含在目標群組中的每個彈性集區，或是目標群組所含伺服器內部的彈性集區。 若要將 max_parallelism NULL的值重設為 ，請將此參數的值設定為 -1。 max_parallelism為 int。
傳回碼值
0 (成功) 或 1 (失敗)。
備註
任何執行中的作業都不會受到影響。 成功時 jobs.sp_update_jobstep ，作業的版本號碼會遞增。 在下次執行作業時，將會使用新版本。
權限
依預設，只有 系統管理員 (sysadmin) 固定伺服器角色的成員，才能夠執行這個預存程序。 只有系統管理員的成員可以使用此預存程序來編輯其他使用者所擁有的作業屬性。
範例
彈性作業步驟的更新命令
此範例會更新現有彈性作業步驟的 T-SQL 命令。 T-SQL 腳本會在作業步驟不存在時新增作業步驟來建立數據表。
--Connect to the job database specified when creating the elastic job agent
-- Add job step to create a table if it does not exist
EXEC jobs.sp_update_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';