Invoke-WebRequest

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

インターネット上の Web ページからコンテンツを取得します。

構文

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [<CommonParameters>]

説明

このコマンドレットは Invoke-WebRequest 、HTTP、HTTPS、FTP、および FILE 要求を Web ページまたは Web サービスに送信します。 さらに、応答を解析し、フォーム、リンク、画像、およびその他の重要な HTML 要素のコレクションを返します。

このコマンドレットは、Windows PowerShell 3.0 で導入されました。

Note

既定では、Web ページ内のスクリプト コードは、プロパティを設定 ParsedHtml するためにページが解析されるときに実行される場合があります。 スイッチを -UseBasicParsing 使用してこれを抑制します。

重要

この記事の例では、doメイン のホストをcontoso.com参照しています。 これは架空の操作でありメイン例として Microsoft によって使用されます。 これらの例は、コマンドレットの使用方法を示すために設計されています。 ただし、サイトは contoso.com 存在しないため、例は機能しません。 環境内のホストに例を適用します。

例

例 1: Web 要求を送信する

この例では、コマンドレットを Invoke-WebRequest 使用して、Bing.com サイトに Web 要求を送信します。

$Response = Invoke-WebRequest -UseBasicParsing -URI https://www.bing.com?q=how+many+feet+in+a+mile
$Response.InputFields |
    Where-Object name -like "* Value" |
    Select-Object name, value

name       value
----       -----
From Value 1
To Value   5280

返される Invoke-WebRequest データは変数に $Response 格納されます。 応答の InputFields プロパティには、フォーム フィールドが含まれています。 Where-Objectは、name プロパティが "* Value" のようなフィールドにフォーム フィールドをフィルター処理するために使用されます。 フィルター処理された結果はパイプ処理されSelect-Object、名前と値のプロパティが選択されます。

例 2: ステートフル Web サービスを使用する

この例では、Facebook などのステートフル Web サービスでコマンドレットを使用 Invoke-WebRequest する方法を示します。

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

最初のコマンドでは、コマンドレットを Invoke-WebRequest 使用してサインイン要求を送信します。 このコマンドは、SessionVariable パラメーターの値に "FB" の値を指定し、結果を変数に$R保存します。 コマンドが完了すると、変数には HtmlWebResponseObject が含まれており、$FB変数には WebRequestSession オブジェクトが含まれます。$R

コマンドレットが Invoke-WebRequest facebook にサインインした後、変数の Web 応答オブジェクト$Rの StatusDescription プロパティは、ユーザーが正常にサインインしたことを示します。

例 3: Web ページからリンクを取得する

このコマンドは、Web ページ内のリンクを取得します。

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

このコマンドレットは Invoke-WebRequest 、Web ページのコンテンツを取得します。 次に、返された HtmlWebResponseObject の Links プロパティを使用して、各リンクの Href プロパティを表示します。

例 4: Invoke-WebRequest から成功以外のメッセージをキャッチする

成功しない HTTP メッセージ (404、500 など) が発生すると Invoke-WebRequest 、出力は返されません。終了エラーがスローされます。 エラーをキャッチして StatusCode を表示するには、実行をブロックでtry/catch囲むことができます。

try
{
    $Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
}
catch
{
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

終了エラーは、例外オブジェクトから StatusCode を取得するブロックによってcatchキャッチされます。

例 8: 複数のファイルを同時にダウンロードする

コマンドレットは Invoke-WebRequest 一度に 1 つのファイルのみをダウンロードできます。 次の例では、 Start-ThreadJob 複数のファイルを同時にダウンロードする複数のスレッド ジョブを作成します。

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

Note

コマンドレットをStart-ThreadJob使用するには、PowerShell ギャラリーから ThreadJob モジュールをインストールする必要があります。

パラメーター

-Body

要求の本文を指定します。 本文は、ヘッダーに続く要求の内容です。 本文の値 Invoke-WebRequestをパイプでパイプすることもできます。

Body パラメーターを使用して、クエリ パラメーターの一覧を指定したり、応答の内容を指定したりできます。

入力が GET 要求で、本文が IDictionary (通常はハッシュ テーブル) の場合、本文はクエリ パラメーターとして URI に追加されます。 その他の要求の種類 (POST など) の場合、本文は標準 name=value 形式の要求本文の値として設定されます。

本文がフォームの場合、または呼び出しの Invoke-WebRequest 出力である場合、PowerShell は要求の内容をフォーム フィールドに設定します。 次に例を示します。

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

  • または -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

Type:Object
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Certificate

セキュリティで保護された Web 要求に使用されるクライアント証明書を指定します。 証明書が格納されている変数を入力するか、証明書を取得するコマンドまたは式を入力します。

証明書を検索するには、証明書 (Cert:) ドライブでコマンドレットを使用Get-PfxCertificateするか、コマンドレットを使用Get-ChildItemします。 証明書が有効でない場合、または十分な権限を持っていない場合、コマンドは失敗します。

Type:X509Certificate
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

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

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

証明書の拇印を表示するには、またはGet-ChildItemコマンドをGet-Item使用して証明書Cert:\CurrentUser\Myを検索します。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ContentType

Web 要求のコンテンツ タイプを指定します。

このパラメーターを省略し、要求メソッドが POST の場合は、 Invoke-WebRequest コンテンツ タイプ application/x-www-form-urlencodedを . それ以外の場合、コンテンツ タイプは呼び出しで指定されません。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

要求を送信するアクセス許可を持つユーザー アカウントを指定します。 既定値は現在のユーザーです。

User01 や Doメイン01\User01 などのユーザー名を入力するか、コマンドレットによって生成された PSCredential オブジェクトをGet-Credential入力します。

資格情報は PSCredential オブジェクトに格納され、パスワードは SecureString として格納されます。

Note

SecureString データ保護の詳細については、「SecureString のセキュリティ保護方法」を参照してください。

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisableKeepAlive

コマンドレットが HTTP ヘッダーの KeepAlive 値を False に設定することを示します。 既定では、 KeepAlive は True です。 KeepAlive は、後続の要求を容易にするために、サーバーへの永続的な接続を確立します。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Headers

Web 要求のヘッダーを指定します。 ハッシュ テーブルまたは辞書を入力します。

UserAgent ヘッダーを設定するには、UserAgent パラメーターを使用します。 このパラメーターを使用して UserAgent ヘッダーまたは Cookie ヘッダーを指定することはできません。

Type:IDictionary
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InFile

ファイルから Web 要求の内容を取得します。

パスとファイル名を入力します。 パスを省略した場合、既定値は現在のディレクトリです。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

接続が失敗するまでに、PowerShell が代替 Uniform Resource Identifier (URI) に接続をリダイレクトする回数を指定します。 既定値は 5 です。 値 0 (ゼロ) を指定した場合、リダイレクトはまったく行われません。

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Method

Web 要求に使用するメソッドを指定します。 このパラメーターの有効値は、次のとおりです。

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace
Type:WebRequestMethod
Accepted values:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutFile

このコマンドレットが応答本文を保存する出力ファイルを指定します。 パスとファイル名を入力します。 パスを省略した場合、既定値は現在のディレクトリです。

既定では、 Invoke-WebRequest 結果をパイプラインに返します。 結果をファイルとパイプラインに送信するには、Passthru パラメーターを使用します。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

ファイルに書き込むだけでなく、コマンドレットによって結果が返されることを示します。 このパラメーターは、OutFile パラメーターがコマンドでも使用されている場合にのみ有効です。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Proxy

インターネット リソースに直接接続するのではなく、要求のプロキシ サーバーを指定します。 ネットワーク プロキシ サーバーの URI を入力します。

Type:Uri
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Proxy パラメーターで指定されたプロキシ サーバーを使用するアクセス許可を持つユーザー アカウントを指定します。 既定値は現在のユーザーです。

ユーザー名を入力するか、User01またはDomain01\User01、コマンドレットによってGet-Credential生成された PSCredential オブジェクトを入力します。

このパラメーターは、Proxy パラメーターがコマンドでも使用されている場合にのみ有効です。 同じコマンドで ProxyCredential パラメーターと ProxyUseDefaultCredentials パラメーターを使用することはできません。

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyUseDefaultCredentials

コマンドレットが現在のユーザーの資格情報を使用して、Proxy パラメーターで指定されたプロキシ サーバーにアクセスすることを示します。

このパラメーターは、Proxy パラメーターがコマンドでも使用されている場合にのみ有効です。 同じコマンドで ProxyCredential パラメーターと ProxyUseDefaultCredentials パラメーターを使用することはできません。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

このコマンドレットが Web 要求セッションを作成し、値に保存する変数を指定します。 ドル記号 ($) 記号を使用せずに変数名を入力します。

セッション変数を指定する場合は、 Invoke-WebRequest Web 要求セッション オブジェクトを作成し、PowerShell セッションで指定した名前の変数に割り当てます。 コマンドが完了すると、すぐに変数をセッションで使用できます。

リモート セッションとは異なり、Web 要求セッションは永続的な接続ではありません。 これは、Cookie、資格情報、最大リダイレクト値、ユーザー エージェント文字列など、接続と要求に関する情報を含むオブジェクトです。 Web 要求セッションを使用して、Web 要求の間で状態とデータを共有することができます。

後続の Web 要求で Web 要求セッションを使用するには、WebSession パラメーターの値にセッション変数を指定します。 PowerShell では、新しい接続を確立するときに、Web 要求セッション オブジェクトのデータが使用されます。 Web 要求セッションの値をオーバーライドするには、UserAgent や Credential などのコマンドレット パラメーターを使用します。 パラメーターの値は、Web 要求セッションの値よりも優先されます。

同じコマンドで SessionVariable パラメーターと WebSession パラメーターを使用することはできません。

Type:String
Aliases:SV
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSec

タイムアウトするまでの要求の保留期間を指定します。値を秒単位で入力します。 既定値は 0 で、無制限のタイムアウトを意味しています。

Doメイン Name System (DNS) クエリの戻りまたはタイムアウトには最大 15 秒かかることがあります。解決が必要なホスト名が要求に含まれており、TimeoutSec を 0 より大きい値に設定したが 15 秒未満の場合、WebException がスローされるまでに 15 秒以上かかる場合があり、要求はタイムアウトします。

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TransferEncoding

転送エンコード HTTP 応答ヘッダーの値を指定します。 このパラメーターの有効値は、次のとおりです。

  • Chunked
  • Compress
  • Deflate
  • GZip
  • Identity
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Uri

Web 要求の送信先の Uniform Resource Identifier (URI) を指定します。 URI を入力します。 このパラメーターは、HTTP、HTTPS、FTP、FILE の値をサポートします。

このパラメーターは必須です。 パラメーター名 Uri は省略可能です。

Type:Uri
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-UseBasicParsing

コマンドレットがドキュメント オブジェクト モデル (DOM) 解析なしで HTML コンテンツに応答オブジェクトを使用することを示します。 このパラメーターは、Windows Server オペレーティング システムの Server Core インストールなど、コンピューターに Internet Explorer がインストールされていない場合に必要です。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseDefaultCredentials

コマンドレットが現在のユーザーの資格情報を使用して Web 要求を送信することを示します。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UserAgent

Web 要求のユーザー エージェント文字列を指定します。 既定のユーザー エージェントは、オペレーティング システムとプラットフォームごとに若干のバリエーションがある場合と似ています Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0 。

ほとんどのインターネット ブラウザーで使用される標準のユーザー エージェント文字列を使用して Web サイトをテストするには、Chrome、FireFox、Internet、Opera、Safari などの PSUserAgent クラスのプロパティエクスプローラー使用します。 たとえば、次のコマンドでは、インターネット エクスプローラーのユーザー エージェント文字列を使用します。Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WebSession

Web 要求セッションを指定します。 ドル記号 ($) を含む変数名を入力します。

Web 要求セッションの値をオーバーライドするには、UserAgent や Credential などのコマンドレット パラメーターを使用します。 パラメーターの値は、Web 要求セッションの値よりも優先されます。

リモート セッションとは異なり、Web 要求セッションは永続的な接続ではありません。 Web 要求セッションは、Cookie、資格情報、リダイレクトの最大値、ユーザー エージェント文字列などの、接続と要求に関する情報を含むオブジェクトです。 Web 要求セッションを使用して、Web 要求の間で状態とデータを共有することができます。

Web 要求セッションを作成するには、コマンドの SessionVariable パラメーターの値に、ドル記号なしで変数名をInvoke-WebRequest入力します。 Invoke-WebRequest はセッションを作成し、変数に保存します。 後続のコマンドでは、変数を WebSession パラメーターの値として使用します。

同じコマンドで SessionVariable パラメーターと WebSession パラメーターを使用することはできません。

Type:WebRequestSession
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

入力

Object

Web 要求の本文をこのコマンドレットにパイプできます。

出力

HtmlWebResponseObject

このコマンドレットは、Web 要求の結果を表す応答オブジェクトを返します。

メモ

Windows PowerShell には、次のエイリアスが Invoke-WebRequest含まれています。

  • iwr