フィードバック

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

ワークフロー ジョブのフレンドリ名を指定します。 既定では、ジョブの名前 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 列挙型の説明を参照してください。

警告

ユーザーの資格情報が認証対象のリモート コンピューターに渡される Credential Security Service Provider (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 <String>

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

-PSConnectionRetryCount <UInt>

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

-PSConnectionRetryIntervalSec <UInt>

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

-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\User01、コマンドレットから返 される PSCredential オブジェクトなどの PSCredential オブジェクトを含む変数を Get-Credential 入力します。 ユーザー名のみを入力すると、パスワードの入力を求められます。

-PSElapsedTimeoutSec <UInt32>

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

-PSParameterCollection <Hashtable[]>

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

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

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

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

上記の例では、すべての接続に既定の 20 PSElapsedTimeoutSec (秒) が設定されます。ただし、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 オブジェクトなど、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 が使用できない場合に、このパラメーターを指定すると、コマンドは失敗します。

参照