Compartilhar 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 hash para representar um gatilho de trabalho.

Ao criar um gatilho de trabalho, examine 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 do 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 veja about_Scheduled_Jobs.

Esse cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: uma vez agendada

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

Esse 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 3:00, o que provavelmente representará uma hora no passado.

Exemplo 2: Agendamento 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

Esse 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: Agendamento 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

Esse comando cria um gatilho de trabalho que inicia um trabalho agendado a cada 4 semanas na segunda, quarta e sexta-feira às 23h (23h).

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

Exemplo 4: Agendamento de Logon

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

Esse comando cria um gatilho de trabalho que inicia um trabalho agendado sempre que o administrador de domínio faz logon no computador.

Exemplo 5: Usando um atraso aleatório

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

Esse comando cria um gatilho de trabalho que inicia um trabalho agendado todos os dias à 1h da manhã. O comando usa o parâmetro RandomDelay para definir o atraso máximo como 20 minutos. Como resultado, o trabalho é executado todos os dias entre 1h 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, examine os valores efetivos 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 repetido

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

Esse comando cria um gatilho de trabalho que executa um trabalho a cada 60 minutos por 48 horas a partir de 12 de setembro de 2013, à 1h.

Exemplo 9: Parar um gatilho de trabalho repetido

PS C:\> Get-JobTrigger -Name SecurityCheck | Set-JobTrigger -RepetitionInterval 0:00 -RepetitionDuration 0:00

Esse comando interrompe à força o trabalho SecurityCheck, que é disparado para ser executado a cada 60 minutos até que o gatilho de trabalho expire.

Para impedir 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 da 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 tempo indefinido. A agenda começa amanhã (21/9/2012) à meia-noite (0h).

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 pode ser convertida em uma data e hora, como "19 de abril de 2012 15:00", "31/12" ou "3h". 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 como 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 por uma hora no passado.

objetos datetime e cadeias de caracteres que são convertidas em objetos DateTime, são ajustadas 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
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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
Cargo:0
Valor padrão:False
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-AtStartup

Inicia o trabalho agendado quando o Windows é iniciado.

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

-Daily

Especifica um agendamento de trabalho diário recorrente. Use os outros parâmetros no parâmetro Daily definido para especificar os detalhes do agendamento.

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

-DaysInterval

Especifica o número de dias entre ocorrências em um agendamento diário. 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
Cargo:Named
Valor padrão:1
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-DaysOfWeek

Especifica os dias da semana em que um trabalho agendado semanal é executado. Insira nomes de dia, como "Segunda-feira" ou inteiros 0-6, onde 0 representa domingo. Esse parâmetro é necessário no conjunto de parâmetros Semanal.

Os nomes de dia são convertidos em seus valores inteiros no gatilho de trabalho. Quando você coloca nomes de dia entre aspas em um comando, coloque o nome de cada dia entre aspas separadas, como "Segunda- feira", "Terça-feira". Se você colocar vários nomes de dia em um único par de aspas, os valores inteiros correspondentes serão resumidos. Por exemplo, "Segunda, Terça" (1, 2) resulta em um valor de "quarta-feira" (3).

Tipo:DayOfWeek[]
Valores aceitos:Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Once

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

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

-RandomDelay

Habilita um atraso aleatório que começa na hora de início agendada e define o valor máximo de atraso. O comprimento do atraso é definido pseudo aleatoriamente para cada início e varia de nenhum atraso até o tempo especificado pelo valor desse parâmetro. O valor padrão, zero (00:00:00), desabilita o atraso aleatório.

Insira um objeto de intervalo de tempo, como um retornado pelo cmdlet New-TimeSpan ou insira um valor em horas:minutos:segundos formato, que é automaticamente convertido em um objeto timeSpan .

Tipo:TimeSpan
Cargo:Named
Valor padrão:00:00:00
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 executar um trabalho agendado repetidamente, por um período indefinido.

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

-RepetitionDuration

Repete o trabalho até que a hora especificada 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 de 2 horas, o trabalho será disparado a cada cinco minutos por duas horas.

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

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

Para interromper um trabalho antes que a duração da repetição do gatilho de trabalho expire, use o cmdlet Set-JobTrigger 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.

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

-RepetitionInterval

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

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

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

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

-User

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

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

-Weekly

Especifica um agendamento de trabalho semanal recorrente. Use os outros parâmetros no conjunto de parâmetros Semanal para especificar os detalhes do agendamento.

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

-WeeksInterval

Especifica o número de semanas entre ocorrências em um agendamento 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
Cargo:Named
Valor padrão:1
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

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

Saídas

ScheduledJobTrigger

Observações

  • Gatilhos de trabalho não são salvos em disco. No entanto, trabalhos agendados são salvos em 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 pelo New-JobTrigger ou cmdlets 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 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 apenas com o AtLogon valor de frequência) }