Suspend-Job
ワークフロー ジョブを一時的に停止します。
構文
Suspend-Job
[-Force]
[-Wait]
[-Id] <Int32[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Suspend-Job
[-Job] <Job[]>
[-Force]
[-Wait]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Suspend-Job
[-Force]
[-Wait]
[-Name] <String[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Suspend-Job
[-Force]
[-Wait]
[-InstanceId] <Guid[]>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Suspend-Job
[-Force]
[-Wait]
[-Filter] <Hashtable>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Suspend-Job
[-Force]
[-Wait]
[-State] <JobState>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
説明
Suspend-Job
コマンドレットは、ワークフロー ジョブを中断します。 中断とは、ワークフロー ジョブを一時的に中断または一時停止することを意味します。 このコマンドレットを使用すると、ワークフローを実行しているユーザーはワークフローを中断できます。 これは、ワークフローを中断するワークフロー内のコマンドである Suspend-Workflowhttps://go.microsoft.com/fwlink/?LinkId=267141 アクティビティを補完します。
Suspend-Job
コマンドレットはワークフロー ジョブでのみ機能します。
Start-Job
コマンドレットを使用して開始されるジョブなど、標準のバックグラウンド ジョブでは機能しません。
ワークフロー ジョブを識別するには、ジョブの PSJobTypeName プロパティで PSWorkflowJob の値を探します。 特定のカスタム ジョブの種類が Suspend-Job
コマンドレットをサポートしているかどうかを確認するには、カスタム ジョブの種類のヘルプ トピックを参照してください。
ワークフロー ジョブを中断すると、ワークフロー ジョブは次のチェックポイントまで実行され、中断され、ワークフロー ジョブ オブジェクトが直ちに返されます。 ジョブを取得する前に中断が完了するのを待つには、 または Suspend-Job
コマンドレットの Wait-Job
パラメーターを使用します。 ワークフロー ジョブが中断されると、ジョブの State プロパティの値が Suspended になります。
一時停止はチェックポイントに依存します。 現在のジョブの状態、メタデータ、および出力はチェックポイントに保存されるため、状態やデータを失うことなくワークフロー ジョブを再開できます。 ワークフロー ジョブにチェックポイントがない場合は、正しく中断できません。 実行中のワークフローにチェックポイントを追加するには、PSPersist ワークフロー共通パラメーターを使用します。 Force パラメーターを使用すると、ワークフロー ジョブを直ちに中断したり、チェックポイントがないワークフロー ジョブを中断したりできますが、アクションによって状態とデータが失われる可能性があります。
ワークフロー ジョブ (PSWorkflowJob) などのカスタム ジョブの種類で Job コマンドレットを使用する前に、Import-Module
コマンドレットを使用するか、モジュールのコマンドレットを使用して、カスタム ジョブの種類をサポートするモジュールをインポートします。
このコマンドレットは、Windows PowerShell 3.0 で導入されました。
例
例 1: 名前でワークフロー ジョブを中断する
この例では、ワークフロー ジョブを中断する方法を示します。
最初のコマンドは、Get-SystemLog
ワークフローを作成します。 ワークフローは、CheckPoint-Workflow
アクティビティを使用して、ワークフロー内のチェックポイントを定義します。
2 番目のコマンドでは、すべてのワークフローに共通する AsJob パラメーターを使用して、Get-SystemLog
ワークフローをバックグラウンド ジョブとして実行します。 このコマンドでは、JobName ワークフロー共通パラメーターを使用して、ワークフロー ジョブのフレンドリ名を指定します。
3 番目のコマンドでは、Get-Job
コマンドレットを使用して、LogflowJob
ワークフロー ジョブを取得します。 出力は、PSJobTypeName プロパティの値が PSWorkflowJob であることを示しています。
4 番目のコマンドでは、Suspend-Job
コマンドレットを使用して、LogflowJob
ジョブを中断します。 ジョブはチェックポイントに対して実行され、中断されます。
#Sample Workflow
workflow Get-SystemLog
{
$Events = Get-WinEvent -LogName System
CheckPoint-Workflow
inlinescript {\\Server01\Scripts\Analyze-SystemEvents.ps1 -Events $Events}
}
Get-SystemLog -AsJob -JobName "LogflowJob"
Get-Job -Name LogflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 LogflowJob PSWorkflowJob Running True localhost Get-SystemLog
Suspend-Job -Name LogflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 LogflowJob PSWorkflowJob Suspended True localhost Get-SystemLog
例 2: ワークフロー ジョブを中断して再開する
この例では、ワークフロー ジョブを中断および再開する方法を示します。
最初のコマンドは、LogWorkflowJob ジョブを中断します。コマンドはすぐに返されます。 出力は、ワークフロー ジョブが中断されているにもかかわらず、まだ実行中であることを示しています。
2 番目のコマンドでは、Get-Job
コマンドレットを使用して LogWorkflowJob ジョブを取得します。 出力は、ワークフロー ジョブが正常に中断されたことを示しています。
3 番目のコマンドでは、Get-Job
コマンドレットを使用して LogWorkflowJob ジョブを取得し、Resume-Job
コマンドレットを使用して再開します。 出力は、ワークフロー ジョブが正常に再開され、現在実行されていることを示しています。
Suspend-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflow
Get-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Suspended True localhost LogWorkflow
Get-Job -Name LogWorkflowJob | Resume-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflow
例 3: リモート コンピューターでワークフロー ジョブを中断する
Invoke-Command -ComputerName Srv01 -ScriptBlock {Suspend-Job -Filter @{CustomID="031589"}
このコマンドは、Invoke-Command
コマンドレットを使用して、Srv01 リモート コンピューター上のワークフロー ジョブを中断します。
Filter パラメーターの値は、CustomID 値を指定するハッシュ テーブルです。
この CustomID はジョブ メタデータ (PSPrivateMetadata) です。
例 4: ワークフロー ジョブが一時停止するのを待つ
Suspend-Job VersionCheck -Wait
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
5 VersionCheck PSWorkflowJob Suspended True localhost LogWorkflow
このコマンドは、VersionCheck ワークフロー ジョブを中断します。 このコマンドは、Wait パラメーターを使用して、ワークフロー ジョブが中断されるまで待機します。 ワークフロー ジョブが次のチェックポイントに実行され、中断されると、コマンドは終了し、ジョブ オブジェクトを返します。
例 5: ワークフロー ジョブを強制的に中断する
Suspend-Job Maintenance -Force
このコマンドは、メンテナンス ワークフロー ジョブを強制的に中断します。 メンテナンス ジョブにはチェックポイントがありません。 正しく中断できず、正常に再開されない可能性があります。
パラメーター
-Confirm
コマンドレットを実行する前に確認を求めるメッセージが表示されます。
型: | SwitchParameter |
Aliases: | cf |
配置: | Named |
規定値: | False |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Filter
条件のハッシュ テーブルを指定します。 このコマンドレットは、すべての条件を満たすジョブを中断します。 キーがジョブ プロパティで、値がジョブ プロパティ値であるハッシュ テーブルを入力します。
型: | Hashtable |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-Force
ワークフロー ジョブを直ちに中断します。 このアクションにより、状態とデータが失われる可能性があります。
既定では、Suspend-Job
ワークフロー ジョブは次のチェックポイントまで実行され、中断されます。
このパラメーターを使用して、チェックポイントのないワークフロー ジョブを中断することもできます。
型: | SwitchParameter |
Aliases: | F |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Id
このコマンドレットが中断するジョブの ID を指定します。
ID は、現在のセッションのジョブを一意に識別する整数です。 インスタンス ID よりも覚えて入力する方が簡単ですが、現在のセッションでのみ一意です。 1 つ以上の ID をコンマで区切って入力できます。 ジョブの ID を検索するには、Get-Job
コマンドレットを使用します。
型: | Int32[] |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-InstanceId
このコマンドレットが中断するジョブのインスタンス ID を指定します。 既定値は、すべてのジョブです。
インスタンス ID は、コンピューター上のジョブを一意に識別する GUID です。 ジョブのインスタンス ID を検索するには、Get-Job
を使用します。
型: | Guid[] |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-Job
このコマンドレットが停止するワークフロー ジョブを指定します。 ワークフロー ジョブを含む変数、またはワークフロー ジョブを取得するコマンドを入力します。 ワークフロー ジョブを Suspend-Job
コマンドレットにパイプすることもできます。
型: | Job[] |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-Name
このコマンドレットが中断するジョブのフレンドリ名を指定します。 1 つ以上のワークフロー ジョブ名を入力します。 ワイルドカード文字がサポートされています。
型: | String[] |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-State
ジョブの状態を指定します。 このコマンドレットは、指定された状態のジョブのみを停止します。 このパラメーターに使用できる値は次のとおりです。
- NotStarted
- ランニング
- 完了
- 失敗 しました
- 停止
- ブロック
- 中断
- 途切れ途切れ
- 中断
- 停車
Suspend-Job
は、実行中 状態のワークフロー ジョブのみを中断します。
ジョブの状態の詳細については、「JobState 列挙 を参照してください。
型: | JobState |
指定可能な値: | NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping, AtBreakpoint |
配置: | 0 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-Wait
このコマンドレットは、ワークフロー ジョブが中断状態になるまでコマンド プロンプトを抑制することを示します。 既定では、ワークフロー ジョブがまだ中断状態でない場合でも、Suspend-Job
はすぐに返されます。
Wait パラメーターは、Suspend-Job
コマンドを Wait-Job
コマンドレットにパイプ処理することと同じです。
型: | SwitchParameter |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-WhatIf
コマンドレットを実行した場合の動作を示します。 コマンドレットは実行されません。
型: | SwitchParameter |
Aliases: | wi |
配置: | Named |
規定値: | False |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
入力
このコマンドレットには、すべての種類のジョブをパイプ処理できます。 ただし、Suspend-Job
がサポートされていない型のジョブを取得すると、終了エラーが返されます。
出力
このコマンドレットは、中断したジョブを返します。
メモ
Windows PowerShell には、Suspend-Job
の次のエイリアスが含まれています。
sujb
中断されたジョブを保存するメカニズムと場所は、ジョブの種類によって異なる場合があります。 たとえば、中断されたワークフロー ジョブは、既定ではフラット ファイル ストアに保存されますが、データベースに保存することもできます。
実行中の状態ではないワークフロー ジョブを送信すると、警告メッセージ Suspend-Job
表示されます。 警告を抑制するには、WarningAction 共通パラメーターを使用し、値を SilentlyContinue に設定します。
ジョブが中断をサポートする型でない場合、Suspend-Job
は終了エラーを返します。
中断されたワークフロー ジョブ (このコマンドレットによって中断されたものも含む) を検索するには、 コマンドレットの Get-Job
パラメーターを使用して、中断状態のワークフロー ジョブを取得します。
一部のジョブの種類には、Windows PowerShell によるジョブの中断を妨げるオプションまたはプロパティがあります。 ジョブの中断が失敗した場合は、ジョブのオプションとプロパティで中断が許可されていることを確認します。