• Artigo

sp_add_jobstep (Transact-SQL)

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

Ícone de vínculo de tópicoConvenções de 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 a etapa deve ser adicionada. job_id é uniqueidentifier, com um padrão NULL.

  • [ @job_name = ] 'job_name'
    O nome do trabalho ao a etapa deve ser adicionada. job_name é sysname, com um padrão NULL.

    ObservaçãoObservaçã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 NULL.

  • [ @step_name = ] 'step_name'
    O nome da etapa. step_nameé sysname, sem padrão.

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

    Valor

    Descrição

    'ACTIVESCRIPTING'

    Script ativo

    Observação importanteImportante
    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 através de subsystem. command é nvarchar(max), com um padrão 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.

    Observação importanteImportante

    No SQL Server 2005 Service Pack 1, a sintaxe de token de etapa de trabalho do SQL Server Agent foi alterada. Por consequência, uma macro de fuga agora deve acompanhar todos os tokens utilizados em etapas de trabalho, ou elas falharão. Além disso, a sintaxe do SQL Server 2000, que usava colchetes para chamar tokens de etapa de trabalho do SQL Server Agent (por exemplo, "[DATE]"), também mudou. Agora, 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_nome da macro(DATE))

    Para obter mais informações sobre esses tokens e atualizar as etapas do seu trabalho ao usar a nova sintaxe de token, consulte Usando tokens em etapas de trabalho.

    Observação sobre segurançaObservaçã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: propriedades A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI().

    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 de 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 de executar se a etapa tiver êxito. success_action é tinyint e pode ser 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
    A ID da etapa neste trabalho a ser executado 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 ser 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
    A ID da etapa neste trabalho a ser executado 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. server is nvarchar(30), com um padrão NULL.

  • [ @database_name = ] 'database'
    O nome do banco de dados no qual executar uma etapa do Transact-SQL. database é sysname, com um padrão NULL, caso o banco de dados mestre seja usado. Os 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 do Transact-SQL. user é sysname, com um padrão 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 tentativas de repetição a serem usadas se esta etapa falhar. retry_attemptsé int, com um padrão de 0, que indica nenhuma tentativa de repetição.

  • [ @retry_interval= ] retry_interval
    O tempo em minutos entre as tentativas de repetição. retry_intervalé int, com um padrão 0, que indica um intervalo de 0 minutos.

  • [ @os_run_priority = ] run_priority
    Reservado.

  • [ @output_file_name= ] 'file_name'
    O nome do arquivo no qual a saída desta etapa é salva. file_nameé nvarchar(200), com um padrão NULL. file_namepode incluir um ou mais dos tokens listados em command. Este parâmetro é válido somente com comandos executados nos subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.

  • [ @flags= ] flags
    É uma opção que controla comportamento. flags é int e pode ser 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 de identificação do proxy com o qual a etapa de trabalho é executada. proxy_id é do tipo int, com um padrão 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 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çãoObservaçã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