about_WorkflowCommonParameters

  • [アーティクル]

適用対象: Windows PowerShell 3.0

トピック

about_Workflow_Common_Parameters

概要

このトピックでは、すべての Windows PowerShell® ワークフロー コマンドで有効なパラメーターについて説明します。これらのパラメーターは、Windows PowerShell エンジンによってワークフローに追加されるため、どのワークフローでも使用でき、作成したワークフローで自動的に有効になります。

詳細説明

Windows PowerShell ワークフロー共通パラメーターは、すべての Windows PowerShell ワークフローとアクティビティで使用できるコマンドレット パラメーターのセットです。ワークフローの作成者ではなく、Windows PowerShell ワークフロー エンジンによって追加されるため、すべてのワークフローおよびアクティビティで自動的に使用できるようになります。ただし、3 レベルまで深く入れ子になったワークフローでは、ワークフロー共通パラメーターを含め、どの共通パラメーターもサポートされません。

すべてのワークフロー パラメーターはオプションで、名前が付けられています (順不同)。パイプラインから入力を取得しません。

ワークフロー共通パラメーターのほとんどには、PSComputerName や PSCredential のように、プレフィックスとして PS が付きます。PS というプレフィックスが付いたパラメーターは、"リモート ノード" とも呼ばれる対象のコンピューターの接続および実行環境を構成します。

PSAllowRedirection や AsJob などワークフロー共通パラメーターの多くは、Windows PowerShell リモート処理とバックグラウンド ジョブで使用されるパラメーターとよく似た名前を持っています。これらのパラメーターはよく似た名前のリモート処理およびジョブ パラメーターと同じように機能するため、リモート処理とジョブで開発したナレッジを使用してワークフローを管理できます。

ワークフローは、Windows PowerShell 3.0 で導入されました。

パラメーターの説明

このセクションでは、ワークフロー共通パラメーターについて説明します。

AsJob <SwitchParameter>

ワークフロー ジョブとしてワークフローを実行します。ワークフロー コマンドは、親ジョブを表すオブジェクトを直ちに返します。親ジョブには、各対象のコンピューターで実行されている子ジョブが含まれています。ジョブを管理するには、Job コマンドレットを使用します。ジョブの結果を取得するには、Receive-Job コマンドレット (https://go.microsoft.com/fwlink/?LinkID=113372) を使用します。

JobName <String>

ワークフロー ジョブのフレンドリ名を指定します。既定では、ジョブの名前は "Job<n>" で、<n> は序数です。

ワークフロー コマンドに JobName パラメーターを使用すると、ワークフローはジョブとして実行されます。また、コマンド内に AsJob パラメーターを含めなくても、ワークフロー コマンドはジョブ オブジェクトを返します。

Windows PowerShell バックグラウンド ジョブの詳細については、「about_Jobs」(https://go.microsoft.com/fwlink/?LinkID=113251) を参照してください。

PSAllowRedirection <SwitchParameter>

対象のコンピューターに接続をリダイレクトできます。

PSConnectionURI パラメーターを使用すると、リモートの送信先は別の URI にリダイレクトするように指示を返すことができます。既定では、Windows PowerShell は接続をリダイレクトしませんが、PSAllowRedirection パラメーターを使用して対象のコンピューターに接続をリダイレクトできます。

$PSSessionOption ユーザー設定変数の MaximumConnectionRedirectionCount プロパティまたは PSSessionOption パラメーター値の MaximumConnectionRedirectionCount プロパティを設定して、接続をリダイレクトする回数を制限することもできます。既定値は 5 です。詳細については、PSSessionOption パラメーターと New-PSSessionOption コマンドレット (https://go.microsoft.com/fwlink/?LinkID=135237) の説明を参照してください。

PSApplicationName <String>

対象のコンピューターへの接続に使用される接続 URI のアプリケーション名セグメントを指定します。コマンドで ConnectionURI パラメーターを使用しない場合は、このパラメーターを使用してアプリケーション名を指定します。

既定値は、ローカル コンピューター上の $PSSessionApplicationName ユーザー設定変数の値です。このユーザー設定変数が定義されていない場合、既定値は WSMAN です。この値はほとんどの用途に適しています。詳細については、「about_Preference_Variables」(https://go.microsoft.com/fwlink/?LinkID=113248) を参照してください。

WinRM サービスは、アプリケーション名を使用して、接続要求を処理するリスナーを選択します。このパラメーターの値は、リモート コンピューター上のリスナーの URLPrefix プロパティの値に一致している必要があります。

PSAUTHENTICATION <AuthenticationMechanism>

対象のコンピューターへの接続時にユーザーの資格情報を認証するために使用するメカニズムを指定します。有効な値は、Default、Basic、Credssp、Digest、Kerberos、Negotiate、および NegotiateWithImplicitCredential です。既定値は Default です。

このパラメーターの値については、MSDN の System.Management.Automation.Runspaces.AuthenticationMechanism 列挙体の説明を参照してください。

注意:

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

PSAUTHENTICATIONLEVEL <AuthenticationLevel>

対象のコンピューターへの接続の認証レベルを指定します。既定値は Default です。

有効な値は次のとおりです。

Unchanged:

認証レベルは前のコマンドと同じです。

既定:

Windows 認証。

None:

COM 認証なし。

Connect:

接続レベルの COM 認証。

Call:

呼び出しレベルの COM 認証。

Packet:

パケット レベルの COM 認証。

PacketIntegrity:

パケット整合性レベルの COM 認証。

PacketPrivacy:

パケット プライバシー レベルの COM 認証。

PSCERTIFICATETHUMBPRINT <String>

この処理を実行するアクセス許可を持つユーザー アカウントのデジタル公開キー証明書 (X509) を指定します。証明書の拇印を入力します。

証明書は、クライアント証明書ベースの認証で使用されます。これらの証明書は、ローカル ユーザー アカウントにしかマップできません。ドメイン アカウントでは機能しません。

証明書を取得するには、Windows PowerShell Cert: ドライブで Get-Item (https://go.microsoft.com/fwlink/?LinkID=113319) コマンドレットまたは Get-ChildItem (https://go.microsoft.com/fwlink/?LinkID=113308) コマンドレットを使用します。

PSCOMPUTERNAME <String[]>

ワークフローの対象ノードであるコンピューターの一覧を指定します。ワークフロー内のコマンドまたはアクティビティは、このパラメーターを使用して指定されているコンピューターで実行されます。既定はローカル コンピューターです。

1 台または複数のコンピューターの NETBIOS 名、IP アドレス、または完全修飾ドメイン名をコンマ区切りリストで入力します。ローカルのコンピューターを指定するには、コンピューター名、「localhost」、またはドット (.) を入力します。

PSComputerName パラメーターの値にローカル コンピューターを指定するには、[管理者として実行] オプションを使用して Windows PowerShell を開きます。

このパラメーターがコマンドで省略されているか、またはその値が $null か空文字列である場合は、ワークフローのターゲットはローカル コンピューターとなり、コマンド実行に際して Windows PowerShell のリモート処理は使用されません。

IP アドレスを ComputerName パラメーターの値として使用するには、コマンドに PSCredential パラメーターを含める必要があります。また、HTTPS トランスポート用にコンピューターを構成するか、リモート コンピューターの IP アドレスをローカル コンピューター上の WinRM TrustedHosts 一覧に含める必要があります。TrustedHosts 一覧にコンピューター名を追加する手順については、「about_Remote_Troubleshooting」(https://go.microsoft.com/fwlink/?LinkID=135188) で、コンピューターを信頼されたホスト一覧に追加する方法に関するセクションを参照してください。

PSCONFIGURATIONNAME <String>

対象のコンピューター上のセッションの構成に使用されるセッション構成を指定します。対象のコンピューター (ワークフロー サーバー コンピューターではなく) でセッション構成を入力します。既定は、Microsoft.PowerShell.Workflow です。

PSCONNECTIONRETRYCOUNT <UInt>

それぞれの対象のコンピューターへの最初の接続試行が失敗した場合に、接続を試行する最大回数を指定します。1 から 4,294,967,295 (UInt.MaxValue) の範囲の数値を入力します。既定値はゼロ (0) で、再試行しないことを表します。

PSCONNECTIONRETRYINTERVALSEC <UInt>

接続再試行の待ち時間を秒単位で指定します。既定値はゼロ (0) です。このパラメーターは、PSConnectionRetryCount の値が 1 以上である場合にのみ有効です。

PSCONNECTIONURI <System.Uri>

対象のコンピューターのワークフローの接続エンドポイントを定義する Uniform Resource Identifier (URI) を指定します。URI は完全修飾名にする必要があります。

この文字列の形式は次のとおりです。

           <Transport>://<ComputerName>:<Port>/<ApplicationName>

既定値は、https://localhost:5985/WSMAN です。

PSConnectionURI を指定しない場合は、PSUseSSL、PSComputerName、PSPort、PSApplicationName の各パラメーターを使用して、PSConnectionURI 値を指定できます。

URI のトランスポート セグメントの有効な値は、HTTP および HTTPS です。トランスポート セグメントを使用して接続 URI だけを指定し、ポートは指定しない場合、セッションは標準ポート、つまり、HTTP の場合は 80、HTTPS の場合は 443 を使用して作成されます。Windows PowerShell リモート処理用の既定のポートを使用するには、HTTP の場合は 5985、HTTPS の場合は 5986 を指定します。

PSCREDENTIAL <PSCredential>

対象のコンピューターでワークフローを実行するアクセス許可を持つユーザー アカウントを指定します。既定値は現在のユーザーです。このパラメーターは、PSComputerName パラメーターがコマンドに含まれている場合にのみ有効です。

「User01」や「Domain01\User01」のようなユーザー名を入力するか、PSCredential オブジェクト (Get-Credential コマンドレットが返すオブジェクトなど) を含む変数を入力します。ユーザー名のみを入力すると、パスワードの入力を促すメッセージが表示されます。

PSELAPSEDTIMEOUTSEC <UInt32>

ワークフローと関連するすべてのリソースがシステムに保持される期間を決定します。タイムアウトが経過すると、ワークフローはまだ処理中であっても削除されます。10 から 4,294,967,295 の範囲の値を入力します。既定値は 0 (ゼロ) で、タイムアウトの経過がないことを意味します。

PSPARAMETERCOLLECTION <Hashtable[]>

別の対象のコンピューター用の別のワークフロー共通パラメーター値を指定します。

対象のコンピューターごとにハッシュ テーブルを 1 つ指定して、ハッシュ テーブルのコンマ区切りのリストを入力します。各ハッシュ テーブルでは、最初のキーは PSComputerName で、その値は対象のコンピューターの名前です。コンピューター名ではワイルドカード文字を使用できます。ハッシュ テーブルの残りのキーはパラメーター名で、その値はパラメーター値です。

たとえば、次のように入力します。

          -PSParameterCollection @{PSComputerName="Server01";
              PSElapsedTimeoutSec=10; PSConnectionRetryCount=6}, 
              @{PSComputerName="*"; PSElapsedTimeoutSec=20}

PSPERSIST <Boolean>

ワークフローで指定されているすべてのチェックポイントのほか、ワークフローにチェックポイントを追加します。

このパラメーターでは、PSPersist アクティビティ共通パラメーター、Checkpoint-Workflow アクティビティ、または $PSPersistPreference 変数を使用して指定されているチェックポイントなど、ワークフローのチェックポイントを抑制できません。

"チェックポイント" や "永続化ポイント" は、ワークフローの状態とワークフローの実行中に取得されるデータのスナップショットであり、ディスクまたは SQL データベースの永続化ストアに保存されます。Windows PowerShell ワークフローは、ワークフローを再起動するのではなく、保存されたデータを使用して、一時停止または中断されたワークフローを最後の永続化ポイントから再開します。

有効な値:

(既定)

このパラメーターを省略した場合は、ワークフローで指定されているチェックポイントのほか、ワークフローの先頭と末尾にもチェックポイントが追加されます。

$True

ワークフローで指定されているチェックポイントのほか、ワークフローの先頭と末尾、および各アクティビティの後にチェックポイントを追加します。

$False

チェックポイントは追加されません。ワークフローで指定されている場合にのみ、チェックポイントが作成されます。

PSPORT <Int32>

対象のコンピューターでネットワーク ポートを指定します。既定のポート番号は 5985 (HTTP 用の WinRM ポート) と 5986 (HTTPS 用の WinRM ポート) です。

必要な場合を除き、この PSPort パラメーターは使用しないでください。このコマンドで設定されたポートは、コマンドが実行されたすべてのコンピューターまたはセッションに適用されます。代替ポートの設定によっては、コマンドがすべてのコンピューターで実行されない場合があります。代替ポートを使用する前に、そのポートでリッスンするようにリモート コンピューター上の WinRM リスナーを構成する必要があります。

PSPRIVATEMETADATA <Hashtable>

カスタマイズされた情報をワークフロー ジョブに提供します。ハッシュ テーブルを入力します。キーと値は、ワークフローごとにカスタマイズします。ワークフローのプライベート メタデータについては、ワークフローのヘルプ トピックを参照してください。

このパラメーターは、Windows PowerShell ワークフロー エンジンによって処理されません。代わりに、エンジンはワークフローに直接ハッシュ テーブルを渡します。

PSRUNNINGTIMEOUTSEC <UInt32>

ワークフローの中断時間を除いて、ワークフローの実行時間を秒単位で指定します。この時間が経過したときにワークフローの実行が完了していない場合、Windows PowerShell ワークフロー エンジンはワークフローの実行を強制的に停止します。

PSSESSIONOPTION <PSSessionOption>

対象のコンピューターに、セッションの詳細オプションを設定します。New-PSSessionOption コマンドレットを使用して作成するオブジェクトなどの、PSSessionOption オブジェクトを入力します。

セッション オプションの既定値は、$PSSessionOption ユーザー設定変数が設定されている場合は、その値によって決まります。それ以外の場合、セッションではセッション構成で指定された値が使用されます。

既定の値を含む、セッション オプションの説明については、New-PSSessionOption コマンドレットのヘルプ トピック (https://go.microsoft.com/fwlink/?LinkID=144305) を参照してください。$PSSessionOption ユーザー設定変数の詳細については、「about_Preference_Variables」(https://go.microsoft.com/fwlink/?LinkID=113248) を参照してください。

PSUSESSL <SwitchParameter>

Secure Sockets Layer (SSL) プロトコルを使用して対象のコンピューターとの接続を確立します。既定では、SSL は使用されません。

WS-Management は、ネットワークを介して転送されるすべての Windows PowerShell コンテンツを暗号化します。UseSSL は、HTTP 経由ではなく HTTPS 経由でデータを送信するために追加された保護機能です。コマンドに使用するポートで SSL が使用できない場合に、このパラメーターを指定すると、コマンドは失敗します。

キーワード

about_Workflow_Common_Parameters

about_Workflow_CommonParameters

関連項目

about_ActivityCommonParameters

about_Workflows

Invoke-AsWorkflow

New-PSWorkflowExecutionOption

New-PSWorkflowSession