sp_add_jobstep (Transact-SQL)

Artigo
06/18/2013

Adiciona uma etapa (operação) a um trabalho.

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL

Sintaxe

sp_add_jobstep [ @job_id = ] job_id | [ @job_name = ] 'job_name' 
     [ , [ @step_id = ] step_id ] 
     { , [ @step_name = ] 'step_name' } 
     [ , [ @subsystem = ] 'subsystem' ] 
     [ , [ @command = ] 'command' ] 
     [ , [ @additional_parameters = ] 'parameters' ] 
          [ , [ @cmdexec_success_code = ] code ] 
     [ , [ @on_success_action = ] success_action ] 
          [ , [ @on_success_step_id = ] success_step_id ] 
          [ , [ @on_fail_action = ] fail_action ] 
          [ , [ @on_fail_step_id = ] fail_step_id ] 
     [ , [ @server = ] 'server' ] 
     [ , [ @database_name = ] 'database' ] 
     [ , [ @database_user_name = ] 'user' ] 
     [ , [ @retry_attempts = ] retry_attempts ] 
     [ , [ @retry_interval = ] retry_interval ] 
     [ , [ @os_run_priority = ] run_priority ] 
     [ , [ @output_file_name = ] 'file_name' ] 
     [ , [ @flags = ] flags ] 
     [ , { [ @proxy_id = ] proxy_id 
         | [ @proxy_name = ] 'proxy_name' } ]

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.
[ @job_name = ] 'job_name'
O nome do trabalho ao qual adicionar a etapa. job_name é sysname, com um padrão de NULL.

Observação

É necessário especificar a job_id ou o job_name, mas não é possível especificar ambos ao mesmo tempo.
[ @step_id = ] 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 com 1 e são incrementados sem intervalos. 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_id é int, com um padrão de NULL.
[ @step_name = ] 'step_name'
O nome da etapa. step_nameé sysname, sem padrão.

Observação
É necessário especificar a job_id ou o job_name, mas não é possível especificar ambos ao mesmo tempo.

[ @subsystem = ] 'subsystem'
O subsistema usado pelo serviço SQL Server Agent para executar command. subsystem é nvarchar(40) e pode ter um destes valores.

'ACTIVESCRIPTING'

Script ativo

Importante
Esse recurso será removido em uma versão futura do Microsoft 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).

'Dts'

Integration Services execução do pacote

'PowerShell'

Scripts PowerShell

'TSQL' (padrão)

Instrução Transact-SQL

[ @command= ] 'command'
Os comandos a serem executados pelo serviço SQLServerAgent por meio de subsystem. command é nvarchar(max), com um padrão de NULL. O SQL Server Agent fornece uma substituição de token que propicia a mesma flexibilidade que as variáveis ao escrever programas de software.

Importante
No SQL Server 2005 Service Pack 1, a sintaxe de token de etapa de trabalho do SQL Server Agent foi alterada. Como consequência, uma macro de fuga agora deve acompanhar todos os tokens usados em etapas de trabalho ou elas 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))

No SQL Server 2005 Service Pack 1, a sintaxe de token de etapa de trabalho do SQL Server Agent foi alterada. Como consequência, uma macro de fuga agora deve acompanhar todos os tokens usados em etapas de trabalho ou elas 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 as etapas do seu trabalho ao usar a nova sintaxe de token, consulte Usar tokens em etapas de trabalho.

Observação sobre segurança
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. São eles: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property). Observe que 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 Propriedades e, na página Sistema de Alerta, selecione Substituir tokens de todas as respostas de trabalho aos alertas para habilitar esses tokens.

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. São eles: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property). Observe que 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 Propriedades e, na página Sistema de Alerta, selecione Substituir tokens de todas as respostas de trabalho aos alertas para habilitar esses tokens.

[ @additional_parameters= ] 'parameters'
Identificado apenas para fins informativos. Sem suporte. A compatibilidade futura não está garantida. parameters é ntext, com um padrão NULL.
[ @cmdexec_success_code = ] code
O valor retornado por um comando do subsistema CmdExec para indicar que command foi executado com êxito. codeé int, com um padrão de 0.
[ @on_success_action= ] success_action
A ação a ser executada se a etapa tiver êxito. success_actioné tinyint e pode ter um destes valores.

Valor

Descrição (ação)

1 (padrão)

Sair com êxito

2

Sair com falha

3

Ir para a próxima etapa

4

Ir para a etapa on_success_step_id
[ @on_success_step_id = ] success_step_id
O número de ID da etapa que será executada neste trabalho se a etapa for bem-sucedida e success_actionfor 4. success_step_idé int, com um padrão de 0.
[ @on_fail_action= ] fail_action
A ação a ser executada se a etapa falhar. fail_actioné tinyint e pode ter um destes valores.

Valor

Descrição (ação)

1

Sair com êxito

2 (padrão)

Sair com falha

3

Ir para a próxima etapa

4

Ir para a etapa on_fail_step_id
[ @on_fail_step_id= ] fail_step_id
O número de ID da etapa que será executada neste trabalho se a etapa falhar e fail_actionfor 4. fail_step_idé int, com um padrão de 0.
[ @server =] 'server'
Identificado apenas para fins informativos. Sem suporte. A compatibilidade futura não está garantida. serveris nvarchar(30), com um padrão NULL.
[ @database_name = ] 'database'
O nome do banco de dados no qual executar uma etapa Transact-SQL. database é sysname, com um padrão de NULL, caso em que o banco de dados mestre é usado. Nomes entre colchetes ([ ]) não são permitidos. Para uma etapa do ActiveX, o database é o nome da linguagem de script que a etapa usa.
[ @database_user_name= ] 'user'
O nome da conta de usuário a ser usada ao executar uma etapa Transact-SQL. user é sysname, com um padrão de NULL. Quando user é NULL, a etapa é executada no contexto de usuário do proprietário do trabalho em database. O SQL Server Agent só incluirá esse parâmetro se o proprietário do trabalho for um sysadmin de SQL Server. Assim, a determinada etapa de Transact-SQL será executada no contexto do determinado nome de usuário do SQL Server. Se o proprietário de trabalho não for um sysadmin de SQL Server, a etapa de Transact-SQL sempre será executada no contexto do logon que possua 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_attemptsis int, com um padrão de 0, que indica que não há tentativas de repetição.
[ @retry_interval= ] retry_interval
A quantidade de tempo, em minutos, entre as novas tentativas. retry_intervalis int, com um padrão de 0, que indica um intervalo de 0 minuto.
[ @os_run_priority = ] run_priority
Reservado.
[ @output_file_name= ] 'file_name'
O nome do arquivo no qual a saída desta etapa é gravado. file_name é nvarchar(200), com um padrão de NULL. file_namepode incluir um ou mais dos tokens listado em command. Este parâmetro é válido apenas com comandos executados nos subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.

Valor	Descrição (ação)
1 (padrão)	Sair com êxito
2	Sair com falha
3	Ir para a próxima etapa
4	Ir para a etapa on_success_step_id

Valor	Descrição (ação)
1	Sair com êxito
2 (padrão)	Sair com falha
3	Ir para a próxima etapa
4	Ir para a etapa on_fail_step_id

[ @flags= ] flags
É uma opção que controla comportamento. flags é int e pode ter um destes 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	Crie um evento do Windows para usar como um sinal para o jobstep de Cmd anular

[ @proxy_id = ] proxy_id
O número da ID do proxy com o qual a etapa de trabalho é executada. proxy_id é do tipo int, com um padrão de NULL. Se nenhuma proxy_id, nenhum proxy_name e nenhum user_name forem especificados, a etapa de trabalho será executada como a conta de serviço para o Agente SQL Server.
[ @proxy_name = ] 'proxy_name'
O nome do proxy com o qual a etapa de trabalho é executada. proxy_name é do tipo sysname, com um padrão de NULL. Se nenhuma proxy_id, nenhum proxy_name e nenhum user_name forem especificados, a etapa de trabalho será executada como a conta de serviço para o SQL Server Agent.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Conjuntos de resultados

Nenhum

Comentários

sp_add_jobstep deve ser executado do banco de dados msdb.

O SQL Server Management Studio gerencia trabalhos de forma fácil e com representação gráfica. Além disso, ele é recomendado para criar e gerenciar a infraestrutura de trabalhos.

Uma etapa de trabalho deve especificar um proxy a menos que o criador da etapa de trabalho seja um membro da função de segurança fixa sysadmin.

Um proxy pode ser identificado por proxy_name ou proxy_id.

Permissões

Por padrão, os membros da função de servidor fixa sysadmin podem executar este procedimento armazenado. Deve ser concedida a outros usuários uma das seguintes funções de banco de dados fixas do SQL Server Agent no banco de dados msdb:

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. 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 Sales. Além disso, este exemplo especifica 5 tentativas de repetição, sendo que cada uma deve ocorrer depois de uma espera de 5 minutos.

Observação
Este exemplo supõe que o trabalho Weekly Sales Data Backup já exista.

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