Suspend-Job
ワークフロー ジョブを一時的に停止します。
構文
Suspend-Job
[-Force]
[-Wait]
[-Id] <Int32[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]Suspend-Job
[-Job] <Job[]>
[-Force]
[-Wait]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Suspend-Job
[-Force]
[-Wait]
[-Filter] <Hashtable>
[-WhatIf]
[-Confirm]
[<CommonParameters>]Suspend-Job
[-Force]
[-Wait]
[-State] <JobState>
[-WhatIf]
[-Confirm]
[<CommonParameters>]Suspend-Job
[-Force]
[-Wait]
[-InstanceId] <Guid[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]Suspend-Job
[-Force]
[-Wait]
[-Name] <String[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]説明
Suspend-Job コマンドレットは、ワークフロー ジョブを中断します。 中断とは、ワークフロー ジョブを一時的に中断または一時停止することを意味します。 ワークフローを実行しているユーザーは、このコマンドレットを使用してワークフローを中断できます。 これは、ワークフローを中断するワークフロー内のコマンドである Suspend-Workflowhttps://go.microsoft.com/fwlink/?LinkId=267141 アクティビティを補完します。
Suspend-Job コマンドレットは、ワークフロー ジョブでのみ機能します。 Start-Job コマンドレットを使用して開始されるバックグラウンド ジョブなど、標準のバックグラウンド ジョブでは機能しません。
ワークフロー ジョブを識別するには、ジョブの PSJobTypeName プロパティで PSWorkflowJob の値を検索します。 特定のカスタム ジョブの種類で Suspend-Job コマンドレットがサポートされているかどうかを確認する方法については、カスタムのジョブの種類のヘルプ トピックを参照してください。
ワークフロー ジョブを中断すると、ワークフロー ジョブは次のチェックポイントまで実行された後で中断されます。その後、ワークフロー ジョブ オブジェクトが直ちに返されます。 ジョブを取得する前に中断が完了するまで待機するには、Suspend-Job の Wait パラメーターまたは Wait-Job コマンドレットを使用します。 ワークフロー ジョブが中断されると、ジョブの State プロパティの値は Suspended になります。
正しく中断できるかどうかはチェックポイントに依存します。 現在のジョブの状態、メタデータ、出力はチェックポイントに保存されるため、状態やデータを失うことなくワークフロー ジョブを再開できます。 ワークフロー ジョブにチェックポイントがない場合は、正しく中断できません。 実行中のワークフローにチェックポイントを追加するには、PSPersist ワークフロー共通パラメーターを使用します。 Force パラメーターを使用すると、ワークフロー ジョブを直ちに中断し、チェックポイントがないワークフロー ジョブを中断できますが、アクションによって状態とデータが失われる可能性があります。
ワークフロー ジョブ (PSWorkflowJob) などのカスタム ジョブの種類で Job コマンドレットを使用する前に、Import-Module コマンドレットを使用するか、モジュールで コマンドレットを使用するか、またはコマンドレットを使用して、カスタム ジョブの種類をサポートするモジュールをインポートします。
このコマンドレットは、Windows PowerShell 3.0 で導入されました。
例
例 1: 名前でワークフロー ジョブを中断する
The first command creates the Get-SystemLog workflow. The workflow uses the CheckPoint-Workflow activity to define a checkpoint in the workflow.
#Sample WorkflowWorkflow Get-SystemLog
{
$Events = Get-WinEvent -LogName System
CheckPoint-Workflow
InlineScript {\\Server01\Scripts\Analyze-SystemEvents.ps1 -Events $Events}
}
The second command uses the *AsJob* parameter that is common to all workflows to run the Get-SystemLog workflow as a background job. The command uses the *JobName* workflow common parameter to specify a friendly name for the workflow job.
PS C:\> Get-SystemLog -AsJob -JobName "Get-SystemLogJob"
The third command uses the **Get-Job** cmdlet to get the Get-SystemLogJob workflow job. The output shows that the value of the **PSJobTypeName** property is PSWorkflowJob.
PS C:\> Get-Job -Name Get-SystemLogJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 Get-SystemLogJob PSWorkflowJob Running True localhost Get-SystemLog
The fourth command uses the **Suspend-Job** cmdlet to suspend the Get-SystemLogJob job. The job runs to the checkpoint and then suspends.
PS C:\> Suspend-Job -Name Get-SystemLogJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 Get-SystemLogJob PSWorkflowJob Suspended True localhost Get-SystemLogこの例では、ワークフロー ジョブを中断する方法を示します。
例 2: ワークフロー ジョブの中断と再開
The first command suspends the LogWorkflowJob job.The command returns immediately. The output shows that the workflow job is still running, even though it is being suspended.
PS C:\> Suspend-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflow
The second command uses the **Get-Job** cmdlet to get the LogWorkflowJob job. The output shows that the workflow job suspended successfully.
PS C:\> Get-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Suspended True localhost LogWorkflow
The third command uses the **Get-Job** cmdlet to get the LogWorkflowJob job and the Resume-Job cmdlet to resume it. The output shows that the workflow job resumed successfully and is now running.
PS C:\> Get-Job -Name LogWorkflowJob | Resume-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflowこの例では、ワークフロー ジョブを中断し、再開する方法を示します。
例 3: リモート コンピューターでワークフロー ジョブを中断する
PS C:\> Invoke-Command -ComputerName Srv01 -Scriptblock {Suspend-Job -Filter @{CustomID="031589"}このコマンドは、Invoke-Command コマンドレットを使用して、Srv01 リモート コンピューター上のワークフロー ジョブを中断します。 Filter パラメーターの値は、CustomID 値を指定するハッシュ テーブルです。 この CustomID は、ジョブのメタデータ (PSPrivateMetadata) です。
例 4: ワークフロー ジョブが中断されるまで待つ
PS C:\> Suspend-Job VersionCheck -Wait
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
5 VersionCheck PSWorkflowJob Suspended True localhost LogWorkflowこのコマンドは、VersionCheck ワークフロー ジョブを中断します。 このコマンドでは、Wait パラメーターを使用して、ワークフロー ジョブが中断されるのを待機しています。 ワークフロー ジョブが次のチェックポイントに実行され、中断されると、コマンドはジョブ オブジェクトを終了して返します。
例 5: ワークフロー ジョブを強制的に中断する
PS C:\> Suspend-Job Maintenance -Forceこのコマンドは、強制的に Maintenance ワークフロー ジョブを中断します。 メンテナンス ジョブにはチェックポイントがありません。 正しく中断できず、正しく再開されない可能性があります。
パラメーター
-Confirm
コマンドレットの実行前に確認を求めるメッセージが表示されます。
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Filter
条件のハッシュ テーブルを指定します。 このコマンドレットは、すべての条件を満たすジョブを中断します。 ジョブのプロパティをキー、ジョブのプロパティ値を値とするハッシュ テーブルを入力します。
| Type: | Hashtable |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Force
ワークフロー ジョブを即座に中断します。 このアクションにより、状態とデータが失われる可能性があります。
既定では、Suspend-Job は、ワークフロー ジョブを次のチェックポイントまで実行した後で中断します。 このパラメーターを使用すると、チェックポイントがないワークフロー ジョブも中断できます。
| Type: | SwitchParameter |
| Aliases: | F |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Id
このコマンドレットが中断するジョブの ID を指定します。
ID は、現在のセッションのジョブを一意に識別する整数です。 インスタンス ID よりも覚えて入力する方が簡単ですが、現在のセッションでのみ一意です。 1 つ以上の ID をコンマで区切って入力できます。 ジョブの ID を検索するには、Get-Job コマンドレットを使用します。
| Type: | Int32[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-InstanceId
このコマンドレットが中断するジョブのインスタンス ID を指定します。 既定値はすべてのジョブです。
インスタンス ID は、コンピューター上のジョブを一意に識別する GUID です。 ジョブのインスタンス ID を調べるには、Get-Job を使用します。
| Type: | Guid[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Job
このコマンドレットが停止するワークフロー ジョブを指定します。 ワークフロー ジョブが格納されている変数、またはワークフロー ジョブを取得するコマンドを入力します。 パイプを使用してワークフロー ジョブを Suspend-Job コマンドレットに渡すこともできます。
| Type: | Job[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
このコマンドレットが中断するジョブのフレンドリ名を指定します。 1 つまたは複数のワークフロー ジョブ名を入力します。 ワイルドカード文字がサポートされています。
| Type: | String[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-State
ジョブの状態を指定します。 このコマンドレットは、指定された状態のジョブのみを停止します。 このパラメーターの有効値は、次のとおりです。
- NotStarted
- 実行中
- 完了
- 失敗
- 停止済み
- Blocked
- Suspended
- [Disconnected](切断済み)
- 中断中
- 停止中
Suspend-Job は、 実行中 状態のワークフロー ジョブのみを中断します。
ジョブの状態の詳細については、MSDN ライブラリの JobState 列挙 に関するページを参照してください。
| Type: | JobState |
| Accepted values: | NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping, AtBreakpoint |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Wait
このコマンドレットは、ワークフロー ジョブが中断状態になるまでコマンド プロンプトを抑制することを示します。 既定では、ワークフロー ジョブがまだ中断状態でない場合でも、 Suspend-Job は直ちに戻ります。
Wait パラメーターは、Suspend-Job コマンドを Wait-Job コマンドレットにパイプするのと同じです。
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
コマンドレットの実行時に発生する内容を示します。 このコマンドレットは実行されません。
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
入力
すべての種類のジョブをこのコマンドレットにパイプできます。 ただし、 Suspend-Job が サポートされていない型のジョブを取得すると、終了エラーが返されます。
出力
このコマンドレットは、中断したジョブを返します。
メモ
中断されているジョブを保存するメカニズムと保存先の場所は、ジョブの種類によって異なる可能性があります。 たとえば、中断されているワークフロー ジョブは、既定でフラット ファイル ストアに保存されますが、データベースに保存することもできます。
Running 状態にないワークフロー ジョブを送信すると、Suspend-Job は警告メッセージを表示します。 警告を抑制するには、 WarningAction 共通パラメーターを SilentlyContinue の値と共に使用します。
ジョブが中断をサポートする型ではない場合、 Suspend-Job は終了エラーを返します。
中断されたワークフロー ジョブ (このコマンドレットによって中断されたものも含む) を見つけるには、Get-Job コマンドレットの State パラメーターを使用して、Suspended 状態のワークフロー ジョブを取得します。
一部のジョブの種類には、Windows PowerShell によるジョブの中断が許可されないオプションまたはプロパティを持つもあります。 ジョブの中断が失敗した場合は、ジョブのオプションとプロパティで中断が許可されていることを確認します。