New-JobTrigger

  • Referência
Módulo:
PSScheduledJob

Cria um gatilho de trabalho para um trabalho agendado.

Syntax

New-JobTrigger
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-Once]
   [-RepetitionInterval <TimeSpan>]
   [-RepetitionDuration <TimeSpan>]
   [-RepeatIndefinitely]
   [<CommonParameters>]
New-JobTrigger
   [-DaysInterval <Int32>]
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-Daily]
   [<CommonParameters>]
New-JobTrigger
   [-WeeksInterval <Int32>]
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   -DaysOfWeek<DayOfWeek[]>
   [-Weekly]
   [<CommonParameters>]
New-JobTrigger
   [-RandomDelay <TimeSpan>]
   [-AtStartup]
   [<CommonParameters>]
New-JobTrigger
   [-RandomDelay <TimeSpan>]
   [-User <String>]
   [-AtLogOn]
   [<CommonParameters>]

Description

O New-JobTrigger cmdlet cria um gatilho de trabalho que inicia um trabalho agendado em uma agenda única ou recorrente, ou quando ocorre um evento.

Você pode usar o objeto ScheduledJobTrigger que New-JobTrigger retorna para definir um gatilho de trabalho para um trabalho agendado novo ou existente. Você também pode criar um gatilho de trabalho com o cmdlet para obter o gatilho de trabalho de um trabalho agendado existente ou com um valor de tabela de hash para representar um gatilho Get-JobTrigger de trabalho.

Ao criar um gatilho New-ScheduledJobOption de trabalho, revise os valores padrão das opções especificadas pelo cmdlet. Essas opções, que têm os mesmos valores válidos e padrão que as opções correspondentes no Agendador de Tarefas, afetam o agendamento e o tempo dos trabalhos agendados.

New-JobTrigger é 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: Uma vez agendado

Este exemplo cria um gatilho de trabalho para iniciar um trabalho agendado apenas uma vez.

New-JobTrigger -Once -At "1/20/2012 3:00 AM"

O New-JobTrigger cmdlet para criar um gatilho de trabalho que inicia um trabalho agendado apenas uma vez. O valor do parâmetro At é uma cadeia de caracteres que o Windows PowerShell converte em um objeto DateTime.

O valor do parâmetro At inclui uma data explícita, não apenas uma hora. Se a data fosse omitida, o gatilho seria criado com a data atual e a hora das 3h00, o que provavelmente representará uma hora no passado.

Exemplo 2: Horário Diário

Este exemplo cria um novo gatilho de trabalho para iniciar um trabalho agendado a cada três dias.

New-JobTrigger -Daily -At "4:15 AM" -DaysInterval 3

Este comando cria um gatilho de trabalho que inicia um trabalho agendado a cada 3 dias às 4h15.

Como o valor do parâmetro At não inclui uma data, a data atual é usada como o valor de data no objeto DateTime . Se a data e a hora estiverem no passado, o trabalho agendado será iniciado na próxima ocorrência, que é 3 dias depois do valor do parâmetro At .

Exemplo 3: Programação semanal

Este exemplo cria um gatilho de trabalho que inicia um trabalho agendado a cada quatro semanas em dias especificados dessa semana.

New-JobTrigger -Weekly -DaysOfWeek Monday, Wednesday, Friday -At "23:00" -WeeksInterval 4

Id Frequency Time                  DaysOfWeek                  Enabled
-- --------- ----                  ----------                  -------
0  Weekly    9/21/2012 11:00:00 PM {Monday, Wednesday, Friday} True

Este comando cria um gatilho de trabalho para iniciar um trabalho agendado na segunda, quarta e sexta-feira às 2300 horas (23:00) a cada 4 semanas.

Você também pode inserir o valor do parâmetro DaysOfWeek em números inteiros, como -DaysOfWeek 1, 5.

Exemplo 4: Agendamento de logon

Este exemplo cria um gatilho de trabalho para iniciar um trabalho agendado no logon de um usuário específico.

New-JobTrigger -AtLogOn -User Domain01\Admin01

Esse comando cria um gatilho de trabalho para iniciar um trabalho agendado sempre que o administrador do domínio fizer logon no computador.

Exemplo 5: Usando um atraso aleatório

Este exemplo cria um novo gatilho de trabalho com um atraso aleatório de intervalo de tempo.

New-JobTrigger -Daily -At 1:00 -RandomDelay 00:20:00

Este comando cria um gatilho de trabalho para iniciar um trabalho agendado todos os dias à 1:00 da manhã. O comando usa o parâmetro RandomDelay para definir o atraso máximo para 20 minutos. Como resultado, o trabalho é executado todos os dias entre 1h00 e 1h20, com o intervalo variando pseudo-aleatoriamente.

Você pode usar um atraso aleatório para amostragem, balanceamento de carga e outras tarefas administrativas. Ao definir o valor de atraso, revise os New-ScheduledJobOption valores efetivo e padrão do cmdlet e coordene o atraso com as configurações de opção.

Exemplo 6: Criar um gatilho de trabalho para um novo trabalho agendado

Este exemplo usa um gatilho de trabalho para criar um novo trabalho agendado.

$t = New-JobTrigger -Weekly -DaysOfWeek 1,3,5 -At 12:01AM
Register-ScheduledJob -Name Test-HelpFiles -FilePath C:\Scripts\Test-HelpFiles.ps1 -Trigger $t

O primeiro comando usa o cmdlet para criar um gatilho New-JobTrigger de trabalho que inicia um trabalho todas as segundas, quartas e sextas-feiras, às 12h01. O comando salva o gatilho $t de trabalho na variável.

O segundo comando usa o Register-ScheduledJob cmdlet para criar um trabalho agendado que inicia um trabalho todas as segundas, quartas e sextas-feiras às 12h01. O valor do parâmetro Trigger é o gatilho armazenado na $t variável.

Exemplo 7: Adicionar um gatilho de trabalho a um trabalho agendado

Este exemplo mostra como adicionar um gatilho de trabalho a um trabalho agendado existente.

Add-JobTrigger -Name SynchronizeApps -Trigger (New-JobTrigger -Daily -At 3:10AM)

Você pode adicionar vários gatilhos de trabalho a qualquer trabalho agendado.

O comando usa o Add-JobTrigger cmdlet para adicionar o gatilho de trabalho ao trabalho agendado SynchronizeApps . O valor do parâmetro Trigger é um New-JobTrigger comando que executa o trabalho todos os dias às 3h10.

Quando o comando é concluído, SynchronizeApps é um trabalho agendado que é executado nos horários especificados pelo gatilho de trabalho.

Exemplo 8: Criar um gatilho de trabalho repetitivo

Este exemplo cria um gatilho de trabalho repetitivo para ser executado apenas por um período de tempo específico.

New-JobTrigger -Once -At "09/12/2013 1:00:00" -RepetitionInterval (New-TimeSpan -Hours 1) -RepetitionDuration (New-Timespan -Hours 48)

Este comando cria um gatilho de trabalho que executa um trabalho a cada 60 minutos durante 48 horas a partir de 12 de setembro de 2013 à 1h00.

Exemplo 9: Parar um gatilho de trabalho repetitivo

Este exemplo interrompe um gatilho de trabalho repetido.

Get-JobTrigger -Name SecurityCheck | Set-JobTrigger -RepetitionInterval 0:00 -RepetitionDuration 0:00

Este comando interrompe à força o trabalho SecurityCheck, que é acionado para ser executado a cada 60 minutos até que o gatilho do trabalho expire.

Para evitar que o trabalho se repita, o comando usa o Get-JobTrigger para obter o gatilho de trabalho do trabalho SecurityCheck e o Set-JobTrigger cmdlet para alterar o intervalo de repetição e a duração de repetição do gatilho de trabalho para zero (0).

Exemplo 10: Criar um gatilho de trabalho por hora

Este exemplo cria um gatilho de trabalho repetitivo que é executado indefinidamente.

New-JobTrigger -Once -At "9/21/2012 0am" -RepetitionInterval (New-TimeSpan -Hour 12) -RepetitionDuration ([TimeSpan]::MaxValue)

O comando a seguir cria um gatilho de trabalho que executa um trabalho agendado uma vez a cada 12 horas por um período de tempo indefinido. A programação começa amanhã (21/09/2012) à meia-noite (0h00).

Parâmetros

-At

Inicia o trabalho na data e hora especificadas. Insira um objeto DateTime , como um que o Get-Date cmdlet retorna, ou uma cadeia de caracteres que possa ser convertida em data e hora, como April 19, 2012 15:00, 12/31ou 3am. Se você não especificar um elemento da data, como o ano, a data no gatilho terá o elemento correspondente da data atual.

Ao usar o parâmetro Once , defina o valor do parâmetro At para uma data e hora futuras. Como a data padrão em um objeto DateTime é a data atual, se você especificar uma hora antes da hora atual sem uma data explícita, o gatilho de trabalho será criado para uma hora no passado.

Os objetos DateTime e as cadeias de caracteres convertidas em objetos DateTime são ajustados automaticamente para serem compatíveis com os formatos de data e hora selecionados para o computador local em Região e Idioma no Painel de Controle.

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

-AtLogOn

Inicia o trabalho agendado quando os usuários especificados fazem logon no computador. Para especificar um usuário, use o parâmetro User .

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

-AtStartup

Inicia o trabalho agendado quando o Windows é iniciado.

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

-Daily

Especifica uma agenda de trabalho diária recorrente. Use os outros parâmetros no conjunto de parâmetros Daily para especificar os detalhes da programação.

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

-DaysInterval

Especifica o número de dias entre ocorrências em uma programação diária. Por exemplo, um valor de inicia o trabalho agendado 3 em dias 1, 74e assim por diante. O valor predefinido é 1.

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

-DaysOfWeek

Especifica os dias da semana em que um trabalho agendado semanal é executado. Insira nomes de dias, como Monday inteiros ou inteiros 0-6, onde 0 representa Domingo. Este parâmetro é necessário no conjunto de parâmetros Weekly .

Os nomes de dia são convertidos em seus valores inteiros no gatilho de trabalho. Quando você colocar nomes de dias entre aspas em um comando, coloque o nome de cada dia entre aspas separadas, como "Monday", "Tuesday". Se você incluir vários nomes de dias em um único par de aspas, os valores inteiros correspondentes serão somados. Por exemplo, "Monday, Tuesday" (1 + 2) resulta em um valor de Wednesday (3).

Type:DayOfWeek[]
Accepted values:Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Once

Especifica uma agenda de repetição não recorrente (uma vez) ou personalizada. Para criar uma agenda de repetição, use o parâmetro Once com os parâmetros RepetitionDuration e RepetitionInterval .

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

-RandomDelay

Permite um atraso aleatório que começa na hora de início agendada e define o valor máximo de atraso. A duração do atraso é definida pseudo-aleatoriamente para cada início e varia de nenhum atraso ao tempo especificado pelo valor deste parâmetro. O valor padrão, zero (00:00:00), desativa o atraso aleatório.

Insira um objeto timespan, como um retornado pelo New-TimeSpan cmdlet, ou insira um valor no <hours>:<minutes>:<seconds> formato, que é convertido automaticamente em um objeto TimeSpan .

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

-RepeatIndefinitely

Esse parâmetro, disponível a partir do Windows PowerShell 4.0, elimina a necessidade de especificar um valor TimeSpan.MaxValue para o parâmetro RepetitionDuration para executar um trabalho agendado repetidamente, por um período indefinido.

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

-RepetitionDuration

Repete o trabalho até que o tempo especificado expire. A frequência de repetição é determinada pelo valor do parâmetro RepetitionInterval . Por exemplo, se o valor de RepetitionInterval for 5 minutos e o valor de RepetitionDuration for 2 horas, o trabalho será acionado a cada cinco minutos durante duas horas.

Insira um objeto timespan, como um que o New-TimeSpan cmdlet retorna ou uma cadeia de caracteres que pode ser convertida em um objeto timespan, como 1:05:30.

Para executar um trabalho indefinidamente, adicione o parâmetro RepeatIndefinidamente .

Para interromper um trabalho antes que a duração da repetição do gatilho do trabalho expire, use o Set-JobTrigger cmdlet para definir o valor RepetitionDuration como zero (0).

Esse parâmetro é válido somente quando os parâmetros Once, At e RepetitionInterval são usados no comando.

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

-RepetitionInterval

Repete o trabalho no intervalo de tempo especificado. Por exemplo, se o valor desse parâmetro for 2 horas, o trabalho será acionado a cada duas horas. O valor padrão, 0, não repete o trabalho.

Insira um objeto timespan, como um que o New-TimeSpan cmdlet retorna ou uma cadeia de caracteres que pode ser convertida em um objeto timespan, como 1:05:30.

Esse parâmetro é válido somente quando os parâmetros Once, At e RepetitionDuration são usados no comando.

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

-User

Especifica os usuários que disparam um início AtLogon de um trabalho agendado. Digite o nome de um usuário em <UserName> ou formato ou <Domain\Username> digite um asterisco (*) para representar todos os usuários. O valor padrão é todos os usuários.

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

-Weekly

Especifica uma agenda de trabalho semanal recorrente. Use os outros parâmetros no conjunto de parâmetros Weekly para especificar os detalhes da programação.

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

-WeeksInterval

Especifica o número de semanas entre ocorrências em um cronograma de trabalho semanal. Por exemplo, um valor de inicia o trabalho agendado 3 em semanas 1, 74e assim por diante. O valor predefinido é 1.

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

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger

Este cmdlet retorna um objeto ScheduledJobTrigger que representa o gatilho criado.

Notas

  • Os gatilhos de trabalho não são salvos no disco. No entanto, os trabalhos agendados são salvos no disco e você pode usar o Get-JobTrigger para obter o gatilho de trabalho de qualquer trabalho agendado.

  • New-JobTrigger não impede que você crie um gatilho de trabalho que não executará um trabalho agendado, como um gatilho único para uma data no passado.

  • O Register-ScheduledJob cmdlet aceita um objeto ScheduledJobTrigger , como um retornado pelos New-JobTrigger cmdlets ou Get-JobTrigger ou uma tabela de hash com valores de gatilho.

    Para submeter uma tabela hash, utilize as seguintes chaves.

    • Frequência: Once, Daily, , WeeklyAtStartup, ouAtLogon
    • At: qualquer cadeia de tempo válida, como 3am
    • DaysOfWeek: qualquer combinação de nomes de dias como strings, como "Monday", "Wednesday"
    • Intervalo: qualquer intervalo de frequência válido como um inteiro
    • RandomDelay: qualquer cadeia de caracteres de intervalo de tempo válida, como 30minutes
    • Usuário: qualquer usuário válido, como Domain1\User01; usado somente com o valor de frequência AtLogon