Register-ScheduledJob

モジュール:

PSScheduledJob

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

構文

Register-ScheduledJob
        [-ScriptBlock] <ScriptBlock>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Register-ScheduledJob
        [-FilePath] <String>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

説明

Register-ScheduledJob コマンドレットは、ローカル コンピューターにスケジュールされたジョブを作成します。

スケジュールされたジョブは、1 回限りまたは定期的なスケジュールで自動的に開始できる Windows PowerShell バックグラウンド ジョブです。 スケジュールされたジョブはディスクに格納され、タスク スケジューラに登録されます。 ジョブは、タスク スケジューラで管理することも、Windows PowerShell のスケジュールされたジョブ コマンドレットを使用して管理することもできます。

スケジュールされたジョブが開始されると、スケジュールされたジョブのインスタンスが作成されます。 スケジュールされたジョブのインスタンスは、結果がディスクに保存される点を除き、Windows PowerShell のバックグラウンド ジョブと同じです。 ジョブ インスタンスの開始、表示、結果の取得には、 Start-Job、 Get-Job、 Receive-Job などのジョブ コマンドレットを使用します。

Register-ScheduledJobを使用して、新しいスケジュールされたジョブを作成します。 スケジュールされたジョブを実行するコマンドを指定するには、 ScriptBlock パラメーターを使用します。 ジョブを実行するスクリプトを指定するには、 FilePath パラメーターを使用します。

Windows PowerShell でスケジュールされたジョブでは、タスク スケジューラがスケジュールされたタスクに使用するのと同じジョブ トリガーとジョブ オプションが使用されます。

Register-ScheduledJob の Trigger パラメーターは、ジョブを開始する 1 つ以上のジョブ トリガーを追加します。 Trigger パラメーターは省略可能であるため、スケジュールされたジョブの作成時にトリガーを追加したり、後でジョブ トリガーを追加したり、RunNow パラメーターを追加してジョブをすぐに開始したり、Start-Job コマンドレットを使用していつでもすぐにジョブを開始したり、トリガーされていないスケジュールされたジョブを他のジョブのテンプレートとして保存したりできます。

Options パラメーターを使用すると、スケジュールされたジョブのオプション設定をカスタマイズできます。 Options パラメーターは省略可能であるため、スケジュールされたジョブを作成したり、いつでも変更したりするときにジョブ オプションを設定できます。 ジョブ オプションの設定によっては、スケジュールされたジョブが実行されない場合があるため、ジョブ オプションを確認し、慎重に設定してください。

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

スケジュールされたジョブの詳細については、 PSScheduledJob モジュールの About に関する記事を参照してください。 PSScheduledJob モジュールをインポートし、「Get-Help about_Scheduled*」と入力するか、about_Scheduled_Jobsを参照してください。

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

例

例 1: スケジュールされたジョブを作成する

次の使用例は、ローカル コンピューターにスケジュールされたジョブを作成します。

Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock {
  Get-ChildItem $HOME\*.ps1 -Recurse |
    Copy-Item -Destination "\\Server\Share\PSScriptArchive"
}

Register-ScheduledJob では、 Name パラメーターを使用して、スケジュールされたジョブ Archive-Scripts 作成します。 ScriptBlock パラメーターは、$HOME ディレクトリを再帰的に検索して.ps1 ファイルを検索するGet-ChildItemを実行します。 Copy-Item コマンドレットは、Destination パラメーターで指定されたディレクトリにファイルをコピーします。

スケジュールされたジョブにはトリガーが含まれていないため、自動的には開始されません。 Add-JobTriggerでジョブ トリガーを追加したり、Start-Job コマンドレットを使用してオンデマンドでジョブを開始したり、スケジュールされたジョブを他のスケジュールされたジョブのテンプレートとして使用したりできます。

例 2: トリガーとカスタム オプションを使用してスケジュールされたジョブを作成する

この例では、ジョブ トリガーとカスタムのジョブ オプションを指定して、スケジュールされたジョブを作成する方法を示します。

$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
$path = "\\Srv01\Scripts\UpdateVersion.ps1"
Register-ScheduledJob -Name "UpdateVersion" -FilePath $path -ScheduledJobOption $O -Trigger $T

$O変数には、New-ScheduledJobOption コマンドレットによって作成されたジョブ オプション オブジェクトが格納されます。 オプションは、コンピューターがアイドル状態でない場合でもスケジュールされたジョブを開始し、必要に応じてコンピューターを起動してジョブを実行し、ジョブの複数のインスタンスを 1 つのシリーズで実行できるようにします。

$T変数には、New-JobTrigger コマンドレットの結果が格納され、毎週月曜日の午後 9 時にジョブを開始するジョブ トリガーが作成されます。

$path変数には、UpdateVersion.ps1 スクリプト ファイルへのパスが格納されます。

Register-ScheduledJob では、 Name パラメーターを使用して、スケジュールされたジョブ UpdateVersion を作成します。 FilePath パラメーターは$pathを使用してジョブを実行するスクリプトを指定します。 ScheduledJobOption パラメーターは、$Oに格納されているジョブ オプションを使用します。 Trigger パラメーターは、$Tに格納されているジョブ トリガーを使用します。

例 3: ハッシュ テーブルを使用してトリガーとスケジュールされたジョブ オプションを指定する

この例は、例 2 のコマンドと同じ効果を持ちます。 スケジュールされたジョブを作成し、ハッシュ テーブルを使用して、 Trigger および ScheduledJobOption パラメーターの値を指定します。 例 2 で定義されている $O と $T変数は、ハッシュ テーブルに置き換えられます。

$T = @{
  Frequency="Weekly"
  At="9:00PM"
  DaysOfWeek="Monday"
  Interval=2
}
$O = @{
  WakeToRun=$true
  StartIfNotIdle=$false
  MultipleInstancePolicy="Queue"
}
Register-ScheduledJob -Trigger $T -ScheduledJobOption $O -Name UpdateVersion -FilePath "\\Srv01\Scripts\Update-Version.ps1"

例 4: リモート コンピューターでスケジュールされたジョブを作成する

この例では、 EnergyData スケジュールされたジョブが複数のリモート コンピューターに作成されます。 スケジュールされたジョブは、生データを収集し、リモート コンピューター上の実行中のログに保存するスクリプトを実行します。

$Cred = Get-Credential
$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Invoke-Command -ComputerName (Get-Content Servers.txt) -Credential $Cred -ScriptBlock {
  $params = @{
      Name = "Get-EnergyData"
      FilePath = "\\Srv01\Scripts\Get-EnergyData.ps1"
      ScheduledJobOption = $using:O
      Trigger = $using:T
  }
  Register-ScheduledJob @params
}

$Cred変数は、スケジュールされたジョブを作成する権限を持つユーザーのPSCredential オブジェクトに資格情報を格納します。 $O変数には、New-ScheduledJobOptionで作成されたジョブ オプションが格納されます。 $T変数には、New-JobTriggerで作成されたジョブ トリガーが格納されます。

Invoke-Command コマンドレットは、ComputerName パラメーターを使用して、Servers.txt ファイルからサーバー名の一覧を取得します。 Credential パラメーターは、$Credに格納されている資格情報オブジェクトを取得します。 ScriptBlock パラメーターは、Servers.txt ファイル内のコンピューターでRegister-ScheduledJob コマンドを実行します。

Register-ScheduledJobのパラメーターは、$paramsによって定義されます。 Name パラメーターは、各リモート コンピューターでジョブにGet-EnergyDataという名前を指定します。 FilePath は、 EnergyData.ps1 スクリプトの場所を提供します。 スクリプトは、参加しているすべてのコンピューターで使用できるファイル サーバー上にあります。ジョブは、 $T のジョブ トリガーと $Oのジョブ オプションによって指定されたスケジュールで実行されます。

Register-ScheduledJob @params コマンドは、スクリプト ブロックのパラメーターを使用してスケジュールされたジョブを作成します。

例 5: リモート コンピューターでスクリプトを実行するスケジュールされたジョブを作成する

次の使用例は CollectEnergyData スケジュールされたジョブをローカル コンピューターに作成します。 ジョブは複数のリモート コンピューターで実行されます。

$Admin = Get-Credential
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock {
  $params = @{
    AsJob = $true
    ComputerName = (Get-Content Servers.txt)
    FilePath = '\\Srv01\Scripts\Get-EnergyData.ps1'
    Credential = $using:Admin
    Authentication = 'CredSSP'
  }
  Invoke-Command @params
}

$Admin変数には、PSCredential オブジェクトでコマンドを実行するアクセス許可を持つユーザーの資格情報が格納されます。 $T変数には、New-JobTriggerで作成されたジョブ トリガーが格納されます。

Register-ScheduledJob コマンドレットは、Name パラメーターを使用して、ローカル コンピューターでスケジュールされたジョブCollectEnergyDataを作成します。 Trigger パラメーターは$Tでジョブ トリガーを指定し、MaxResultCount パラメーターは保存された結果の数を 99 に増やします。

ScriptBlock パラメーターは、$paramsを使用してInvoke-Commandパラメーターを定義します。 AsJob パラメーターは、Energydata.ps1 スクリプトがリモート コンピューターで実行されている場合でも、ローカル コンピューター上にバックグラウンド ジョブ オブジェクトを作成します。 ComputerName パラメーターは、Servers.txt ファイルからサーバー名の一覧を取得します。 Credential パラメーターは、リモート コンピューターでスクリプトを実行する権限を持つユーザー アカウントを指定します。 また、 Authentication パラメーターは、委任された資格情報を許可するために CredSSP の値を指定します。

Invoke-Command @paramsは、スクリプト ブロックのパラメーターを使用してコマンドを実行します。

パラメーター

-ArgumentList

FilePath パラメーターで指定されたスクリプトのパラメーター、または ScriptBlock パラメーターで指定されたコマンドの値を指定します。

型:	Object[]
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Authentication

ユーザーの資格情報の認証に使用するメカニズムを指定します。 既定値は Default です。

このパラメーターの有効値は、次のとおりです。

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

このパラメーターの値の詳細については、「 AuthenticationMechanismを参照してください。

注意事項

ユーザーの資格情報が認証されるリモート コンピューターにユーザーの資格情報が渡される資格情報セキュリティ サービス プロバイダー (CredSSP) 認証は、リモート ネットワーク共有へのアクセスなど、複数のリソースで認証を必要とするコマンド用に設計されています。 このメカニズムを使用すると、リモート操作のセキュリティ リスクが高まります。 リモート コンピューターのセキュリティが低下している場合は、そのリモート コンピューターに渡される資格情報を使用してネットワーク セッションが制御される場合があります。

型:	AuthenticationMechanism
指定可能な値:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Confirm

コマンドレットの実行前に確認を求めるメッセージが表示されます。

型:	SwitchParameter
Aliases:	cf
配置:	Named
規定値:	False
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Credential

スケジュールされたジョブを実行するアクセス許可を持つユーザー アカウントを指定します。 既定値は現在のユーザーです。

User01 や Domain01\User01 などのユーザー名を入力するか、Get-Credential コマンドレットのオブジェクトなど、PSCredential オブジェクトを入力します。 ユーザー名のみを入力すると、パスワードの入力を求められます。

資格情報は PSCredential オブジェクトに格納され、パスワードは SecureString として格納されます。

Note

SecureString データ保護の詳細については、「 SecureString のセキュリティ保護方法」を 参照してください。

型:	PSCredential
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-FilePath

スケジュールされたジョブで実行するスクリプトを指定します。 ローカル コンピューター上の .ps1 ファイルへのパスを入力します。 スクリプト パラメーターの既定値を指定するには、 ArgumentList パラメーターを使用します。 すべての Register-ScheduledJob コマンドでは、 ScriptBlock または FilePath パラメーターを使用する必要があります。

型:	String
配置:	1
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-InitializationScript

Windows PowerShell スクリプト (.ps1) への完全修飾パスを指定します。 初期化スクリプトは、 ScriptBlock パラメーターで指定されたコマンドまたは FilePath パラメーターで指定されたスクリプトの前に、バックグラウンド ジョブ用に作成されたセッションで実行されます。 初期化スクリプトを使用すると、ファイル、関数、またはエイリアスの追加、ディレクトリの作成、前提条件の確認など、セッションを構成することができます。

プライマリ ジョブ コマンドを実行するスクリプトを指定するには、 FilePath パラメーターを使用します。

初期化スクリプトでエラーが生成された場合 (終了しないエラーであっても)、スケジュールされたジョブの現在のインスタンスは実行されません。その状態は Failed。

型:	ScriptBlock
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-MaxResultCount

スケジュールされたジョブに対して保持されるジョブの結果のエントリ数を指定します。 既定値は 32 です。

Windows PowerShell では、スケジュールされたジョブのトリガーされた各インスタンスの実行履歴と結果をディスクに保存します。 このパラメーターの値により、このスケジュールされたジョブに対して保存されるジョブ インスタンスの結果の数が決まります。 ジョブ インスタンスの結果の数がこの値を超えた場合は、最新のジョブ インスタンスの結果を保存するために、最も古いジョブ インスタンスの結果が削除されます。

ジョブの実行履歴とジョブの結果は、$HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> ジョブが作成されるコンピューター上のディレクトリ。 実行履歴を表示するには、 Get-Job コマンドレットを使用します。 ジョブの結果を取得するには、 Receive-Job コマンドレットを使用します。

MaxResultCount パラメーターは、スケジュールされたジョブの ExecutionHistoryLength プロパティの値を設定します。

現在の実行履歴とジョブの結果を削除するには、Set-ScheduledJob コマンドレットの ClearExecutionHistory パラメーターを使用します。

型:	Int32
配置:	Named
規定値:	32
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Name

スケジュールされたジョブの名前を指定します。 この名前は、スケジュールされたジョブの開始されたすべてのインスタンスにも使用されます。 名前は、コンピューター上で一意である必要があります。 このパラメーターは必須です。

型:	String
配置:	0
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-RunAs32

スケジュールされたジョブを 32 ビット プロセスで実行します。

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-RunEvery

ジョブを実行する頻度を指定するために使用します。 たとえば、15 分ごとにジョブを実行するには、このオプションを使用します。

型:	TimeSpan
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-RunNow

Register-ScheduledJob コマンドレットが実行されるとすぐにジョブを開始します。 このパラメーターにより、登録直後に Windows PowerShell スクリプトを実行するためにタスク スケジューラをトリガーする必要がなくなります。また、開始日時を指定するトリガーをユーザーが作成する必要はありません。

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ScheduledJobOption

スケジュールされたジョブのオプションを設定します。 ScheduledJobOptions オブジェクト (New-ScheduledJobOption コマンドレットを使用して作成するもの、ハッシュ テーブル値など) を入力します。

スケジュール ジョブを登録するとき、または Set-ScheduledJobOption または Set-ScheduledJob コマンドレットを使用してオプションを変更するときに、スケジュールされたジョブのオプションを設定できます。

さまざまなオプションとその既定値により、スケジュールされたジョブが実行されるかどうかとそのタイミングが決まります。 ジョブをスケジュールする前に、必ずこれらのオプションを確認してください。 スケジュールされたジョブ オプションの説明 (既定値を含む) については、 New-ScheduledJobOptionを参照してください。

ハッシュ テーブルを渡すには、次のキーを使用します。 次のハッシュ テーブルには、キーとその既定値が示されています。

@{StartIfOnBattery=$False; StopIfGoingOnBattery=$True; WakeToRun=$False; StartIfNotIdle=$False; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$True; RestartOnIdleResume=$False; ShowInTaskScheduler=$True; RunElevated=$False; RunWithoutNetwork=$False; DoNotAllowDemandStart=$False; MultipleInstancePolicy="IgnoreNew"}

型:	ScheduledJobOptions
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ScriptBlock

スケジュールされたジョブで実行するコマンドを指定します。 コマンドを中かっこ ({}) で囲み、スクリプト ブロックを作成します。 コマンド パラメーターの既定値を指定するには、 ArgumentList パラメーターを使用します。

すべての Register-ScheduledJob コマンドでは、 ScriptBlock または FilePath パラメーターを使用する必要があります。

型:	ScriptBlock
配置:	1
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Trigger

スケジュールされたジョブのトリガーを指定します。 New-JobTrigger コマンドレットから返されるオブジェクトなどの 1 つ以上のScheduledJobTrigger オブジェクト、またはジョブ トリガーのキーと値のハッシュ テーブルを入力します。

ジョブ トリガーによってスケジュール ジョブが開始されます。 トリガーでは、1 回だけ、定期的なスケジュール、またはイベント (ユーザーがログオンしたときや Windows が起動したときなど) を指定できます。

Trigger パラメーターは省略可能です。 スケジュールされたジョブの作成時、 Add-JobTrigger、 Set-JobTrigger、または Set-ScheduledJob コマンドレットを使用して後でジョブ トリガーを追加または変更するときにトリガーを追加したり、 Start-Job コマンドレットを使用してスケジュールされたジョブをすぐに開始したりできます。 また、テンプレートとして使用するために、トリガーのないスケジュールされたジョブを作成し、管理することもできます。

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

• Frequency: Daily、Weekly、AtStartup、AtLogon
• At: 任意の有効な時刻文字列
• DaysOfWeek - 曜日名の任意の組み合わせ
• 間隔 - 任意の有効な頻度間隔
• RandomDelay: 任意の有効な期間文字列
• ユーザー: 任意の有効なユーザー。 AtLogon の頻度値でのみ使用されます

次に例を示します。

@{Frequency="Once"; At="3am"; DaysOfWeek="Monday", "Wednesday"; Interval=2; RandomDelay="30minutes"; User="Domain1\User01"}

型:	ScheduledJobTrigger[]
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-WhatIf

コマンドレットの実行時に発生する内容を示します。 コマンドレットは実行されません。

型:	SwitchParameter
Aliases:	wi
配置:	Named
規定値:	False
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

ScheduledJobDefinition

このコマンドレットは、登録済みジョブを表す ScheduledJobDefinition オブジェクトを返します。

メモ

スケジュールされた各ジョブは、ローカル コンピューター上の $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs ディレクトリのサブディレクトリに保存されます。 サブディレクトリには、スケジュールされたジョブの名前が付けられ、スケジュールされたジョブの XML ファイルとその実行履歴のレコードが含まれます。 ディスク上のスケジュールされたジョブの詳細については、「 about_Scheduled_Jobs_Advanced」を参照してください。

Windows PowerShell で作成したスケジュールされたジョブは、タスク スケジューラ Library\Microsoft\Windows\PowerShell\ScheduledJobs フォルダーのタスク スケジューラに表示されます。 タスク スケジューラを使用して、スケジュールされたジョブを表示および編集できます。

タスク スケジューラ、 schtasks.exe コマンド ライン ツール、タスク スケジューラ コマンドレットを使用して、スケジュールされたジョブ コマンドレットを使用して作成するスケジュールされたジョブを管理できます。 ただし、スケジュールされたジョブ コマンドレットを使用して、タスク スケジューラで作成したタスクを管理することはできません。

スケジュールされたジョブ コマンドが失敗した場合は、エラー メッセージが返されます。 ただし、タスク スケジューラがジョブを実行しようとしたときにジョブが失敗した場合、Windows PowerShell ではエラーを使用できません。

スケジュールされたジョブが実行されない場合は、次のメソッドを使用して理由を見つけます。

• ジョブ トリガーが正しく設定されていることを確認します。
  • ジョブ・オプションで設定された条件が満たされていることを確認します。
• ジョブを実行するユーザー アカウントに、ジョブ内のコマンドまたはスクリプトを実行するアクセス許可があることを確認します。
• タスク スケジューラの履歴でエラーを確認します。
• タスク スケジューラのイベント ログでエラーを確認します。

詳細については、「 about_Scheduled_Jobs_Troubleshooting」を参照してください。

関連リンク

• Add-JobTrigger
• Disable-JobTrigger
• Disable-ScheduledJob
• Enable-JobTrigger
• Enable-ScheduledJob
• Get-JobTrigger
• Get-ScheduledJob
• Get-ScheduledJobOption
• New-JobTrigger
• New-ScheduledJobOption
• Register-ScheduledJob
• Remove-JobTrigger
• Set-JobTrigger
• Set-ScheduledJob
• Set-ScheduledJobOption
• Unregister-ScheduledJob