PowerShell Cmdlet - New-PSSession記事記号：[mg1931] 初版：2011/Sep/30
この文書は、Windows PowerShellのヘルプ機能で表示される内容を再構成したものです。
名前
New-PSSession
概要
ローカル コンピューターまたはリモート コンピューターへの固定接続を作成します。
構文
New-PSSession [[-ComputerName] <string[]>] [-ApplicationName <string>] [-Aut
hentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential |
Credssp | Digest | Kerberos}] [-CertificateThumbprint <string>] [-Configurat
ionName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-Port <in
t>] [-SessionOption <PSSessionOption>] [-UseSSL] [-ThrottleLimit <int>] [<Co
mmonParameters>]
New-PSSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit
<int>] [<CommonParameters>]
New-PSSession [-ConnectionURI] <Uri[]> [-AllowRedirection] [-Authentication
{Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | D
igest | Kerberos}] [-CertificateThumbprint <string>] [-ConfigurationName <st
ring>] [-Credential <PSCredential>] [-Name <string[]>] [-SessionOption <PSSe
ssionOption>] [-ThrottleLimit <int>] [<CommonParameters>]
説明
New-PSSession コマンドレットは、ローカル コンピューターまたはリモート コンピ
ューター上に Windows PowerShell セッション (PSSession) を作成します。PSSessi
on を作成すると、Windows PowerShell はリモート コンピューターに対する固定接
続を確立します。
PSSession を使用して、関数や変数の値などのデータを共有する複数のコマンドを実
行できます。PSSession でコマンドを実行するには、Invoke-Command コマンドレッ
トを使用します。PSSession を使用してリモート コンピューターと直接対話するには、
Enter-PSSession コマンドレットを使用します。詳細については、「about_PSSession
s」を参照してください。
Enter-PSSession または Invoke-Command の ComputerName パラメーターを使用する
ことによって、PSSession を作成せずに、リモート コンピューター上でコマンドを実
行できます。ComputerName パラメーターを使用すると、Windows PowerShell は、対
話型のセッションや単一のコマンドに使用した後で閉じられる一時接続を作成します。
パラメーター
-AllowRedirection [<SwitchParameter>]
この接続を代替 URI (Uniform Resource Identifier) にリダイレクトできます。
ConnectionURI パラメーターを使用すると、リモートの配信先は別の URI にリ
ダイレクトするための命令を返すことができます。既定では、Windows PowerShe
ll は接続をリダイレクトしませんが、ユーザーは AllowRedirection パラメー
ターを使用して接続のリダイレクトを許可できます。
また、$PSSessionOption preference 変数の MaximumConnectionRedirectionCou
nt property プロパティ、または SessionOption パラメーターの値の MaximumC
onnectionRedirectionCount プロパティを設定することにより、接続をリダイレ
クトする回数を制限することもできます。既定値は 5 です。詳細については、S
essionOption パラメーターの説明と、New-PSSessionOption を参照してくださ
い。
必須 false
位置 named
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-ApplicationName <string>
接続 URI のアプリケーション名セグメントを指定します。ConnectionURI パラ
メーターをコマンド内で使用しない場合は、このパラメーターを使用してアプリ
ケーション名を指定します。
既定値は、ローカル コンピューターの $PSSessionApplicationName ユーザー設
定変数の値です。この設定変数を定義しない場合、既定値は WSMAN になります。
この値はほとんどのユーザーに適しています。詳細については、「about_Prefer
ence_Variables」を参照してください。
WinRM サービスは、アプリケーション名を使用して接続要求を処理するリスナー
を選択します。このパラメーターの値は、リモート コンピューターにあるリス
ナーの URLPrefix プロパティの値と一致する必要があります。
必須 false
位置 named
既定値 WSMAN
パイプライン入力を許可する true (ByPropertyName)
ワイルドカード文字を許可する false
-Authentication <AuthenticationMechanism>
ユーザーの資格情報の認証に使用するメカニズムを指定します。有効な値は、"D
efault"、"Basic"、"Credssp"、"Digest"、"Kerberos"、"Negotiate"、および "
NegotiateWithImplicitCredential" です。既定値は "Default" です。
CredSSP 認証は、Windows Vista、Windows Server 2008、およびそれ以降のバー
ジョンの Windows でのみ使用できます。
このパラメーターの値の詳細については、MSDN (Microsoft Developer Network)
ライブラリの System.Management.Automation.Runspaces.AuthenticationMechan
ism 列挙体の説明 (http://go.microsoft.com/fwlink/?LinkID=144382) を参照
してください。
注意: ユーザーの資格情報が認証対象のリモート コンピューターに渡される、
資格情報のセキュリティ サービス プロバイダー (CredSSP) 認証は、リモート
ネットワーク共有にアクセスする場合など、複数のリソースの認証を必要とする
コマンドを対象としています。このメカニズムを使用すると、リモート操作のセ
キュリティ リスクが高まります。リモート コンピューターのセキュリティが低
下している場合は、そのリモート コンピューターに渡される資格情報を使用し
てネットワーク セッションを制御できます。
必須 false
位置 named
既定値 Default
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-CertificateThumbprint <string>
この処理を実行するアクセス許可を持つユーザー アカウントのデジタル公開キ
ー証明書 (X509) を指定します。証明書の拇印を入力します。
証明書は、クライアント証明書ベースの認証で使用されます。これらはローカル
ユーザー アカウントにのみマッピングできます。ドメイン アカウントでは機能
しません。
証明書の拇印を取得するには、Windows PowerShell Cert: ドライブで Get-Item
または Get-ChildItem コマンドを使用します。
必須 false
位置 named
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-ComputerName <string[]>
指定されたコンピューターへの固定接続 (PSSession) を作成します。複数のコ
ンピューター名を入力した場合、New-PSSession によって各コンピューターに
1 つずつ複数の PSSession が作成されます。既定値はローカル コンピュータ
ーです。
1 つまたは複数のリモート コンピューターの NetBIOS 名、IP アドレス、また
は完全修飾ドメイン名を入力します。ローカル コンピューターを指定するには、
コンピューター名、「localhost」、またはドット (.) を入力します。コンピュ
ーターがユーザーとは異なるドメインにある場合、完全修飾ドメイン名が必要で
す。New-PSSession に対して (引用符で囲まれた) コンピューター名をパイプ処
理することもできます。
ComputerName パラメーターの値に IP アドレスを使用するには、コマンドに Cr
edential パラメーターを含める必要があります。また、コンピューターが HTTP
S トランスポート用に構成されているか、リモート コンピューターの IP アド
レスがローカル コンピューター上の WinRM TrustedHosts リストに含まれてい
る必要があります。コンピューター名を TrustedHosts リストに追加する方法に
ついては、「about_Remote_Troubleshooting」の「How to Add a Computer to t
he Trusted Host List (コンピューターを信頼されたホストの一覧に追加する方
法)」を参照してください。
注: Windows Vista 以降のバージョンの Windows で、ローカル コンピューター
を ComputerName パラメーターの値に含めるには、Windows PowerShell を起動
する際に [管理者として実行] を指定する必要があります。
必須 false
位置 1
既定値
パイプライン入力を許可する true (ByValue, ByPropertyName)
ワイルドカード文字を許可する false
-ConfigurationName <string>
新しい PSSession に使用するセッション構成を指定します。
構成名またはセッション構成の完全修飾リソース URI (Uniform Resource Ident
ifier) を入力します。構成名のみを指定すると、スキーマ URI "http://schema
s.microsoft.com/powershell" が先頭に付加されます。
セッションのセッション構成は、リモート コンピューター上にあります。指定
したセッション構成がリモート コンピューター上に存在しない場合、コマンド
は失敗します。
既定値は、ローカル コンピューターの $PSSessionConfigurationName ユーザー
設定変数の値です。この設定変数を設定しない場合、既定値は Microsoft.Power
Shell になります。詳細については、「about_Preference_Variables」を参照し
てください。
必須 false
位置 named
既定値
パイプライン入力を許可する true (ByPropertyName)
ワイルドカード文字を許可する false
-ConnectionURI <Uri[]>
接続エンドポイントを定義する URI (Uniform Resource Identifier) を指定し
ます。URI は完全修飾名でなければなりません。
この文字列の形式は次のとおりです。
<Transport>://<ComputerName>:<Port>/<ApplicationName>
既定値は次のとおりです。
http://localhost:80/WSMAN
URI のトランスポート セグメントの有効な値は HTTP および HTTPS です。Conn
ectionURI を指定しない場合、UseSSL、ComputerName、Port、および Applicati
onName パラメーターを使用して URI 値を指定できます。
対象のコンピューターが接続を別の URI にリダイレクトする場合、コマンドで
AllowRedirection パラメーターを使用しない限り、Windows PowerShell によっ
てリダイレクトが防止されます。
必須 true
位置 1
既定値
パイプライン入力を許可する true (ByPropertyName)
ワイルドカード文字を許可する false
-Credential <PSCredential>
この処理を実行するアクセス許可を持つユーザー アカウントを指定します。既
定値は現在のユーザーです。
"User01"、"Domain01\User01"、"User@Domain.com" のようなユーザー名を入力
するか、Get-Credential コマンドレットで返されるような PSCredential オブ
ジェクトを入力します。
ユーザー名を入力すると、パスワードの入力を促すメッセージが表示されます。
必須 false
位置 named
既定値
パイプライン入力を許可する true (ByPropertyName)
ワイルドカード文字を許可する false
-Name <string[]>
PSSession のフレンドリ名を指定します。
Get-PSSession や Enter-PSSession などの他のコマンドレットを使用する際に
は、この名前を使用して PSSession を参照できます。この名前は、コンピュー
ターまたは現在のセッションで一意である必要はありません。
必須 false
位置 named
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-Port <int>
このコマンドで使用するリモート コンピューター上のネットワーク ポートを
指定します。既定値はポート 80 (HTTP ポート) です。
代替ポートを使用する前に、リモート コンピューター上でそのポートをリッス
ンするための WinRM リスナーを構成する必要があります。リスナーを構成する
には、次のコマンドを使用します。
1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port=&q
uot;<port-number>"}
必要がない限り、Port パラメーターを使用しないでください。コマンドに設定
されたポート設定は、すべてのコンピューターおよびコマンドが実行されるセッ
ションに適用されます。代替ポート設定によって、すべてのコンピューターでの
コマンドの実行が妨げられている可能性があります。
必須 false
位置 named
既定値 80
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-Session <PSSession[]>
指定された PSSession を新しい PSSession のモデルとして使用します。このパ
ラメーターによって、指定された PSSession と同じプロパティを持つ新しい PS
Session が作成されます。
PSSessions を格納する変数を入力するか、New-PSSession コマンドや Get-PSSe
ssion コマンドなど、PSSessions を作成または取得するコマンドを入力します。
結果の PSSession は、元のセッションと同じコンピューター名、アプリケーシ
ョン名、接続 URI、ポート、構成名、スロットル制限および SSL (Secure Socke
ts Layer) 値を保持していますが、表示名、ID、およびインスタンス ID (GUID)
は異なります。
必須 false
位置 1
既定値
パイプライン入力を許可する true (ByValue, ByPropertyName)
ワイルドカード文字を許可する false
-SessionOption <PSSessionOption>
セッションの詳細オプションを設定します。New-PSSessionOption コマンドレッ
トを使用して作成する SessionOption オブジェクトを入力します。
$PSSessionOption 設定変数の値が設定されている場合、オプションの既定値は
この値によって決まります。それ以外の場合、セッションではシステムの既定値
が使用されます。
既定値を含め、セッション オプションの詳細については、New-PSSessionOption
を参照してください。$PSSessionOption 設定変数の詳細については、「about_P
reference_Variables」を参照してください。
必須 false
位置 named
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-ThrottleLimit <int>
このコマンドを実行するために確立できる最大同時接続数を指定します。このパ
ラメーターを省略した場合、または値 0 (ゼロ) を入力した場合は、既定値の 3
2 が使用されます。
スロットル制限は現在のコマンドのみに適用され、セッションまたはコンピュー
ターには適用されません。
必須 false
位置 named
既定値 32
パイプライン入力を許可する false
ワイルドカード文字を許可する false
-UseSSL [<SwitchParameter>]
Secure Sockets Layer (SSL) プロトコルを使用してリモート コンピューターと
の接続を確立します。既定では、SSL は使用されません。
WS-Management では、ネットワーク上で送信されるすべての Windows PowerShel
l コンテンツが暗号化されます。UseSSL は、HTTP 接続ではなく HTTPS 接続を
使用してデータを送信する追加の保護機能です。
このパラメーターを使用するが、コマンドに使用されるポートで SSL が利用で
きない場合、コマンドは失敗します。
必須 false
位置 named
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する false
<CommonParameters>
このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
OutBuffer、および OutVariable。詳細については、
「get-help about_commonparameters」と入力してヘルプを参照してください。
入力
System.String、System.URI、System.Management.Automation.Runspaces.PSSession
パイプを使用して ComputerName (文字列)、ConnectionURI (URI)、またはセッ
ション (PSSession) オブジェクトを New-PSSession に渡すことができます。
出力
System.Management.Automation.Runspaces.PSSession
メモ
このコマンドレットは、Windows PowerShell リモート処理インフラストラクチ
ャを使用します。このコマンドレットを使用するには、ローカル コンピュータ
ーおよび任意のリモート コンピューターが Windows PowerShell リモート処理
用に構成されている必要があります。詳細については、「about_Remote_Require
ments」を参照してください。
Windows Vista 以降のバージョンの Windows で、ローカル コンピューター上に
PSSession を作成するには、Windows PowerShell を起動する際に [管理者とし
て実行] を指定する必要があります。
PSSession を終了する際には、Remove-PSSession コマンドレットを使用して、P
SSession を削除し、そのリソースを解放します。
-------------------------- 例 1 --------------------------
C:\PS>$s = new-pssession
説明
-----------
このコマンドは、ローカル コンピューター上に新しい PSSession を作成し、その P
SSession を $s 変数に保存します。
これで、この PSSession を使用して、ローカル コンピューターでコマンドを実行で
きるようになります。
-------------------------- 例 2 --------------------------
C:\PS>$Server01 = new-pssession -ComputerName Server01
説明
-----------
このコマンドは、Server01 コンピューター上に新しい PSSession を作成し、その P
SSession を $Server01 変数に保存します。
複数の PSSession を作成する際には、これらのセッションを、有用な名前を持つ変
数に割り当てます。これは、後続のコマンドで PSSession を管理するのに役立ちま
す。
-------------------------- 例 3 --------------------------
C:\PS>$s1, $s2, $s3 = new-session -computername server1,server2,server3
説明
-----------
このコマンドは、3 つの新しい PSSession を作成します。セッションは、ComputerN
ame パラメーターによって指定された各コンピューターに 1 つずつ作成されます。
また、代入演算子 (=) を使用して、新しい PSSession を変数の配列 $s1、$s2、$s3
に割り当てます。Server01 の PSSession は $s1 に、Server02 の PSSession は $s
2 に、Server03 の PSSession は $s3 に割り当てられます。
複数のオブジェクトを変数の配列に割り当てた場合、Windows PowerShell は各オブ
ジェクトを配列のそれぞれの変数に割り当てます。オブジェクトの数が変数の数より
も多い場合、残りのすべてのオブジェクトは最後の変数に割り当てられます。変数の
数がオブジェクトの数よりも多い場合には、残りの変数は空 (Null) になります。
-------------------------- 例 4 --------------------------
C:\PS>new-pssession -computername Server01 -port 8081 -useSSL -Configuration
Name E12
説明
-----------
このコマンドは、サーバー ポート 8081 に接続して SSL プロトコルを使用する Ser
ver01 コンピューター上に新しい PSSession を作成します。新しい PSSession は、
"E12" という代替セッション構成を使用します。
ポートを設定する前に、リモート コンピューター上でポート 8081 をリッスンする
ための WinRM リスナーを構成する必要があります。詳細については、Port パラメー
ターの説明を参照してください。
-------------------------- 例 5 --------------------------
C:\PS>new-pssession -session $s -credential domain01\user01
説明
-----------
このコマンドによって、既存の PSSession と同じプロパティを持つ新しい PSSessio
n が作成されます。このコマンド形式は、既存の PSSession のリソースを使い果た
したためにリソース消費の一部をオフロードするための新しい PSSession が必要な
場合に使用できます。
このコマンドは、New-PSSession の Session パラメーターを使用して、$s 変数に保
存されている PSSession を指定します。また、Domain1\Admin01 ユーザーの資格情
報を使用して、コマンドを完了します。
-------------------------- 例 6 --------------------------
C:\PS>$global:s = new-pssession -computername server1.domain44.corpnet.fabri
kam.com -credential domain01\admin01
説明
-----------
この例は、異なるドメインのコンピューター上に、グローバル スコープを使用して
PSSession を作成する方法を示しています。
既定では、コマンド ラインで作成された PSSession はローカル スコープを使用し
て作成され、スクリプトで作成された PSSession にはスクリプト スコープが使用さ
れます。
グローバル スコープを使用して PSSession を作成するには、新しい PSSession を
作成し、その PSSession をグローバル スコープにキャストされる変数に保存します。
この場合、$s 変数はグローバル スコープにキャストされます。
このコマンドは、ComputerName パラメーターを使用してリモート コンピューターを
指定します。コンピューターがユーザー アカウントとは異なるドメインにあるため、
コンピューターの完全な名前がユーザーの資格情報と共に指定されています。
-------------------------- 例 7 --------------------------
C:\PS>$rs = get-content c:\test\servers.txt | new-PSsession -throttleLimit 5
0
説明
-----------
このコマンドは、Servers.txt ファイルに示されている 200 台の各コンピューターで
PSSession を作成し、結果の PSSession を $rs 変数に保存します。PSSession のス
ロットル制限は 50 です。
このコマンド形式は、コンピューター名がデータベース、スプレッドシート、テキスト
ファイル、またはテキストに変換可能な他の形式で保存されている場合に使用できます。
-------------------------- 例 8 --------------------------
C:\PS>$s = new-PSSession -URI http://Server01:91/NewSession -credential doma
in01\user01
説明
-----------
このコマンドは、Server01 コンピューター上に PSSession を作成し、その PSSessi
on を $s 変数に保存します。URI パラメーターを使用して、トランスポート プロト
コル、リモート コンピューター、ポート、および代替セッション構成を指定します。
また、Credential パラメーターを使用して、リモート コンピューターでセッション
を作成する権限を持つユーザー アカウントを指定します。
-------------------------- 例 9 --------------------------
C:\PS>$s = new-PSSession -computername (import-csv servers.csv) -credential
domain01\admin01 -throttlelimit 16
C:\PS> invoke-command -session $s -scriptblock {get-process powershell} -AsJ
ob
説明
-----------
これらのコマンドは、一連の PSSession を作成して、各 PSSession でバックグラウ
ンド ジョブを実行します。
最初のコマンドは、Servers.csv ファイルに示されている各コンピューターで、新し
い PSSession を作成します。また、New-PSSession コマンドレットを使用して PSSe
ssion を作成します。ComputerName パラメーターの値は、Import-Csv コマンドレッ
トを使用して Servers.csv ファイルをインポートし、その内容を読み込むコマンド
です。
このコマンドは、Credential パラメーターを使用してドメイン管理者の権限を持つ
PSSession を作成し、ThrottleLimit パラメーターを使用してコマンドの同時接続数
を 16 に制限します。このコマンドは PSSession を $s 変数に保存します。
2 番目のコマンドは、Invoke-Command の AsJob パラメーターを使用して、$s の各
PSSession で "Get-Process PowerShell" コマンドを実行するバックグラウンド ジ
ョブを開始します。
バックグラウンド ジョブの詳細については、「about_Jobs」と「about_Remote_Jobs
」を参照してください。
-------------------------- 例 10 --------------------------
C:\PS>new-PSSession -ConnectionURI https://management.exchangelabs.com/Manag
ement
説明
-----------
このコマンドは、コンピューター名ではなく URI で指定されたコンピューターに接
続する新しい PSSession を作成します。
-------------------------- 例 11 --------------------------
C:\PS>$so = New-WSManSessionOption -SkipCACheck
PS C:\> new-pssession -ConnectionUri https://management.exchangelabs.com/Mana
gement -SessionOption $so -credential server01\admin01
説明
-----------
この例は、SessionOption パラメーターの作成方法と使用方法を示しています。
最初のコマンドは、New-WSManSessionOption コマンドレットを使用してセッションの
オプションを作成します。このコマンドは、結果の SessionOption オブジェクトを $
so パラメーターに保存します。
2 番目のコマンドは、新しいセッションでそのオプションを使用します。このコマン
ドは、New-PSSession コマンドレットを使用して新しいセッションを作成します。Ses
sionOption パラメーターの値は、$so 変数の SessionOption オブジェクトです。
関連するリンク
Online version: http://go.microsoft.com/fwlink/?LinkID=135237
about_PSSessions
about_Remote
Get-PSSession
Remove-PSSession
Enter-PSSession
Exit-PSSession
Invoke-Command
記事で解説しているパソコンの環境基本ソフト： Windows 7
キーワード： Windows PowerShell、ヘルプ、Cmdlet、New-PSSession