Set-ScheduledJob

  • Referência
Módulo:
PSScheduledJob

Altera trabalhos agendados.

Syntax

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 Set-ScheduledJob cmdlet altera as propriedades de trabalhos agendados, como os comandos que os trabalhos executam 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 Get-ScheduledJob cmdlet para obter o trabalho agendado. Em seguida, canalize o trabalho agendado ou Set-ScheduledJob salve-o em uma variável e use o parâmetro InputObject para identificar o trabalho. Use os parâmetros restantes de para alterar as propriedades do trabalho ou limpar o histórico de Set-ScheduledJob execução.

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

O parâmetro Trigger de adiciona um ou mais gatilhos de Set-ScheduledJob trabalho que iniciam o trabalho. O parâmetro Trigger é opcional, portanto, você pode adicionar gatilhos ao criar o trabalho agendado, adicionar gatilhos de trabalho posteriormente, adicionar o parâmetro RunNow para iniciar o trabalho imediatamente, usar o Start-Job cmdlet para iniciar o trabalho imediatamente a qualquer momento ou salvar o trabalho agendado não acionado 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 consulte about_Scheduled_Jobs.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: Alterar o script que um trabalho executa

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

Get-ScheduledJob -Name "Inventory"

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

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

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

O segundo comando usa o Get-ScheduledJob cmdlet para obter o trabalho agendado de inventário. Um operador de pipeline (|) envia o trabalho agendado para o Set-ScheduledJob cmdlet. O Set-ScheduledJob cmdlet usa o parâmetro Script para especificar um novo script, Get-FullInventory.ps1. O comando usa o parâmetro Passthru para retornar o trabalho agendado após a alteração.

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

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

Este exemplo exclui o histórico de execução atual e os resultados de trabalho salvos de um trabalho agendado.

Get-ScheduledJob BackupArchive | Set-ScheduledJob -ClearExecutionHistory

O comando usa o Get-ScheduledJob cmdlet para obter o trabalho agendado BackupArchive. Um operador de pipeline (|) envia o trabalho ao Set-ScheduledJob cmdlet para alterá-lo. O Set-ScheduledJob cmdlet 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 de trabalhos salvos de trabalhos agendados, consulte about_Scheduled_Jobs.

Exemplo 3: Alterar trabalhos agendados num computador remoto

Este comando altera o script de inicialização em todos os trabalhos agendados em computadores remotos.

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

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

O comando remoto começa com um Get-ScheduledJob comando que obtém todos os trabalhos agendados no computador. Os trabalhos agendados são canalizados para o Set-ScheduledJob cmdlet, 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 .

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Authentication

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

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

O valor predefinido é Default. Para obter mais informações sobre os valores desse parâmetro, consulte Enumeração AuthenticationMechanism no SDK do PowerShell.

Atenção

A autenticação CredSSP (Credential Security Support Provider), na qual as credenciais do usuário são passadas para um computador remoto para ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Este mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas para ele podem ser usadas para controlar a sessão de rede.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ClearExecutionHistory

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

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

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Especifica uma conta de usuário que tem permissão para executar o trabalho agendado. A predefinição é o utilizador atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential , como um do Get-Credential cmdlet. Se introduzir apenas um nome de utilizador, ser-lhe-á solicitada uma palavra-passe.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 valor ScriptBlock ou FilePath .

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 pré-requisitos.

Para especificar um script que execute os comandos de trabalho primários, 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 será Falha.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 obtenha objetos ScheduledJobDefinition , como um Get-ScheduledJob comando. 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.

Type:Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-MaxResultCount

Especifica quantas entradas de resultado de 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 acionada do trabalho agendado no 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 e os resultados do trabalho são salvos no $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> diretórios no computador no qual o trabalho é criado. Para ver o histórico de execução, use o Get-Job cmdlet. Para obter os resultados do trabalho, use o Receive-Job cmdlet.

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 .

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 canalize um trabalho agendado de Get-ScheduledJob para Set-ScheduledJob.

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunAs32

Executa o trabalho agendado em um processo de 32 bits.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunNow

Inicia um trabalho imediatamente, assim que o Set-ScheduledJob cmdlet é executado. Esse parâmetro elimina a necessidade de acionar 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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ScheduledJobOption

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

Você pode definir opções para um trabalho agendado ao registrar o trabalho agendado ou usar os Set-ScheduledJobOption cmdlets ou 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. Certifique-se de revisar essas opções antes de agendar um trabalho. Para obter uma descrição das opções de trabalho agendado, incluindo os valores padrão, consulte New-ScheduledJobOption.

Para submeter uma tabela hash, utilize as seguintes chaves. Na tabela hash seguinte, as chaves são mostradas com os respetivos valores predefinidos.

@{# 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}

Type:Microsoft.PowerShell.ScheduledJob.ScheduledJobOptions
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

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

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

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Trigger

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

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

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

Para submeter uma tabela hash, utilize as seguintes chaves.

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

}

Type:Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

Você pode canalizar um trabalho agendado para este cmdlet.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

Quando você usa o parâmetro PassThru , esse cmdlet retorna o trabalho agendado que ele alterou.