Compartilhar via

Set-ScheduledJob

  • Referência
Módulo:
PSScheduledJob

Altera trabalhos agendados.

Sintaxe

Set-ScheduledJob
   [-Name <String>]
   [-ScriptBlock <ScriptBlock>]
   [-Trigger <ScheduledJobTrigger[]>]
   [-InitializationScript <ScriptBlock>]
   [-RunAs32]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-ScheduledJobOption <ScheduledJobOptions>]
   [-InputObject] <ScheduledJobDefinition>
   [-MaxResultCount <Int32>]
   [-PassThru]
   [-ArgumentList <Object[]>]
   [-RunNow]
   [-RunEvery <TimeSpan>]
   [<CommonParameters>]
Set-ScheduledJob
   [-Name <String>]
   [-FilePath <String>]
   [-Trigger <ScheduledJobTrigger[]>]
   [-InitializationScript <ScriptBlock>]
   [-RunAs32]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-ScheduledJobOption <ScheduledJobOptions>]
   [-InputObject] <ScheduledJobDefinition>
   [-MaxResultCount <Int32>]
   [-PassThru]
   [-ArgumentList <Object[]>]
   [-RunNow]
   [-RunEvery <TimeSpan>]
   [<CommonParameters>]
Set-ScheduledJob
   [-InputObject] <ScheduledJobDefinition>
   [-ClearExecutionHistory]
   [-PassThru]
   [<CommonParameters>]

Description

O cmdlet Set-ScheduledJob altera as propriedades de trabalhos agendados, como os comandos executados pelos trabalhos ou as credenciais necessárias para executar o trabalho. Você também pode usá-lo para limpar o histórico de execução do trabalho agendado.

Para usar esse cmdlet, comece usando o cmdlet Get-ScheduledJob para obter o trabalho agendado. Em seguida, redirecione o trabalho agendado para set-ScheduledJob ou salve o trabalho em uma variável e use o parâmetro InputObject para identificar o trabalho. Use os parâmetros restantes de Set-ScheduledJob para alterar as propriedades do trabalho ou limpar o histórico de execução.

Embora você possa usar Set-ScheduledJob para alterar os gatilhos e opções de um trabalho agendado, os cmdlets Add-JobTrigger, Set-JobTrigger e Set-ScheduledJobOption fornecem maneiras muito mais fáceis de realizar essas tarefas. Para criar um novo trabalho agendado, use o cmdlet Register-ScheduledJob.

O parâmetro gatilho de de set-scheduledJob adiciona um ou mais gatilhos de trabalho que iniciam o trabalho. O parâmetro Gatilho é opcional, portanto, você pode adicionar gatilhos ao criar o trabalho agendado, adicionar gatilhos de trabalho mais tarde, adicionar o parâmetro RunNow para iniciar o trabalho imediatamente, usar o cmdlet Start-Job para iniciar o trabalho imediatamente a qualquer momento ou salvar o trabalho agendado não verificado como um modelo para outros trabalhos.

Set-ScheduledJob é um de uma coleção de cmdlets de agendamento de trabalho no módulo PSScheduledJob incluído no Windows PowerShell.

Para obter mais informações sobre trabalhos agendados, consulte os tópicos sobre no módulo PSScheduledJob. Importe o módulo PSScheduledJob e digite: Get-Help about_Scheduled* ou veja about_Scheduled_Jobs.

Esse cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: alterar o script executado por um trabalho

PS C:\> Get-ScheduledJob -Name "Inventory"
Id         Name            Triggers        Command                                  Enabled
--         ----            --------        -------                                  -------
1          Inventory       {1}             C:\Scripts\Get-Inventory.ps1             True

The second command uses the Get-ScheduledJob cmdlet to get the Inventory scheduled job. A pipeline operator (|) sends the scheduled job to the **Set-ScheduledJob** cmdlet. The **Set-ScheduledJob** cmdlet uses the *Script* parameter to specify a new script, Get-FullInventory.ps1. The command uses the *Passthru* parameter to return the scheduled job after the change.
PS C:\> Get-ScheduledJob -Name "Inventory" | Set-ScheduledJob -FilePath "C:\Scripts\Get-FullInventory.ps1" -Passthru
Id         Name            Triggers        Command                                  Enabled
--         ----            --------        -------                                  -------
1          Inventory       {1}             C:\Scripts\Get-FullInventory.ps1         True

Este exemplo mostra como alterar o script executado em um trabalho agendado.

O primeiro comando usa o cmdlet Get-ScheduledJob para obter o trabalho agendado de Inventário. A saída mostra que o trabalho executa o script Get-Inventory.ps1.

Esse comando não é necessário; ele é incluído apenas para mostrar o efeito da alteração do script.

Exemplo 2: excluir o histórico de execução de um trabalho agendado

PS C:\> Get-ScheduledJob BackupArchive | Set-ScheduledJob -ClearExecutionHistory

Esse comando exclui o histórico de execução atual e os resultados salvos do trabalho agendado do BackupArchive.

O comando usa o cmdlet Get-ScheduledJob para obter o trabalho agendado do BackupArchive. Um operador de pipeline (|) envia o trabalho para o cmdlet Set-ScheduledJob para alterá-lo. O cmdlet Set-ScheduledJob usa o parâmetro ClearExecutionHistory para excluir o histórico de execução e os resultados salvos.

Para obter mais informações sobre o histórico de execução e os resultados salvos do trabalho de trabalhos agendados, consulte about_Scheduled_Jobs.

Exemplo 3: alterar trabalhos agendados em um computador remoto

PS C:\> Invoke-Command -Computer "Server01, Server02" -ScriptBlock {Get-ScheduledJob | Set-ScheduledJob -InitializationScript \\SrvA\Scripts\SetForRun.ps1}

Esse comando altera o script de inicialização em todos os trabalhos agendados nos computadores Server01 e Server02.

O comando usa o cmdlet Invoke-Command para executar um comando nos computadores Server01 e Server02.

O comando remoto começa com um comando Get-ScheduledJob que obtém todos os trabalhos agendados no computador. Os trabalhos agendados são canalizados para o cmdlet Set-ScheduledJob, que altera o script de inicialização para SetForRun.ps1.

Parâmetros

-ArgumentList

Especifica valores para os parâmetros do script especificado pelo parâmetro FilePath ou para o comando especificado pelo parâmetro ScriptBlock.

Tipo:Object[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário. Os valores aceitáveis para este parâmetro são:

  • Inadimplência
  • Básico
  • Credssp
  • Digerir
  • Kerberos
  • Negociar
  • NegotiateWithImplicitCredential

O valor padrão é Default. Para obter mais informações sobre os valores desse parâmetro, consulte de Enumeração AuthenticationMechanism na biblioteca MSDN.

Cuidado: a autenticação credSSP (Provedor de Suporte à Segurança de Credencial), na qual as credenciais do usuário são passadas para um computador remoto a ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais passadas para ele poderão ser usadas para controlar a sessão de rede.

Tipo:AuthenticationMechanism
Valores aceitos:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Cargo:Named
Valor padrão:Default
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ClearExecutionHistory

Exclui o histórico de execução atual e os resultados salvos do trabalho agendado.

O histórico de execução do trabalho e os resultados do trabalho são salvos com o trabalho agendado no diretório $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs no computador no qual o trabalho é criado. Para ver o histórico de execução, use o cmdlet Get-Job. Para obter os resultados do trabalho, use o cmdlet Receive-Job.

Esse parâmetro não afeta os eventos que o Agendador de Tarefas grava nos logs de eventos do Windows e não impede o Windows PowerShell de salvar resultados do trabalho. Para gerenciar o número de resultados do trabalho salvos, use o parâmetro MaxResultCount.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Credential

Especifica uma conta de usuário que tem permissão para executar o trabalho agendado. O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential , como um do cmdlet Get-Credential. Se você inserir apenas um nome de usuário, será solicitado que você solicite uma senha.

Tipo:PSCredential
Cargo:Named
Valor padrão:Current user
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FilePath

Especifica um script que o trabalho agendado executa. Insira o caminho para um arquivo .ps1 no computador local. Para especificar valores padrão para os parâmetros de script, use o parâmetro ArgumentList. Cada trabalho agendado deve ter um ScriptBlock ou valor de filepath.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InitializationScript

Especifica o caminho totalmente qualificado para um script do Windows PowerShell (.ps1). O script de inicialização é executado na sessão criada para o trabalho em segundo plano antes dos comandos especificados pelo parâmetro ScriptBlock ou pelo script especificado pelo parâmetro FilePath. Você pode usar o script de inicialização para configurar a sessão, como adicionar arquivos, funções ou aliases, criar diretórios ou verificar se há pré-requisitos.

Para especificar um script que executa os comandos de trabalho primário, use o parâmetro FilePath.

Se o script de inicialização gerar um erro, incluindo um erro de não encerramento, a instância atual do trabalho agendado não será executada e seu status falhará.

Tipo:ScriptBlock
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InputObject

Especifica o trabalho agendado a ser alterado. Insira uma variável que contenha objetos ScheduledJobDefinition ou digite um comando ou expressão que obtém objetos ScheduledJobDefinition, como um comando Get-ScheduledJob. Você também pode canalizar um objeto ScheduledJobDefinition para Set-ScheduledJob .

Se você especificar vários trabalhos agendados, Set-ScheduledJob fará as mesmas alterações em todos os trabalhos.

Tipo:ScheduledJobDefinition
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-MaxResultCount

Especifica quantas entradas de resultado do trabalho são mantidas para o trabalho agendado. O valor padrão é 32.

O Windows PowerShell salva o histórico de execução e os resultados de cada instância disparada do trabalho agendado em disco. O valor desse parâmetro determina o número de resultados da instância de trabalho que são salvos para esse trabalho agendado. Quando o número de resultados da instância de trabalho excede esse valor, o Windows PowerShell exclui os resultados da instância de trabalho mais antiga para abrir espaço para os resultados da instância de trabalho mais recente.

O histórico de execução do trabalho e os resultados do trabalho são salvos nos diretórios $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> no computador no qual o trabalho é criado. Para ver o histórico de execução, use o cmdlet Get-Job. Para obter os resultados do trabalho, use o cmdlet Receive-Job.

O parâmetro MaxResultCount define o valor da propriedade ExecutionHistoryLength do trabalho agendado.

Para excluir o histórico de execução atual e os resultados do trabalho, use o parâmetro ClearExecutionHistory.

Tipo:Int32
Cargo:Named
Valor padrão:32
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Name

Especifica um novo nome para o trabalho agendado e instâncias do trabalho agendado. O nome deve ser exclusivo no computador local.

Para identificar o trabalho agendado a ser alterado, use o parâmetro InputObject ou pipe de um trabalho agendado de Get-ScheduledJob para Set-ScheduledJob.

Esse parâmetro não altera os nomes das instâncias de trabalho no disco. Ele afeta apenas as instâncias de trabalho que são iniciadas após a conclusão desse comando.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-PassThru

Retorna um objeto que representa o item com o qual você está trabalhando. Por padrão, esse cmdlet não gera nenhuma saída.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RunAs32

Executa o trabalho agendado em um processo de 32 bits.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RunEvery

Usado para especificar com que frequência executar o trabalho. Por exemplo, use essa opção para executar um trabalho a cada 15 minutos.

Tipo:TimeSpan
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RunNow

Inicia um trabalho imediatamente, assim que o cmdlet Set-ScheduledJob é executado. Esse parâmetro elimina a necessidade de disparar o Agendador de Tarefas para executar um script do Windows PowerShell imediatamente após o registro e não exige que os usuários criem um gatilho que especifique uma data e hora de início.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ScheduledJobOption

Define opções para o trabalho agendado. Insira um objeto ScheduledJobOptions, como um que você cria usando o cmdlet New-ScheduledJobOption ou um valor de tabela de hash.

Você pode definir opções para um trabalho agendado ao registrar o trabalho agendado ou usar o Set-ScheduledJobOption ou cmdlets set-scheduledJob para definir ou alterar opções.

Muitas das opções e seus valores padrão determinam se e quando um trabalho agendado é executado. Verifique essas opções antes de agendar um trabalho. Para obter uma descrição das opções de trabalho agendadas, incluindo os valores padrão, consulte New-ScheduledJobOption.

Para enviar uma tabela de hash, use as seguintes chaves. Na tabela de hash a seguir, as chaves são mostradas com seus valores padrão.

@{# Power SettingsStartIfOnBattery=$False;StopIfGoingOnBattery=$True; WakeToRun=$False; # Idle SettingsStartIfNotIdle=$False; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$True; RestartOnIdleResume=$False;# Security settingsShowInTaskScheduler=$TrueRunElevated=$False;# MiscRunWithoutNetwork=$False;DoNotAllowDemandStart=$False;MultipleInstancePolicy=IgnoreNew# Can be IgnoreNew, Parallel, Queue, StopExisting}

Tipo:ScheduledJobOptions
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ScriptBlock

Especifica os comandos que o trabalho agendado executa. Coloque os comandos em chaves ( { } ) para criar um bloco de script. Para especificar valores padrão para parâmetros de comando, use o parâmetro ArgumentList.

Cada comando Register-ScheduledJob deve usar os parâmetros ScriptBlock ou .

Tipo:ScriptBlock
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Trigger

Especifica os gatilhos para o trabalho agendado. Insira um ou mais objetos ScheduledJobTrigger, como os objetos que o cmdlet New-JobTrigger retorna ou uma tabela de hash de chaves e valores de gatilho de trabalho.

Um gatilho de trabalho inicia um trabalho agendado automaticamente em um agendamento único ou recorrente ou quando ocorre um evento.

Gatilhos de trabalho são opcionais. Você pode adicionar um gatilho ao criar o trabalho agendado, usar os cmdlets Add-JobTrigger ou Set-ScheduledJob para adicionar gatilhos posteriormente ou usar o cmdlet Start-Job para iniciar o trabalho agendado imediatamente. Você também pode criar e manter um trabalho agendado que não tenha gatilhos de trabalho.

Para enviar uma tabela de hash, use as seguintes chaves.

@{Frequency="Once" (or Daily, Weekly, AtStartup, AtLogon);At="3am" (ou qualquer cadeia de caracteres de tempo válida); DaysOfWeek="Monday", "Wednesday" (ou qualquer combinação de nomes de dia); Interval=2 (ou qualquer intervalo de frequência válido); RandomDelay="30minutes" (ou qualquer cadeia de caracteres de tempo válida); User="Domain1\User01" (ou qualquer usuário válido; usado somente com o valor de frequência AtLogon)

}

Tipo:ScheduledJobTrigger[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

ScheduledJobDefinition

Você pode canalizar trabalhos agendados para Set-ScheduledJob.

Saídas

None or Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

Se você usar o parâmetro Passthru, Set-ScheduledJob retornará o trabalho agendado que foi alterado. Caso contrário, esse cmdlet não gerará nenhuma saída.