jobs.sp_add_jobstep (Azure Elastic Jobs) (Transact-SQL)
Aplica-se a: 
Banco de Dados SQL do Azure
Adiciona uma etapa a um trabalho existente no serviço de Trabalhos Elásticos do Azure para Banco de Dados SQL do Azure. Use jobs.sp_update_jobstep para modificar as etapas de trabalho elásticas existentes.
Esse procedimento armazenado compartilha o nome de sp_add_jobstep com um objeto semelhante no SQL Server para o serviço SQL Server Agent. Para obter informações sobre a versão do SQL Server Agent, consulte sp_add_jobstep.
Convenções de sintaxe de Transact-SQL
Sintaxe
[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 ]
Argumentos
@job_name
O nome do trabalho ao qual adicionar a etapa. job_name é nvarchar(128).
@step_id
O número de identificação de sequência para a etapa de trabalho. Os números de identificação de etapa começam em 1 e são incrementados sem lacunas. Se uma etapa existente já tiver essa ID, essa etapa e todas as etapas seguintes terão suas IDs incrementadas para que essa nova etapa possa ser inserida na sequência. Se não for especificado, o step_id será atribuído automaticamente ao último na sequência de etapas. step_id é um int.
@step_name
O nome da etapa. Deve ser especificado, exceto para a primeira etapa de um trabalho que (por conveniência) tem um nome padrão de JobStep. step_name é nvarchar(128).
@command_type
O tipo de comando que é executado por esta etapa de trabalho. command_type é nvarchar(50), com um valor padrão de TSql, o que significa que o valor do parâmetro @command_type é um script T-SQL.
Se especificado, o valor deve ser TSql.
@command_source
O tipo do local em que o comando é armazenado. command_source é nvarchar(50), com um valor padrão de Inline, o que significa que o valor do parâmetro @command é o texto literal do comando.
Se especificado, o valor deve ser Inline.
@command
O script T-SQL válido que deve ser executado por esta etapa de trabalho. é nvarchar(max), com um padrão de NULL.
@credential_name
O nome da credencial no escopo do banco de dados armazenada nesse banco de dados de controle de trabalho que é usado para se conectar a cada um dos bancos de dados de destino dentro do grupo de destino quando essa etapa é executada. credential_name é nvarchar(128).
Ao usar a autenticação do Microsoft Entra (anteriormente Azure Active Directory), omita o parâmetro @credential_name , que só deve ser fornecido ao usar credenciais no escopo do banco de dados.
@target_group_name
O nome do grupo de destino que contém os bancos de dados de destino nos quais a etapa de trabalho será executada. target_group_name é nvarchar(128).
@initial_retry_interval_seconds
O atraso antes da primeira tentativa de repetição, se a etapa de trabalho falhar na tentativa de execução inicial. initial_retry_interval_seconds é int, com valor padrão de 1.
@maximum_retry_interval_seconds
O atraso máximo entre as tentativas repetição. Se o atraso entre as tentativas aumentar maior do que esse valor, ele será limitado a esse valor. maximum_retry_interval_seconds é int, com valor padrão de 120.
@retry_interval_backoff_multiplier
O multiplicador a ser aplicado ao atraso de repetição se várias tentativas de execução de etapa de trabalho falharem. Por exemplo, se a primeira repetição tiver um atraso de 5 segundos e o multiplicador de retirada for 2.0, a segunda repetição terá um atraso de 10 segundos e a terceira, de 20 segundos. retry_interval_backoff_multiplier é o tipo de dados real, com valor padrão de 2.0.
@retry_attempts
O número de vezes que a execução deverá ser repetida quando a tentativa inicial falhar. Por exemplo, se o valor retry_attempts for 10, haverá 1 tentativa inicial e 10 tentativas de repetição, totalizando 11 tentativas. Se a tentativa final de repetição falhar, a execução do trabalho será encerrada com um lifecycle de Failed registrado em jobs.job_executions. retry_attempts é int, com valor padrão de 10.
@step_timeout_seconds
O período de tempo máximo permitido para a execução da etapa. Se esse tempo for excedido, a execução do trabalho será encerrada com um lifecycle de TimedOut registrado em jobs.job_executions. step_timeout_seconds é int, com valor padrão de 43.200 segundos (12 horas).
@output_type
Caso contrárioNULL, o tipo de destino no qual o primeiro conjunto de resultados do comando é gravado. output_type é nvarchar(50), com um padrão de NULL.
Se especificado, o valor deve ser SqlDatabase.
@output_credential_name
Se não for nulo, o nome da credencial no escopo do banco de dados usada para se conectar ao banco de dados de destino de saída. Deve ser especificado se output_type for igual a SqlDatabase. output_credential_name é nvarchar(128), com um valor padrão de NULL.
Ao usar a autenticação do Microsoft Entra (anteriormente Azure Active Directory), omita o parâmetro @output_credential_name , que só deve ser fornecido ao usar credenciais no escopo do banco de dados.
@output_subscription_id
ID de assinatura do Azure a ser usada para a saída. O padrão é a assinatura do agente de trabalho. output_subscription_id é um identificador exclusivo.
@output_resource_group_name
Nome do grupo de recursos no qual o banco de dados de saída reside. O padrão é o grupo de recursos do agente de trabalho. output_resource_group_name é nvarchar(128).
@output_server_name
Caso contrário NULL, o nome DNS totalmente qualificado do servidor que contém o banco de dados de destino de saída, por exemplo: @output_server_name = 'server1.database.windows.net'. Deve ser especificado se output_type for igual a SqlDatabase. output_server_name é nvarchar(256), com um padrão de NULL.
@output_database_name
Caso contrário NULL, o nome do banco de dados que contém a tabela de destino de saída. Deve ser especificado se output_type for igual a SqlDatabase. output_database_name é nvarchar(128), com um padrão de NULL.
@output_schema_name
Caso contrário NULL, o nome do esquema SQL que contém a tabela de destino de saída. Se output_type for SqlDatabaseigual a , o valor padrão é dbo. output_schema_name é nvarchar(128).
@output_table_name
Caso contrário NULL, o nome da tabela na qual o primeiro conjunto de resultados do comando será gravado. Se a tabela ainda não existir, ela será criada com base no esquema do conjunto de resultados retornado. Deve ser especificado se output_type for igual a SqlDatabase. output_table_name é nvarchar(128), com um valor padrão de NULL.
Se especificar um output_table_name, a UMI do Agente de Trabalho ou a credencial no escopo do banco de dados deverá receber as permissões necessárias para CREATE TABLE e INSERT dados na tabela.
@job_version SAÍDA
Parâmetro de saída que será atribuído ao novo número de versão do trabalho. job_version é int.
@max_parallelism SAÍDA
O nível máximo de paralelismo por pool elástico.
Se estiver definido, a execução da etapa de trabalho será restrita apenas a esse número máximo de bancos de dados por pool elástico. Isso se aplica a cada pool elástico incluído diretamente no grupo de destino ou a pools elásticos dentro de um servidor incluído no grupo de destino. max_parallelism é int.
Valores do código de retorno
0 (sucesso) ou 1 (falha).
Comentários
Quando sp_add_jobstep for bem-sucedido, o número da versão atual do trabalho será incrementado. Na próxima vez em que o trabalho for executado, a nova versão será usada. Se o trabalho estiver em execução no momento, essa execução não conterá a nova etapa.
- Ao usar a autenticação do Microsoft Entra para autenticar em servidor(es)/bancos de dados de destino, os argumentos @credential_name e @output_credential_name não devem ser fornecidos para
sp_add_jobstepousp_update_jobstep. - Ao usar credenciais no escopo de banco de dados para autenticação em servidores/bancos de dados de destino, o parâmetro @credential_name é necessário para
sp_add_jobstepesp_update_jobstep. Por exemplo,@credential_name = 'job_credential'.
Permissões
Por padrão, os membros da função de servidor fixa sysadmin podem executar este procedimento armazenado. Somente os membros da função sysadmin podem usar esse procedimento armazenado para editar os atributos dos trabalhos pertencentes a outros usuários.
Exemplos
Criar uma etapa de trabalho para executar uma instrução T-SQL
O exemplo a seguir mostra como criar um trabalho elástico para executar uma instrução T-SQL em um trabalho elástico. O exemplo a seguir usa jobs.sp_add_jobstep para criar uma etapa de trabalho no trabalho chamado CreateTableTest, a ser executado no grupo PoolGroupde destino.
Conecte-se ao job_database e execute o seguinte comando:
--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';
Criar uma etapa de trabalho para executar uma instrução T-SQL e coletar resultados
O exemplo a seguir mostra como criar um trabalho elástico para executar uma instrução T-SQL em um trabalho elástico e coletar os resultados em um Banco de Dados SQL do Azure. O exemplo a seguir usa jobs.sp_add_jobstep para criar uma etapa de trabalho no trabalho chamado ResultsJob, a ser executado no grupo PoolGroupde destino. Os resultados são registrados em uma tabela nomeada dbo.results_table no banco de dados nomeado Results no servidor 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';