sp_add_jobstep (Transact-SQL)

Artigo
08/21/2024

Aplica-se a: SQL Server Instância Gerenciada de SQL do Azure

Adiciona uma etapa (operação) a um trabalho do SQL Server Agent.

Importante

Na Instância Gerenciada de SQL do Azure, há suporte para a maioria, mas não todos, os tipos de trabalho do SQL Server Agent. Confira Diferenças entre o T-SQL da Instância Gerenciada de SQL do Azure e o SQL Server para obter detalhes.

Sintaxe

sp_add_jobstep
    [ [ @job_id = ] 'job_id' ]
    [ , [ @job_name = ] N'job_name' ]
    [ , [ @step_id = ] step_id ]
    , [ @step_name = ] N'step_name'
    [ , [ @subsystem = ] N'subsystem' ]
    [ , [ @command = ] N'command' ]
    [ , [ @additional_parameters = ] N'additional_parameters' ]
    [ , [ @cmdexec_success_code = ] cmdexec_success_code ]
    [ , [ @on_success_action = ] on_success_action ]
    [ , [ @on_success_step_id = ] on_success_step_id ]
    [ , [ @on_fail_action = ] on_fail_action ]
    [ , [ @on_fail_step_id = ] on_fail_step_id ]
    [ , [ @server = ] N'server' ]
    [ , [ @database_name = ] N'database_name' ]
    [ , [ @database_user_name = ] N'database_user_name' ]
    [ , [ @retry_attempts = ] retry_attempts ]
    [ , [ @retry_interval = ] retry_interval ]
    [ , [ @os_run_priority = ] os_run_priority ]
    [ , [ @output_file_name = ] N'output_file_name' ]
    [ , [ @flags = ] flags ]
    [ , [ @proxy_id = ] proxy_id ]
    [ , [ @proxy_name = ] N'proxy_name' ]
    [ , [ @step_uid = ] 'step_uid' OUTPUT ]
[ ; ]

Argumentos

@job_id [ = ] 'job_id'

O número de identificação do trabalho ao qual adicionar a etapa. @job_id é uniqueidentifier, com um padrão de NULL.

Tanto @job_id quanto @job_name devem ser especificados, mas ambos não podem ser especificados.

@job_name [ = ] N'job_name'

O nome do trabalho ao qual adicionar a etapa. @job_name é sysname, com um padrão de NULL.

Tanto @job_id quanto @job_name devem ser especificados, mas ambos não podem ser especificados.

@step_id [ = ] step_id

O número de identificação de sequência para a etapa de trabalho. @step_id é int, com um padrão de NULL. Os números de identificação da etapa começam em 1 e aumentam sem lacunas. Se uma etapa for inserida na sequência existente, os números da sequência serão ajustados automaticamente. Um valor será fornecido se @step_id não for especificado.

@step_name [ = ] N'step_name'

O nome da etapa. @step_name é sysname, sem padrão.

@subsystem [ = ] N'subsistema'

O subsistema usado pelo serviço SQL Server Agent para executar @command. @subsystem é nvarchar(40) e pode ser um desses valores.

Valor	Descrição
`ActiveScripting`	Script ativo Importante: Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.
`CmdExec`	Comando do sistema operacional ou programa executável
`Distribution`	Trabalho do Replication Distribution Agent
`Snapshot`	Trabalho do Replication Snapshot Agent
`LogReader`	Trabalho do Replication Log Reader Agent
`Merge`	Trabalho do Replication Merge Agent
`QueueReader`	Trabalho do Replication Queue Reader Agent
`ANALYSISQUERY`	Consulta do Analysis Services (MDX, DMX)
`ANALYSISCOMMAND`	Comando do Analysis Services (XMLA)
`SSIS`	Execução de pacotes do Integration Services
`PowerShell`	Scripts PowerShell
`TSQL` (padrão)	Instrução Transact-SQL

@command [ = ] N'comando'

Os comandos a serem executados pelo serviço SQL Server Agent por meio do @subsystem. @command é nvarchar(max), com um padrão de NULL. O SQL Server Agent fornece substituição de token, o que oferece a mesma flexibilidade que as variáveis fornecem quando você escreve programas de software.

Uma macro de escape deve acompanhar todos os tokens usados nas etapas de trabalho, caso contrário, essas etapas de trabalho falharão. Além disso, deve-se colocar os nomes de token entre parênteses e um sinal de cifrão ($) no início da sintaxe do token. Por exemplo: $(ESCAPE_<macro name>(DATE)).

Para obter mais informações sobre esses tokens e atualizar suas etapas de trabalho para usar a nova sintaxe de token, consulte Usar tokens em etapas de trabalho.

Qualquer usuário Windows com permissões de gravação no Log de Eventos do Windows pode acessar etapas de trabalho ativadas pelos alertas do SQL Server Agent ou alertas do WMI. Para evitar riscos de segurança, os tokens do SQL Server Agent que podem ser usados em trabalhos ativados por alertas encontram-se desabilitados por padrão. Esses tokens são: A-DBN, A-SVR, A-ERR, A-SEVA-MSG, e WMI(<property>). Nesta versão, o uso de tokens foi estendido a todos os alertas.

Se tiver que usar esses tokens, garanta, primeiro, que apenas membros dos grupos de segurança confiáveis do Windows, como o grupo Administradores, tenham permissões de gravação no Log de Eventos do computador em que reside o SQL Server . Depois, clique com o botão direito do mouse em SQL Server Agent no Pesquisador de Objetos, selecione Propriedadese, na página Sistema de Alerta , selecione Substituir tokens de todas as respostas de trabalho aos alertas para habilitar esses tokens.

@additional_parameters [ = ] N'additional_parameters'

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@cmdexec_success_code [ = ] cmdexec_success_code

O valor retornado por um CmdExec comando de subsistema para indicar que @command executado com êxito. @cmdexec_success_code é int, com um padrão de 0.

@on_success_action [ = ] on_success_action

A ação a ser executada se a etapa tiver êxito. @on_success_action é tinyint e pode ser um desses valores.

Valor	Descrição (ação)
`1` (padrão)	Saia com sucesso
`2`	Sair com falha
`3`	Ir para a próxima etapa
`4`	Vá para a etapa @on_success_step_id

@on_success_step_id [ = ] on_success_step_id

A ID da etapa neste trabalho a ser executada se a etapa for bem-sucedida e @on_success_action for 4. @on_success_step_id é int, com um padrão de 0.

@on_fail_action [ = ] on_fail_action

A ação a ser executada se a etapa falhar. @on_fail_action é tinyint e pode ser um desses valores.

Valor	Descrição (ação)
`1`	Saia com sucesso
`2` (padrão)	Sair com falha
`3`	Ir para a próxima etapa
`4`	Vá para a etapa @on_fail_step_id

@on_fail_step_id [ = ] on_fail_step_id

A ID da etapa neste trabalho a ser executada se a etapa falhar e @on_fail_action for 4. @on_fail_step_id é int, com um padrão de 0.

@server [ = ] N'servidor'

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@database_name [ = ] N'database_name'

O nome do banco de dados no qual executar uma etapa Transact-SQL. @database_name é sysname, com um padrão de , caso em que o master banco de NULLdados é usado. Nomes entre colchetes ([]) não são permitidos. Para uma etapa de trabalho do ActiveX, o @database_name é o nome da linguagem de script que a etapa usa.

@database_user_name [ = ] N'database_user_name'

O nome da conta de usuário a ser usada ao executar uma etapa Transact-SQL. @database_user_name é sysname, com um padrão de NULL. Quando @database_user_name é NULL, a etapa é executada no contexto de usuário do proprietário do trabalho em @database_name. O SQL Server Agent incluirá esse parâmetro somente se o proprietário do trabalho for um administrador de sistema do SQL Server. Nesse caso, a etapa Transact-SQL fornecida é executada no contexto do nome de usuário do SQL Server fornecido. Se o proprietário do trabalho não for um administrador de sistema do SQL Server, a etapa Transact-SQL será sempre executada no contexto do logon que possui esse trabalho e o parâmetro @database_user_name será ignorado.

@retry_attempts [ = ] retry_attempts

O número de novas tentativas a serem usadas se esta etapa apresentar falha. @retry_attempts é int, com um padrão de , o que indica que não há tentativas de 0repetição.

@retry_interval [ = ] retry_interval

A quantidade de tempo, em minutos, entre as novas tentativas. @retry_interval é int, com um padrão de , que indica um 0intervalo de 0minutos.

@os_run_priority [ = ] os_run_priority

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@output_file_name [ = ] N'output_file_name'

O nome do arquivo no qual a saída desta etapa é gravado. @output_file_name é nvarchar(200), com um padrão de NULL. @output_file_name pode incluir um ou mais dos tokens listados em @command. Esse parâmetro é válido somente com comandos em execução nos subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.

@flags [ = ] sinalizadores

Uma opção que controla comportamento. @flags é int e pode ser um desses valores.

Valor	Descrição
`0` (padrão)	Substitui o arquivo de saída
`2`	Anexa a um arquivo de saída
`4`	Grava a saída da etapa de trabalho do Transact-SQL no histórico de etapas
`8`	Grava o log na tabela (substitui o histórico existente)
`16`	Grava o log na tabela (anexa ao histórico existente)
`32`	Grave todas as saídas no histórico do trabalho
`64`	Criar um evento do Windows para usar como um sinal para a etapa de trabalho ser anulada `cmd`

@proxy_id [ = ] proxy_id

O número da ID do proxy com o qual a etapa de trabalho é executada. @proxy_id é int, com um padrão de NULL. Se nenhuma @proxy_id for especificada, nenhuma @proxy_name for especificada e nenhuma @database_user_name for especificada, a etapa de trabalho será executada como a conta de serviço do SQL Server Agent.

@proxy_name [ = ] N'proxy_name'

O nome do proxy com o qual a etapa de trabalho é executada. @proxy_name é sysname, com um padrão de NULL. Se nenhuma @proxy_id for especificada, nenhuma @proxy_name for especificada e nenhuma @database_user_name for especificada, a etapa de trabalho será executada como a conta de serviço do SQL Server Agent.

@step_uid [ = ] 'step_uid' SAÍDA

@step_uid é um parâmetro OUTPUT do tipo uniqueidentifier.

Valores do código de retorno

0 (sucesso) ou 1 (falha).

Conjunto de resultados

Nenhum.

Comentários

sp_add_jobstep deve ser executado a partir do msdb banco de dados.

O SQL Server Management Studio fornece um modo gráfico fácil de gerenciar trabalhos e é o modo recomendado de criar e gerenciar a infra-estrutura de trabalho.

Por padrão, uma etapa de trabalho é executada como a conta de serviço do SQL Server Agent, a menos que outro proxy seja especificado. Um requisito dessa conta é ser membro do direito de acesso fixo sysadmin .

Um proxy pode ser identificado por @proxy_name ou @proxy_id.

Esse procedimento armazenado compartilha o nome de sp_add_jobstep com um objeto semelhante para o serviço de Trabalhos Elásticos do Azure para Banco de Dados SQL do Azure. Para obter informações sobre a versão dos trabalhos elásticos, consulte jobs.sp_add_jobstep (Trabalhos Elásticos do Azure).

Permissões

Você pode conceder EXECUTE permissões nesse procedimento, mas essas permissões podem ser substituídas durante uma atualização do SQL Server.

Outros usuários devem receber uma das seguintes funções de banco de dados fixas do msdb SQL Server Agent no banco de dados:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Para obter detalhes sobre as permissões dessas funções, consulte Funções de banco de dados fixas do SQL Server Agent.

O criador da etapa de trabalho deve ter acesso ao proxy para a etapa de trabalho. Os membros da função de servidor fixa sysadmin têm acesso a todos os proxies. O acesso a um proxy deve ser concedido explicitamente a outros usuários.

Exemplos

O exemplo a seguir cria uma etapa de trabalho que altera o acesso ao banco de dados para somente leitura para o banco de dados de Vendas. Além disso, este exemplo especifica cinco tentativas de repetição, com cada repetição ocorrendo após uma espera de 5 minutos.

Observação

Este exemplo pressupõe que o Weekly Sales Data Backup trabalho já existe.

USE msdb;
GO
EXEC sp_add_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_name = N'Set database to read only',
    @subsystem = N'TSQL',
    @command = N'ALTER DATABASE SALES SET READ_ONLY',
    @retry_attempts = 5,
    @retry_interval = 5;
GO

Compartilhar via

sp_add_jobstep (Transact-SQL)

Sintaxe

Argumentos

@job_id [ = ] 'job_id'

@job_name [ = ] N'job_name'

@step_id [ = ] step_id

@step_name [ = ] N'step_name'

@subsystem [ = ] N'subsistema'

@command [ = ] N'comando'

@additional_parameters [ = ] N'additional_parameters'

@cmdexec_success_code [ = ] cmdexec_success_code

@on_success_action [ = ] on_success_action

@on_success_step_id [ = ] on_success_step_id

@on_fail_action [ = ] on_fail_action

@on_fail_step_id [ = ] on_fail_step_id

@server [ = ] N'servidor'

@database_name [ = ] N'database_name'

@database_user_name [ = ] N'database_user_name'

@retry_attempts [ = ] retry_attempts

@retry_interval [ = ] retry_interval

@os_run_priority [ = ] os_run_priority

@output_file_name [ = ] N'output_file_name'

@flags [ = ] sinalizadores

@proxy_id [ = ] proxy_id

@proxy_name [ = ] N'proxy_name'

@step_uid [ = ] 'step_uid' SAÍDA

Valores do código de retorno

Conjunto de resultados

Comentários

Permissões

Exemplos

Comentários

Recursos adicionais

Compartilhar via

sp_add_jobstep (Transact-SQL)

Sintaxe

Argumentos

@job_id [ = ] 'job_id'

@job_name [ = ] N'job_name'

@step_id [ = ] step_id

@step_name [ = ] N'step_name'

@subsystem [ = ] N'subsistema'

@command [ = ] N'comando'

@additional_parameters [ = ] N'additional_parameters'

@cmdexec_success_code [ = ] cmdexec_success_code

@on_success_action [ = ] on_success_action

@on_success_step_id [ = ] on_success_step_id

@on_fail_action [ = ] on_fail_action

@on_fail_step_id [ = ] on_fail_step_id

@server [ = ] N'servidor'

@database_name [ = ] N'database_name'

@database_user_name [ = ] N'database_user_name'

@retry_attempts [ = ] retry_attempts

@retry_interval [ = ] retry_interval

@os_run_priority [ = ] os_run_priority

@output_file_name [ = ] N'output_file_name'

@flags [ = ] sinalizadores

@proxy_id [ = ] proxy_id

@proxy_name [ = ] N'proxy_name'

@step_uid [ = ] 'step_uid' SAÍDA

Valores do código de retorno

Conjunto de resultados

Comentários

Permissões

Exemplos

Conteúdo relacionado

Comentários

Recursos adicionais