Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Aplica-se a:
SQL ServerAzure SQL Managed Instance
Adiciona um passo (operação) a um trabalho de Agente SQL Server.
Transact-SQL convenções de sintaxe
Importante
No Azure SQL Managed Instance, a maioria, mas não todos, os tipos de trabalho do SQL Server Agent são suportados. Consulte as diferenças entre o Azure SQL Managed Instance T-SQL e o SQL Server para mais 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 ]
[ ; ]
Arguments
[ @job_id = ] 'job_id'
O número de identificação do trabalho ao qual adicionar o passo.
@job_id é um identificador único, com um padrão de NULL.
Ou @job_id ou @job_name devem ser especificados, mas nenhum dos dois pode ser especificado.
[ @job_name = ] N'job_name'
O nome do trabalho ao qual adicionar o passo.
@job_name é sysname, com o padrão de NULL.
Ou @job_id ou @job_name devem ser especificados, mas nenhum dos dois pode ser especificado.
[ @step_id = ] step_id
O número de identificação de sequência para a etapa do trabalho.
@step_id é int, com um padrão de NULL. Os números de identificação dos passos começam em 1 e aumentam sem lacunas. Se um passo for inserido na sequência existente, os números de sequência são ajustados automaticamente. É fornecido um valor se @step_id não for especificado.
[ @step_name = ] N'step_name'
O nome do degrau. @step_name é sysname, sem padrão.
[ @subsystem = ] N'subsistema'
O subsistema utilizado pelo serviço SQL Server Agent para executar @command. @subsystem é nvarchar(40), e pode ser um desses valores.
| Valor | Description |
|---|---|
ActiveScripting |
Escrita Ativa Importante: Esta funcionalidade será removida numa versão futura do SQL Server. Evite usar esse recurso em novos trabalhos de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. |
CmdExec |
Comando do sistema operativo ou programa executável |
Distribution |
Trabalho do Agente de Distribuição de Replicação |
Snapshot |
Trabalho do Agente de Snapshot de Replicação |
LogReader |
Trabalho de Agente Leitor de Registo de Replicação |
Merge |
Trabalho de Agente de Fusão de Replicação |
QueueReader |
Trabalho do Agente Leitor de Fila de Replicação |
ANALYSISQUERY |
Consulta de Serviços de Análise (MDX, DMX) |
ANALYSISCOMMAND |
Comando de Serviços de Análise (XMLA) |
SSIS |
Execução do pacote Integration Services |
PowerShell |
PowerShell Script |
TSQL (padrão) |
Transact-SQL Declaração |
[ @command = ] N'comando'
Os comandos a serem executados pelo serviço SQL Server Agent através de @subsystem.
@command é nvarchar(max), com um padrão de NULL. O SQL Server Agent fornece substituição de tokens, o que lhe dá a mesma flexibilidade que as variáveis proporcionam quando escreve programas de software.
Uma macro de escape deve acompanhar todos os tokens usados nos passos do trabalho, caso contrário esses passos falham. Além disso, deve agora incluir os nomes dos tokens entre parênteses e colocar um cifrão ($) no início da sintaxe do token. Por exemplo: $(ESCAPE_<macro name>(DATE)).
Para mais informações sobre estes tokens e para atualizar os seus passos de trabalho para usar a nova sintaxe do token, consulte Usar Tokens em Passos de Trabalho.
Qualquer utilizador do Windows com permissões de escrita no Registo de Eventos do Windows pode aceder a passos de trabalho ativados por alertas do SQL Server Agent ou alertas WMI. Para evitar este risco de segurança, os tokens SQL Server Agent que podem ser usados em trabalhos ativados por alertas são desativados por defeito. Estas fichas são: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, e WMI(<property>). Nesta versão, o uso de tokens é estendido a todos os alertas.
Se precisar de usar estes tokens, certifique-se primeiro de que apenas membros de grupos de segurança Windows de confiança, como o grupo Administradores, têm permissões de escrita no Registo de Eventos do computador onde o SQL Server reside. Depois, clique com o botão direito no Agente SQL Server no Explorador de Objetos, selecione Propriedades e, na página do Sistema de Alertas , selecione Substituir tokens para todas as respostas de trabalho a alertas para ativar esses tokens.
[ @additional_parameters = ] N'additional_parameters'
Identificado apenas para fins informativos. Não suportado. A compatibilidade futura não é garantida.
[ @cmdexec_success_code = ] cmdexec_success_code
O valor devolvido por um CmdExec comando de subsistema para indicar que @command executado com sucesso.
@cmdexec_success_code é int, com um padrão de 0.
[ @on_success_action = ] on_success_action
A ação a realizar se o passo for bem-sucedido. @on_success_action é minúsculo e pode ser um desses valores.
| Valor | Descrição (ação) |
|---|---|
1 (padrão) |
Desistir com sucesso |
2 |
Desiste com fracasso |
3 |
Passar para o próximo passo |
4 |
Ir para o passo @on_success_step_id |
[ @on_success_step_id = ] on_success_step_id
O ID do passo neste trabalho a executar se o passo for bem-sucedido 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 realizar se o passo falhar. @on_fail_action é minúsculo e pode ser um desses valores.
| Valor | Descrição (ação) |
|---|---|
1 |
Desistir com sucesso |
2 (padrão) |
Desiste com fracasso |
3 |
Passar para o próximo passo |
4 |
Ir para o passo @on_fail_step_id |
[ @on_fail_step_id = ] on_fail_step_id
O ID do passo neste trabalho a executar se o passo 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 suportado. A compatibilidade futura não é garantida.
[ @database_name = ] N'database_name'
O nome da base de dados onde executar uma Transact-SQL etapa.
@database_name é sysname, com um padrão de NULL, caso em que a master base de dados é utilizada. Nomes que estejam entre parênteses ([]) não são permitidos. Para um passo de trabalho ActiveX, o @database_name é o nome da linguagem de script que o passo utiliza.
[ @database_user_name = ] N'database_user_name'
O nome da conta de utilizador a usar ao executar um passo Transact-SQL.
@database_user_name é sysname, com um padrão de NULL. Quando @database_user_name é NULL, o passo corre no contexto de utilizador do proprietário do trabalho em @database_name. O SQL Server Agent inclui este parâmetro apenas se o proprietário do trabalho for um administrador de sistemas SQL Server. Se sim, o passo Transact-SQL dado é executado no contexto do nome de utilizador SQL Server dado. Se o dono do job não for um sysadmin do SQL Server, então o passo Transact-SQL é sempre executado no contexto do login que detém esse trabalho, e o parâmetro @database_user_name é ignorado.
[ @retry_attempts = ] retry_attempts
O número de tentativas de retentativa a usar se esta etapa falhar.
@retry_attempts é int, com um padrão de 0, o que indica que não há tentativas de retentativa.
[ @retry_interval = ] retry_interval
O tempo em minutos entre tentativas de repetição.
@retry_interval é int, com um padrão de 0, que indica um 0intervalo de -minutos.
[ @os_run_priority = ] os_run_priority
Identificado apenas para fins informativos. Não suportado. A compatibilidade futura não é garantida.
[ @output_file_name = ] N'output_file_name'
O nome do ficheiro onde a saída deste passo é guardada.
@output_file_name é nvarchar(200), com um padrão de NULL.
@output_file_name podem incluir um ou mais dos tokens listados em @command. Este parâmetro é válido apenas com comandos a correr nos subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.
[ @flags = ] bandeiras
Uma opção que controla o comportamento. @flags é int, e pode ser um desses valores.
| Valor | Description |
|---|---|
0 (padrão) |
Sobrescrever ficheiro de saída |
2 |
Adicionar ao ficheiro de saída |
4 |
Escreva Transact-SQL saída do passo do trabalho no histórico de passos |
8 |
Escrever registo na tabela (sobrescrever o histórico existente) |
16 |
Escrever registo na tabela (anexar ao histórico existente) |
32 |
Escreva toda a saída para o histórico do emprego |
64 |
Crie um evento Windows para usar como sinal para abortar a cmd etapa do trabalho |
[ @proxy_id = ] proxy_id
O número de ID do proxy que o passo do trabalho é executado.
@proxy_id é int, com um padrão de NULL. Se não for especificado @proxy_id , não for especificado @proxy_name e não for especificado @database_user_name , o passo da tarefa executa-se como conta de serviço para o SQL Server Agent.
[ @proxy_name = ] N'proxy_name'
O nome do proxy que o passo do trabalho é executado.
@proxy_name é sysname, com um padrão de NULL. Se não for especificado @proxy_id , não for especificado @proxy_name e não for especificado @database_user_name , o passo da tarefa executa-se como conta de serviço para o SQL Server Agent.
[ @step_uid = ] 'step_uid' SAÍDA
@step_uid é um parâmetro OUTPUT do tipo identificador único.
Valores de código de retorno
0 (sucesso) ou 1 (fracasso).
Conjunto de resultados
Nenhum.
Observações
sp_add_jobstep deve ser executado a partir da msdb base de dados.
O SQL Server Management Studio fornece uma maneira gráfica fácil de gerenciar trabalhos e é a maneira recomendada de criar e gerenciar a infraestrutura de trabalho.
Por defeito, um passo de trabalho é executado como conta de serviço para o SQL Server Agent, a menos que outro proxy seja especificado. Um requisito desta conta é ser membro da função fixa de segurança de sysadmin .
Um proxy pode ser identificado por @proxy_name ou @proxy_id.
Este procedimento armazenado partilha o nome de sp_add_jobstep com um objeto semelhante para o serviço Azure Elastic Jobs para Azure SQL Database. Para informações sobre a versão do Elastic Jobs, veja jobs.sp_add_jobstep (Azure Elastic Jobs).
Permissions
Pode conceder EXECUTE permissões neste procedimento, mas essas permissões podem ser anuladas durante uma atualização do SQL Server.
Outros utilizadores devem receber um dos seguintes papéis fixos de base de dados SQL Server Agent na msdb base de dados:
- SQLAgentUserRole
- SQLAgentReaderRole
- SQLAgentOperatorRole
Para detalhes sobre as permissões destes papéis, consulte Funções de Base de Dados Fixas do Agente SQL Server.
O criador do passo do trabalho deve ter acesso ao proxy do passo do trabalho. Os membros do papel fixo de servidor sysadmin têm acesso a todos os proxies. Outros utilizadores devem ter acesso explícito a um proxy.
Examples
O exemplo seguinte cria uma etapa de trabalho que altera o acesso à base de dados para apenas leitura na base de dados de Vendas. Além disso, este exemplo especifica cinco tentativas de retentativa, com cada tentativa a ocorrer após uma espera de 5 minutos.
Observação
Este exemplo assume que o Weekly Sales Data Backup trabalho já existe.
USE msdb;
GO
EXECUTE 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