Partilhar via

New-JobTrigger

  • Referência
Módulo:
PSScheduledJob

Cria um gatilho de trabalho para um trabalho agendado.

Sintaxe

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 cmdlet New-JobTrigger 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 usando o cmdlet Get-JobTrigger para obter o gatilho de trabalho de um trabalho agendado existente ou usando um valor de tabela de hash para representar um gatilho de trabalho.

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

New-JobTrigger faz parte 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.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: Uma vez agendado

PS C:\> New-JobTrigger -Once -At "1/20/2012 3:00 AM"

Este comando usa o cmdlet New-JobTrigger 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

PS C:\> New-JobTrigger -Daily -At "4:15 AM" -DaysInterval 3
Id         Frequency       Time                   DaysOfWeek              Enabled
--         ---------       ----                   ----------              -------
0          Daily           9/21/2012 4:15:00 AM                           True

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

PS C:\> 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 que inicia um trabalho agendado a cada 4 semanas às segundas, quartas e sextas-feiras às 2300 horas (23:00).

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

Exemplo 4: Agendamento de logon

PS C:\> New-JobTrigger -AtLogOn -User Domain01\Admin01

Este comando cria um gatilho de trabalho que inicia um trabalho agendado sempre que o administrador do domínio inicia sessão no computador.

Exemplo 5: Usando um atraso aleatório

PS C:\> New-JobTrigger -Daily -At 1:00 -RandomDelay 00:20:00

Este comando cria um gatilho de trabalho que inicia 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 valores efetivo e padrão do cmdlet New-ScheduledJobOption e coordene o atraso com as configurações de opção.

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

The first command uses the **New-JobTrigger** cmdlet to create a job trigger that starts a job every Monday, Wednesday, and Friday at 12:01 AM. The command saves the job trigger in the $T variable.
PS C:\> $T = New-JobTrigger -Weekly -DaysOfWeek 1,3,5 -At 12:01AM


The second command uses the Register-ScheduledJob cmdlet to create a scheduled job that starts a job every Monday, Wednesday, and Friday at 12:01 AM. The value of the *Trigger* parameter is the trigger that is stored in the $T variable.
PS C:\> Register-ScheduledJob -Name Test-HelpFiles -FilePath C:\Scripts\Test-HelpFiles.ps1 -Trigger $T

Esses comandos usam um gatilho de trabalho para criar um novo trabalho agendado.

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

PS C:\> Add-JobTrigger -Name SynchronizeApps -Trigger (New-JobTrigger -Daily -At 3:10AM)

Este exemplo mostra como adicionar um gatilho de trabalho a um trabalho agendado existente. Você pode adicionar vários gatilhos de trabalho a qualquer trabalho agendado.

O comando usa o cmdlet Add-JobTrigger para adicionar o gatilho de trabalho ao trabalho agendado SynchronizeApps. O valor do parâmetro Trigger é um comando New-JobTrigger 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

PS C:\> 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

PS C:\> 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 cmdlet Set-JobTrigger 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

PS C:\> 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 cmdlet Get-Date retorna, ou uma cadeia de caracteres que possa ser convertida em data e hora, como "19 de abril de 2012 15:00", "12/31" ou "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 do é a data atual, se você especificar uma hora antes da hora atual sem uma data explícita, o gatilho de trabalho será criado para um tempo no passado.

objetos de DateTime e cadeias de caracteres que são 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.

Tipo:DateTime
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:SwitchParameter
Position:0
Default value:False
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-AtStartup

Inicia o trabalho agendado quando o Windows é iniciado.

Tipo:SwitchParameter
Position:0
Default value:False
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:SwitchParameter
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-DaysInterval

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

Tipo:Int32
Position:Named
Default value:1
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-DaysOfWeek

Especifica os dias da semana em que um trabalho agendado semanal é executado. Insira nomes de dias, como "segunda-feira" ou inteiros de 0 a 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 "segunda-feira", "terça-feira". Se você incluir vários nomes de dias em um único par de aspas, os valores inteiros correspondentes serão somados. Por exemplo, "Segunda-feira, terça-feira" (1, 2) resulta em um valor de "quarta-feira" (3).

Tipo:DayOfWeek[]
Valores aceites:Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:SwitchParameter
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 cmdlet New-TimeSpan, ou insira um valor em <horas>:<minutos>:<segundos> formato, que é convertido automaticamente em um objeto TimeSpan.

Tipo:TimeSpan
Position:Named
Default value:00:00:00
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-RepeatIndefinitely

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

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 cmdlet New-TimeSpan 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 RepeatIndefinitely em vez disso.

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

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

Tipo:TimeSpan
Position:Named
Default value:0
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 cmdlet New-TimeSpan retorna ou uma cadeia de caracteres que pode ser convertida em um objeto timespan, como "1:05:30".

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

Tipo:TimeSpan
Position:Named
Default value:0
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-User

Especifica os usuários que acionam um AtLogon início de um trabalho agendado. Introduza o nome de um utilizador no formato <> Nome de Utilizador ou <Domínio\Nome de Utilizador> ou introduza um asterisco (*) para representar todos os utilizadores. O valor padrão é todos os usuários.

Tipo:String
Position:Named
Default value:All users
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:SwitchParameter
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-WeeksInterval

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

Tipo:Int32
Position:Named
Default value:1
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

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

Saídas

ScheduledJobTrigger

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 cmdlet Register-ScheduledJob aceita um objeto ScheduledJobTrigger, como um retornado pelos cmdlets New-JobTrigger ou Get-JobTrigger, ou uma tabela de hash com valores de gatilho.

    Para enviar uma tabela de hash, use 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 tempo válida); User="Domain1\User01 (ou qualquer usuário válido; usado apenas com o valor AtLogon frequência) }