Share via

about_WorkflowCommonParameters

  • [アーティクル]

概要

このトピックでは、すべての 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 を使用 します。

-JobName <文字列>

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

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

Windows PowerShell バックグラウンド ジョブの詳細については、「about_Jobs」を参照してください。

-PSAllowRedirection <SwitchParameter>

ターゲット コンピューターへの接続のリダイレクトを許可します。

PSConnectionURI パラメーターを使用すると、リモート宛先は別の URI にリダイレクトする命令を返すことができます。 既定では、Windows PowerShell は接続を リダイレクトしませんが、PSAllowRedirection パラメーターを使用して、ターゲット コンピューターへの接続のリダイレクトを許可できます。

また、基本設定変数の MaximumConnectionRedirectionCount プロパティ、または PSSessionOption パラメーターの値の $PSSessionOption MaximumConnectionRedirectionCount プロパティを設定して、接続がリダイレクトされる回数を制限することもできます。 既定値は 5 です。 詳細については、PSSessionOption パラメーターと New-PSSessionOption の説明を参照してください。

-PSApplicationName <String>

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

既定値は、ローカル コンピューターの $PSSessionApplicationName 基本設定変数の値です。 この基本設定変数が定義されていない場合、既定値は WSMAN. この値はほとんどの用途に適しています。 詳細については、「about_Preference_Variables」を参照してください。

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

-PSAuthentication <AuthenticationMechanism>

ターゲット コンピューターに接続するときにユーザーの資格情報を認証するために使用されるメカニズムを指定します。

有効な値は次の通りです。

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

既定値は Default です。

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

警告

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

-PSAuthenticationLevel <AuthenticationLevel>

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

有効な値は次の通りです。

名前 説明
Unchanged 認証レベルは、前のコマンドと同じです。
Default Windows 認証
None COM 認証なし。
Connect 接続レベルの COM 認証。
Call 呼び出しレベルの COM 認証。
Packet パケット レベルの COM 認証。
PacketIntegrity パケット整合性レベルの COM 認証。
PacketPrivacy パケット プライバシー レベルの COM 認証。

-PSCertificateThumbprint <String>

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

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

証明書を取得するには、Windows PowerShell Cert: ドライブで Get-Item コマンドレットまたは Get-ChildItem コマンドレットを使用します。

-PSComputerName <String[]>

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

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

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

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

ComputerName パラメーターの値に IP アドレスを使用するには、コマンドに PSCredential パラメーターを含める必要があります。 また、HTTPS トランスポート用にコンピューターを構成するか、リモート コンピューターの IP アドレスをローカル コンピューター上の WinRM TrustedHosts 一覧に含める必要があります。 TrustedHosts リストにコンピューター名を追加する手順については、about_Remote_Troubleshootingの「信頼できるホストの一覧にコンピューターを追加する方法」を参照してください。

-PSConfigurationName <文字列>

ターゲット コンピューターでセッションを構成するために使用するセッション構成を指定します。 (ワークフロー サーバー コンピューターではなく) ターゲット コンピューターでセッション構成を入力します。 既定値は Microsoft.PowerShell.Workflow です。

-PSConnectionRetryCount <UInt>

最初の接続試行が失敗した場合に、各ターゲット コンピューターへの接続試行の最大数を指定します。 1 ~ 4,294,967,295 (UInt.MaxValue) の数値を入力します。 既定値の 0 (0) は、再試行を行いません。

-PSConnectionRetryIntervalSec <UInt>

接続再試行の間隔を秒単位で指定します。 既定値は 0 (0) です。 このパラメーターは、PSConnectionRetryCount の値が少なくとも 11 つの場合にのみ有効です。

-PSConnectionURI <System.Uri>

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

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

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

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

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

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

-PSCredential <PSCredential>

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

ユーザー名を入力するか、User01または Domain01\User01PSCredential オブジェクトを含む変数 (コマンドレットから返されるオブジェクトなど) をGet-Credential入力します。 ユーザー名のみを入力すると、パスワードの入力を求められます。

-P Standard Edition lapsedTimeoutSec <UInt32>

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

-PSParameterCollection <Hashtable[]>

ターゲット コンピューターごとに異なるワークフロー共通パラメーター値を指定します。

ターゲット コンピューターごとに 1 つのハッシュ テーブルを持つハッシュ テーブルのコンマ区切りの一覧を入力します。 各ハッシュ テーブルでは、最初のキーは PSComputerName で、その値はターゲット コンピューターの名前です。 コンピューター名には、ワイルドカード文字を使用できます。 ハッシュ テーブル内の再メインキーの場合、キーはパラメーター名であり、値はパラメーター値です。

次に例を示します。

-PSParameterCollection @{PSComputerName="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}

上記の例では、すべての接続に既定の P Standard Edition lapsedTimeoutSec20 (秒) が設定されます。ただし、Server01 では、独自の10タイムアウト (秒) を指定して既定値がオーバーライドされます。

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

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

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

既定値を含むセッション オプションの説明については、New-PSSessionOption を参照してください。 基本設定変数の詳細$PSSessionOptionについては、about_Preference_Variablesを参照してください。

-PSUseSSL <SwitchParameter>

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

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

参照