次の方法で共有

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 パラメーターを使用して、ターゲット コンピューターへの接続のリダイレクトを許可できます。

$PSSessionOption設定変数の MaximumConnectionRedirectionCount プロパティ、または 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 パラメーターの値にローカル コンピューターを含めるには、Run as administrator オプションを指定して 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 を指定したが、ポートを指定しない場合、セッションは標準ポート (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="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}

上記の例では、すべての接続の既定の PSElapsedTimeoutSec 20 秒になります。ただし、Server01 では、独自のタイムアウトを 10 秒に指定して既定値をオーバーライドします。

-PSPersist <Boolean>

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

このパラメーターは、PSPersist、activity common パラメーター、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を参照してください。 $PSSessionOption基本設定変数の詳細については、about_Preference_Variablesを参照してください。

-PSUseSSL <SwitchParameter>

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

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

参照