New-JobTrigger

リファレンス

モジュール:: PSScheduledJob

スケジュールされたジョブのジョブトリガーを作成します。

構文

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>]

説明

New-JobTrigger コマンドレットは、1 回限りまたは定期的なスケジュールで、またはイベントが発生したときにスケジュールされたジョブを開始するジョブトリガーを作成します。

New-JobTrigger から返された ScheduledJobTrigger オブジェクトを使用して、新しいまたは既存のスケジュールされたジョブのジョブトリガーを設定できます。また、ジョブトリガーを作成するには、Get-JobTrigger コマンドレットを使用して、既存のスケジュールされたジョブのジョブトリガーを取得するか、ハッシュテーブル値を使用してジョブトリガーを表します。

ジョブトリガーを作成するときは、New-ScheduledJobOption コマンドレットで指定されたオプションの既定値を確認します。これらのオプションは、有効な値と既定値が Task Scheduler の対応するオプションと同じで、スケジュールされたジョブのスケジュールとタイミングに影響します。

New-JobTrigger は、Windows PowerShellに含まれる PSScheduledJob モジュール内のジョブスケジューリングコマンドレットのコレクションの 1 つです。

スケジュールされたジョブの詳細については、PSScheduledJob モジュールの概要トピックを参照してください。 PSScheduledJob モジュールをインポートし、次 Get-Help about_Scheduled* のように入力するか、about_Scheduled_Jobsを参照してください。

このコマンドレットは、Windows PowerShell 3.0 で導入されました。

例

例 1: 1 回のスケジュール

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

このコマンドは、New-JobTrigger コマンドレットを使用して、スケジュールされたジョブを 1 回だけ開始するジョブトリガーを作成します。 At パラメーターの値は、Windows PowerShell によって DateTime オブジェクトに変換される文字列です。 At パラメーターの値には、時刻だけでなく、明示的な日付も含まれています。日付を省略すると、現在の日付の午前 3 時 00 分のトリガーが作成されます。これは、過去の時刻を表す可能性があります。

例 2: 毎日のスケジュール

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

このコマンドは、3 日おきの午前 4 時 15 分にスケジュールされたジョブを開始するジョブトリガーを作成します。

At パラメーターの値には日付が含まれていないため、DateTime オブジェクトの日付の値として現在の日付が使用されます。日時が過去の場合、スケジュールされたジョブは次の実行日 (At パラメーターの値の 3 日後) に開始されます。

例 3: 週単位のスケジュール

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

このコマンドは、4 週間おきの月曜日、水曜日、および金曜日の 23:00 (午後 11 時 00 分) にスケジュールされたジョブを開始するジョブトリガーを作成します。

DaysOfWeek パラメーター値は、次のような-DaysOfWeek 1, 5整数で入力することもできます。

例 4: ログオンスケジュール

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

このコマンドは、ドメイン管理者がコンピューターにログオンするたびに、スケジュールされたジョブを開始するジョブトリガーを作成します。

例 5: ランダム遅延の使用

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

このコマンドは、毎日午前 1 時 00 分にスケジュールされたジョブを開始するジョブトリガーを作成します。このコマンドでは、RandomDelay パラメーターを使用して、遅延の最大値を 20 分に設定します。その結果、ジョブは、毎日午前 1 時 00 分から 1 時 20 分の間に実行されます (時刻は擬似ランダムに変動します)。

ランダムな遅延は、サンプリング、負荷分散、およびその他の管理タスクに使用できます。遅延値を設定するときは、New-ScheduledJobOption コマンドレットの有効な値と既定値を確認し、オプション設定で遅延を調整します。

例 6: 新しいスケジュールされたジョブのジョブトリガーを作成する

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

これらのコマンドは、ジョブトリガーを使用して、スケジュールされた新しいジョブを作成します。

例 7: スケジュールされたジョブにジョブトリガーを追加する

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

この例では、既存のスケジュールされたジョブにジョブトリガーを追加する方法を示します。任意のスケジュールされたジョブに複数のジョブトリガーを追加できます。

コマンドは、Add-JobTrigger コマンドレットを使用して、SynchronizeApps スケジュールされたジョブにジョブトリガーを追加します。 Trigger パラメーターの値は、毎日午前 3 時 10 分にジョブを実行する New-JobTrigger コマンドです。

コマンドが完了すると、SynchronizeApps は、ジョブトリガーで指定された時刻に実行されるスケジュールされたジョブになります。

例 8: 繰り返しジョブトリガーを作成する

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

このコマンドは、2013 年 9 月 12 日午前 1 時から 48 時間、60 分ごとにジョブを実行するジョブトリガーを作成します。

例 9: 繰り返しジョブトリガーを停止する

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

このコマンドは、トリガーされた SecurityCheck ジョブ (ジョブトリガーの期限が過ぎるまで 60 分おきに実行されます) を強制的に停止します。

ジョブの繰り返しを防ぐために、コマンドはGet-JobTriggerを使用して SecurityCheck ジョブのジョブトリガーを取得し、Set-JobTrigger コマンドレットを使用して、ジョブトリガーの繰り返し間隔と繰り返し期間を 0 に変更します。

例 10: 時間単位のジョブトリガーを作成する

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

次のコマンドは、無期限で、12 時間おきに 1 回スケジュールされたジョブを実行するジョブトリガーを作成します。スケジュールは、翌日 (2012 年 9 月 21 日) の午前 0 時 (0:00 AM) に開始されます。

パラメーター

-At

指定された日時にジョブを開始します。 dateTime オブジェクト (Get-Date コマンドレットが返すオブジェクトなど)、または日付と時刻に変換できる文字列 ("April 19, 2012 15:00"、"12/31"、"3am" など) を入力します。年などの日付の要素を指定しない場合、トリガーの日付には、現在の日付の対応する要素が使用されます。

Once パラメーターを使用する場合は、At パラメーターの値の設定を未来の日時に設定します。 DateTime オブジェクトの既定の日付は現在の日付です。そのため、日付を明示的に指定せずに、現在の時刻より前の時刻を指定すると、過去の時刻のジョブトリガーが作成されます。

DateTime オブジェクトと DateTime オブジェクトに変換される文字列は、コントロールパネルの地域と言語でローカルコンピューターに対して選択された日付と時刻の形式と互換性を持つよう自動的に調整されます。

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

-AtLogOn

指定されたユーザーがコンピューターにログオンしたときに、スケジュールされたジョブを開始します。ユーザーを指定するには、User パラメーターを使用します。

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

-AtStartup

Windows の起動時に、スケジュールされたジョブを開始します。

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

-Daily

日単位の定期的なジョブスケジュールを指定します。スケジュールの詳細を指定するには、[ 日単位 ] パラメーターセットの他のパラメーターを使用します。

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

-DaysInterval

日単位のスケジュールの実行間隔を日数で指定します。たとえば、値が 3 の場合、スケジュールされたジョブは、1 日、4 日、7 日というように 3 日おきに開始されます。既定値は 1 です。

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

-DaysOfWeek

週単位でスケジュールされたジョブを実行する曜日を指定します。 "Monday" などの曜日名または 0 ～ 6 の整数 (0 は日曜日を表します) を入力します。 Weekly パラメーターセットでは、このパラメーターは必須です。

ジョブトリガーでは、曜日名は整数値に変換されます。コマンド内で曜日名を引用符で囲む場合は、"Monday", "Tuesday" など、各曜日名を別々に引用符で囲みます。複数の曜日名を 1 つの引用符のペアで囲んだ場合は、対応する整数値が合計されます。たとえば、"Monday, Tuesday" (1, 2) は、"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

非定期的な (1 回だけの) スケジュールまたは繰り返しのカスタムスケジュールを指定します。繰り返しのスケジュールを作成するには、Once パラメーターと一緒に RepetitionDuration パラメーターと RepetitionInterval パラメーターを使用します。

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

-RandomDelay

スケジュールされた開始時刻のランダムな遅延を有効にし、遅延の最大値を設定します。遅延の長さは、開始ごとに擬似ランダムに設定され、遅延なしから、このパラメーターの値で指定された時間の間で変動します。既定値のゼロ (00:00:00) では、ランダムな遅延が無効になります。

New-TimeSpan コマンドレットによって返されるタイムスパンオブジェクトを入力するか、timeSpan オブジェクトに自動的に変換される hours>:<minutes>:<seconds> 形式の<値を入力します。

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

-RepeatIndefinitely

このパラメーターは、Windows PowerShell 4.0 以降で利用でき、RepetitionDuration パラメーターの TimeSpan.MaxValue 値を指定することなく、スケジュールされたジョブを無期限に繰り返し実行します。

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

-RepetitionDuration

指定された期間を過ぎるまでジョブを繰り返し実行します。繰り返しの頻度は、RepetitionInterval パラメーターの値によって決まります。たとえば、RepetitionInterval の値が 5 分で、RepetitionDuration の値が 2 時間の場合、ジョブは 2 時間の間 5 分おきにトリガーされます。

New-TimeSpan コマンドレットから返されるタイムスパンオブジェクトや、"1:05:30" などのタイムスパンオブジェクトに変換できる文字列を入力します。

ジョブを無期限に実行するには、代わりに RepeatIndefinitely パラメーターを追加します。

ジョブトリガーの繰り返し期間が経過する前にジョブを停止するには、Set-JobTrigger コマンドレットを使用して 、RepetitionDuration 値を 0 に設定します。

このパラメーターは、Once、At、および RepetitionInterval パラメーターがコマンドで使用されている場合にのみ有効です。

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

-RepetitionInterval

ジョブは、指定された時間間隔で繰り返し実行されます。たとえば、このパラメーターの値が 2 時間の場合、ジョブは 2 時間おきにトリガーされます。既定値の 0 では、ジョブは繰り返し実行されません。

New-TimeSpan コマンドレットから返されるタイムスパンオブジェクトや、"1:05:30" などのタイムスパンオブジェクトに変換できる文字列を入力します。

このパラメーターは、Once、At、および RepetitionDuration パラメーターがコマンドで使用されている場合にのみ有効です。

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

-User

スケジュールされたジョブの AtLogon 開始をトリガーするユーザーを指定します。 UserName> または <Domain\Username> 形式で<ユーザーの名前を入力するか、アスタリスク (*) を入力してすべてのユーザーを表します。既定値は、すべてのユーザーです。

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

-Weekly

週単位の定期的なジョブスケジュールを指定します。 Weekly パラメーターセットの他のパラメーターを使用して、スケジュールの詳細を指定します。

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

-WeeksInterval

週単位のジョブスケジュールの実行間隔を週数で指定します。たとえば、値が 3 の場合、スケジュールされたジョブは、1 週目、4 週目、7 週目というように 3 週おきに開始されます。既定値は 1 です。

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

入力

None

パイプを使用してこのコマンドレットに入力を渡すことはできません。

出力

Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger

メモ

ジョブトリガーはディスクに保存されません。ただし、スケジュールされたジョブはディスクに保存され、Get-JobTriggerを使用してスケジュールされたジョブのジョブトリガーを取得できます。
New-JobTrigger では、過去の日付の 1 回限りのトリガーなど、スケジュールされたジョブを実行しないジョブトリガーを作成できません。
Register-ScheduledJob コマンドレットは、 New-JobTrigger コマンドレットや Get-JobTrigger コマンドレットによって返される ScheduledJobTrigger オブジェクトや、トリガー値を持つハッシュテーブルを受け取ります。

ハッシュテーブルを渡すには、次のキーを使用します。

@{Frequency="Once" (or Daily, Weekly, AtStartup, AtLogon);At="3am" (または任意の有効な時刻文字列); DaysOfWeek="Monday", "Wednesday" (または日の名前の任意の組み合わせ); Interval=2 (または任意の有効な頻度間隔); RandomDelay="30minutes" (または任意の有効な期間文字列); User="Domain1\User01 (または任意の有効なユーザー。 AtLogon 頻度値でのみ使用) }