Test-Connection

  • リファレンス
モジュール:
Microsoft.PowerShell.Management

ICMP エコー要求パケット (ping) を 1 つ以上のコンピューターに送信します。

構文

Test-Connection
    [-TargetName] <string[]>
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Count <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -Repeat
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -Traceroute
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -MtuSize
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -TcpPort <int>
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-Count <int>]
    [-Delay <int>]
    [-Repeat]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [-Detailed]
    [<CommonParameters>]

説明

Test-Connection コマンドレットは、インターネット制御メッセージ プロトコル (ICMP) エコー要求パケット (ping) を 1 つ以上のリモート コンピューターに送信し、エコー応答応答を返します。 このコマンドレットを使用して、特定のコンピューターに IP ネットワーク経由で接続できるかどうかを判断できます。

Test-Connectionのパラメーターを使用して、送受信コンピューターの両方を指定したり、コマンドをバックグラウンド ジョブとして実行したり、タイムアウトと ping の数を設定したり、接続と認証を構成したりできます。

使い慣れた ping コマンドとは異なり、 Test-Connection は PowerShell で調査できる TestConnectionCommand+PingStatus オブジェクトを返します。 Quiet パラメーターは、テストされた各接続の System.Boolean オブジェクトの Boolean 値を返します。 複数の接続をテストすると、 Boolean 値の配列が返されます。

例

例 1: リモート コンピューターにエコー要求を送信する

この例では、ローカル コンピューターから Server01 コンピューターにエコー要求パケットを送信します。

Test-Connection -TargetName Server01 -IPv4

Destination: Server01

Ping Source           Address                   Latency BufferSize Status
                                                   (ms)        (B)
---- ------           -------                   ------- ---------- ------
   1 ADMIN1           10.59.137.44                   24         32 Success
   2 ADMIN1           10.59.137.44                   39         32 Success
   3 ADMIN1           *                               *          * TimedOut
   4 ADMIN1           10.59.137.44                   28         32 Success

Test-Connection は、 TargetName パラメーターを使用して Server01 コンピューターを指定します。 IPv4 パラメーターは、テストのプロトコルを指定します。

一連の TestConnectionCommand+ PingStatus オブジェクトが出力ストリームに送信され、ターゲット コンピューターからの ping 応答ごとに 1 つのオブジェクトが送信されます。

例 2: 複数のコンピューターにエコー要求を送信する

この例では、ローカル コンピューターから複数のリモート コンピューターに ping を送信します。

Test-Connection -TargetName Server01, Server02, Server12

例 3: パラメーターを使用してテスト コマンドをカスタマイズする

この例では、 Test-Connection のパラメーターを使用してコマンドをカスタマイズします。 ローカル コンピューターからリモート コンピューターに ping テストが送信されます。

Test-Connection -TargetName Server01 -Count 3 -Delay 2 -MaxHops 255 -BufferSize 256

Test-Connection は、 TargetName パラメーターを使用して Server01 を指定します。 Count パラメーターは、Delay 2 秒間隔で 3 つの ping を Server01 コンピューターに送信することを指定します。

これらのオプションは、ホップ数が長いか、トラフィックの多いネットワーク状態が原因で、ping 応答に通常よりも長い時間がかかると予想される場合に使用できます。

例 4: バックグラウンド ジョブとしてテストを実行する

この例では、powerShell バックグラウンド ジョブとして Test-Connection コマンドを実行する方法を示します。

$job = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path "Servers.txt") }
$Results = Receive-Job $job -Wait

Start-Job コマンドは、Test-Connection コマンドレットを使用して、企業内の多くのコンピューターに ping を実行します。 TargetName パラメーターの値は、Servers.txt ファイルからコンピューター名の一覧を読み取るGet-Content コマンドです。 このコマンドは、 Start-Job コマンドレットを使用してバックグラウンド ジョブとしてコマンドを実行し、ジョブを $job 変数に保存します。

Receive-Job コマンドは、ジョブが完了するまで-Waitするように指示され、結果を取得して$Results変数に格納します。

例 5: 接続テストが成功した場合にのみセッションを作成する

この例では、コンピューターに送信された ping の少なくとも 1 つが成功した場合にのみ、Server01 コンピューターにセッションを作成します。

if (Test-Connection -TargetName Server01 -Quiet) { New-PSSession -ComputerName Server01 }

Test-Connection コマンドレットは、Quiet パラメーターを指定して、Server01 コンピューターに ping を実行します。 結果の値は、4 つの ping のいずれかが成功した場合に $True されます。 ping が成功しなかった場合、値は $False。

Test-Connection コマンドが $True の値を返す場合、コマンドは New-PSSession コマンドレットを使用してPSSessionを作成します。

例 6: Traceroute パラメーターを使用する

PowerShell 6.0 で導入された Traceroute パラメーターは、ローカル コンピューターと、 TargetName パラメーターで指定したリモート接続先の間のルートをマップします。

Test-Connection -TargetName www.google.com -Traceroute

Target: google.com

Hop Hostname                  Ping Latency Status           Source       TargetAddress
                                      (ms)
--- --------                  ---- ------- ------           ------       -------------
  1 172.20.0.1                   1       4 Success          Lira         172.217.9.174
  1 172.20.0.1                   2       3 Success          Lira         172.217.9.174
  1 172.20.0.1                   3       2 Success          Lira         172.217.9.174
  2 12.108.153.193               1       3 Success          Lira         172.217.9.174
  2 12.108.153.193               2       3 Success          Lira         172.217.9.174
  2 12.108.153.193               3       2 Success          Lira         172.217.9.174
  3 12.244.85.177                1      11 Success          Lira         172.217.9.174
  3 12.244.85.177                2      12 Success          Lira         172.217.9.174
  3 12.244.85.177                3      12 Success          Lira         172.217.9.174
  4 *                            1      14 DestinationNetw… Lira         172.217.9.174
  4 *                            2       * TimedOut         Lira         172.217.9.174
  4 *                            3      20 DestinationNetw… Lira         172.217.9.174
  5 *                            1       * TimedOut         Lira         172.217.9.174
  5 *                            2      15 DestinationNetw… Lira         172.217.9.174
  5 *                            3       * TimedOut         Lira         172.217.9.174
  6 *                            1      18 DestinationNetw… Lira         172.217.9.174
  6 *                            2       * TimedOut         Lira         172.217.9.174
  6 *                            3      16 DestinationNetw… Lira         172.217.9.174
  7 *                            1       * TimedOut         Lira         172.217.9.174
  7 *                            2       * TimedOut         Lira         172.217.9.174
  7 *                            3       * TimedOut         Lira         172.217.9.174
  8 *                            1       * TimedOut         Lira         172.217.9.174
  8 *                            2       * TimedOut         Lira         172.217.9.174
  8 *                            3       * TimedOut         Lira         172.217.9.174
  9 *                            1       * TimedOut         Lira         172.217.9.174
  9 *                            2       * TimedOut         Lira         172.217.9.174
  9 *                            3       * TimedOut         Lira         172.217.9.174
 10 *                            1       * TimedOut         Lira         172.217.9.174
 10 *                            2       * TimedOut         Lira         172.217.9.174
 10 *                            3       * TimedOut         Lira         172.217.9.174
 11 172.217.9.174                1      23 Success          Lira         172.217.9.174
 11 172.217.9.174                2      21 Success          Lira         172.217.9.174
 11 172.217.9.174                3      22 Success          Lira         172.217.9.174

Test-Connection コマンドは、Traceroute パラメーターを使用して呼び出されます。 結果はオブジェクト [Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus] 、 Success 出力ストリームに出力されます。

例 7: TCP 接続テストの詳細な出力を取得する

Detailed パラメーターを使用すると、TCP 接続試行の状態に関する詳細情報が返されます。

Test-Connection bing.com -TCPPort 443 -Detailed -Count 4

Target: bing.com

Id Source     Address           Port Latency(ms) Connected Status
-- ------     -------           ---- ----------- --------- ------
 1 circumflex 2620:1ec:c11::200  443          12 True      Success
 2 circumflex 2620:1ec:c11::200  443          14 True      Success
 3 circumflex 2620:1ec:c11::200  443          17 True      Success
 4 circumflex 2620:1ec:c11::200  443          17 True      Success

パラメーター

-BufferSize

このコマンドで送信されるバッファーのサイズをバイト単位で指定します。 既定値は 32 です。

型:Int32
Aliases:Size, Bytes, BS
配置:Named
規定値:32
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Count

送信するエコー要求の数を指定します。 既定値は 4 ですが、

型:Int32
配置:Named
規定値:4
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Delay

ping 間の間隔を秒単位で指定します。

型:Int32
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Detailed

Detailed パラメーターを使用すると、TCP 接続試行の状態に関する詳細情報が返されます。

このパラメーターは PowerShell 7.4 で追加されました。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-DontFragment

このパラメーターは、IP ヘッダーの Don't Fragment フラグを設定します。 このパラメーターを BufferSize パラメーターと共に使用して、パス MTU サイズをテストできます。 パス MTU の詳細については、wikipedia の Path MTU Discovery 記事を参照してください。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-IPv4

テストに IPv4 プロトコルを使用するようにコマンドレットを強制します。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-IPv6

テストに IPv6 プロトコルを使用するようにコマンドレットを強制します。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MaxHops

ICMP 要求メッセージを送信できるホップの最大数を設定します。 既定値はオペレーティング システムによって制御されます。 Windows 10 以降の既定値は 128 ホップです。

型:Int32
Aliases:Ttl, TimeToLive, Hops
配置:Named
規定値:128
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-MtuSize

このパラメーターは、パス MTU サイズを検出するために使用されます。 このコマンドレットは、ターゲットへのパス MTU サイズを含む PingReply#MTUSize オブジェクトを返します。 パス MTU の詳細については、wikipedia の Path MTU Discovery 記事を参照してください。

型:SwitchParameter
Aliases:MtuSizeDetect
配置:Named
規定値:False
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Ping

コマンドレットで ping テストを実行します。 これは、 Test-Connection コマンドレットの既定のモードです。

型:SwitchParameter
配置:Named
規定値:True
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Quiet

Quiet パラメーターは、Boolean 値を返します。 このパラメーターを使用すると、すべてのエラーが抑制されます。

テストされた各接続は、 Boolean 値を返します。 TargetName パラメーターで複数のコンピューターを指定した場合は、Boolean 値の配列が返されます。

any特定のターゲットへの ping が成功すると、$Trueが返されます。

特定のターゲットへの ping が失敗した場合は、$Falseが返されます。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Repeat

コマンドレットが ping 要求を継続的に送信するようにします。 TargetName の値がターゲットの配列である場合、コマンドレットは最初のターゲットに対してのみ ping 要求を繰り返します。 残りのターゲットは無視されます。 このパラメーターは、 Count パラメーターでは使用できません。

型:SwitchParameter
Aliases:Continuous
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ResolveDestination

コマンドレットがターゲットの DNS 名の解決を試みます。 Traceroute パラメーターと組み合わせて使用すると、可能であれば、すべての中間ホストの DNS 名も取得されます。

型:SwitchParameter
配置:Named
規定値:False
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Source

ping の送信元コンピューターの名前を指定します。 コンピューター名のコンマ区切りのリストを入力します。 既定値はローカル コンピューターです。

Note

このパラメーターは、PowerShell バージョン 6 以降ではサポートされていません。 このパラメーターを指定すると、エラーが発生します。

型:String
配置:Named
規定値:Local computer
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-TargetName

テストするコンピューターを指定します。 コンピューター名を入力するか、IP アドレスを IPv4 または IPv6 形式で入力します。

型:String[]
Aliases:ComputerName
配置:0
規定値:None
必須:True
パイプライン入力を受け取る:True
ワイルドカード文字を受け取る:False

-TcpPort

TCP 接続テストで使用するターゲットの TCP ポート番号を指定します。

このコマンドレットは、ターゲット上の指定されたポートへの TCP 接続を試行します。

  • このコマンドレットは、接続が確立された場合に $True を返します。
  • 接続が確立されていない場合、コマンドレットは $False を返します。
型:Int32
配置:Named
規定値:None
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-TimeoutSeconds

テストのタイムアウト値を設定します。 タイムアウトの期限が切れる前に応答が受信されない場合、テストは失敗します。 既定値は 5 秒です。

このパラメーターは、PowerShell 6.0 で導入されました。

型:Int32
配置:Named
規定値:5 seconds
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Traceroute

コマンドレットで traceroute テストを実行します。 このパラメーターを使用すると、コマンドレットは TestConnectionCommand+TraceStatus オブジェクトを返します。

型:SwitchParameter
配置:Named
規定値:False
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

Microsoft.PowerShell.Commands.TestConnectionCommand+PingStatus

既定では、このコマンドレットは ping 応答ごとに TestConnectionCommand+ PingStatus オブジェクトを返します。

Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus

Traceroute パラメーターを使用すると、このコマンドレットはルートに沿った ping 応答ごとに TestConnectionCommand+TraceStatus オブジェクトを返します。

Boolean

Quiet または TcpPort パラメーターを使用すると、このコマンドレットは Boolean 値を返します。 コマンドレットが複数の接続をテストすると、 Boolean 値の配列が返されます。

Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus

MtuSize パラメーターを使用すると、このコマンドレットは ping 応答ごとに TestConnectionCommand+PingMtuStatus オブジェクトを返します。

Microsoft.PowerShell.Commands.TestConnectionCommand+TcpPortStatus

Detailed パラメーターを使用すると、このコマンドレットは TCP 接続の状態を示す TestConnectionCommand+TcpPortStatus オブジェクトを返します。

メモ

Linux では、 BufferSize パラメーターを使用するか、 MtuSizeDetect パラメーター セットを使用して既定以外のバッファー サイズが 32 バイトになるパラメーターの任意の組み合わせを使用するには、 sudoが必要な場合があります。 このような場合、 Test-Command は、 sudo が必要であることを示すメッセージを含む例外を発生させます。