Invoke-WebRequest

構文

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

説明

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

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

PowerShell 7.0 以降では、 Invoke-WebRequest は環境変数によって定義されたプロキシ構成をサポートしています。 この記事の「 Notes 」セクションを参照してください。

PowerShell 7.4 以降では、要求の文字エンコードは既定で ASCII ではなく UTF-8 に設定されています。 別のエンコードが必要な場合は、Content-Type ヘッダーにcharset属性を設定する必要があります。

例

例 1: Web 要求を送信する

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

$Response = Invoke-WebRequest -URI https://www.bing.com/search?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

最初のコマンドは要求を発行し、応答を $Response 変数に保存します。

2 番目のコマンドは、Name プロパティが"* Value"のようなInputFieldを取得します。 フィルター処理された結果は Select-Object にパイプ処理され、 Name および Value プロパティが選択されます。

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

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

$LoginParameters = @{
    Uri             = 'https://www.contoso.com/login/'
    SessionVariable = 'Session'
    Method          = 'POST'
    Body            = @{
        User     = 'jdoe'
        Password = 'P@S$w0rd!'
    }
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

Invoke-WebRequestへの最初の呼び出しは、サインイン要求を送信します。 このコマンドは、SessionVariable パラメーターの値にSessionの値を指定します。 コマンドが完了すると、 $LoginResponse 変数には BasicHtmlWebResponseObject $Session 変数に WebRequestSession オブジェクトが含まれます。 これにより、ユーザーがサイトにログインします。

Invoke-WebRequestへの 2 回目の呼び出しでは、ユーザーのプロファイルがフェッチされます。この場合、ユーザーはサイトにサインインする必要があります。 $Session変数に格納されているセッション データは、ログイン中に作成されたサイトにセッション Cookie を提供します。

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

この例では、Web ページ内のリンクを取得します。 Invoke-WebRequest コマンドレットを使用して Web ページのコンテンツを取得します。 次に、Invoke-WebRequestが返す BasicHtmlWebResponseObject の Links プロパティと、各リンクの Href プロパティを使用します。

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

例 4: 要求されたページで定義されているエンコードを使用して、応答コンテンツをファイルに書き込む

この例では、 Invoke-WebRequest コマンドレットを使用して、PowerShell ドキュメント ページの Web ページコンテンツを取得します。

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
} finally {
    $Stream.Dispose()
}

最初のコマンドはページを取得し、応答オブジェクトを $Response 変数に保存します。

2 番目のコマンドは、応答コンテンツをファイルに書き込むのに使用する StreamWriter を作成します。 応答オブジェクトの Encoding プロパティを使用して、ファイルのエンコードを設定します。

最後のいくつかのコマンドは、 Content プロパティをファイルに書き込み、 StreamWriterを破棄します。

Web 要求がテキスト コンテンツを返さない場合、 Encoding プロパティは null であることに注意してください。

例 5: マルチパート/フォーム データ ファイルを送信する

この例では、 Invoke-WebRequest コマンドレットを使用して、ファイルを multipart/form-data 送信としてアップロードします。 ファイル c:\document.txtは、text/plainのContent-Typeと共にdocumentフォーム フィールドとして送信されます。

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

例 6: 簡略化されたマルチパート/フォーム データ送信

一部の API では、ファイルと混合コンテンツをアップロードするために multipart/form-data 送信が必要です。 この例では、ユーザー プロファイルの更新を示します。

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-WebRequest -Uri $Uri -Method Post -Form $Form

プロファイル フォームには、 firstName、 lastName、 email、 avatar、 birthday、 hobbiesの各フィールドが必要です。 API では、ユーザー プロファイルの画像が avatar フィールドに提供されることを想定しています。 API は、同じ形式で送信される複数の hobbies エントリも受け入れます。

$Form HashTable を作成するときに、キー名がフォーム フィールド名として使用されます。 既定では、HashTable の値は文字列に変換されます。 System.IO.FileInfo 値が存在する場合は、ファイルの内容が送信されます。 配列やリストなどのコレクションが存在する場合、フォーム フィールドは複数回送信されます。

avatar キーでGet-Itemを使用すると、FileInfo オブジェクトが値として設定されます。 その結果、 jdoe.png の画像データが送信されます。

hobbies キーにリストを指定すると、hobbies フィールドがリスト アイテムごとに提出に 1 回存在します。

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

Invoke-WebRequestが成功しない HTTP メッセージ (404、500 など) を検出すると、出力は返されません。終了エラーがスローされます。 エラーをキャッチして 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

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

例 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
}

例 9: ヘッダー検証のスキップ

既定では、 Invoke-WebRequest コマンドレットは、標準で定義された値形式を持つ既知のヘッダーの値を検証します。 次の例は、この検証でエラーが発生する方法と、 SkipHeaderValidation パラメーターを使用して、無効に書式設定された値を許容するエンドポイントの値の検証を回避する方法を示しています。

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation

Invoke-WebRequest: The format of value '12345' is invalid.

StatusCode        : 200
StatusDescription : OK
Content           : {
                      "headers": {
                        "Host": "httpbin.org",
                        "If-Match": "12345",
                        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.19044; en-US) PowerShell/7.2.5",
                        "X-Amzn-Trace-Id": �
RawContent        : HTTP/1.1 200 OK
                    Date: Mon, 08 Aug 2022 16:24:24 GMT
                    Connection: keep-alive
                    Server: gunicorn/19.9.0
                    Access-Control-Allow-Origin: *
                    Access-Control-Allow-Credentials: true
                    Content-Type: application�
Headers           : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 249
RelationLink      : {}

httpbin.org は、トラブルシューティングのために Web 要求と応答に関する情報を返すサービスです。 $Uri変数はサービスの/headers エンドポイントに割り当てられ、要求のヘッダーが応答の内容として返されます。

If-Match要求ヘッダーは、RFC-7232 セクション 3.1 で定義されておりそのヘッダーの値を周囲の引用符で定義する必要があります。 $InvalidHeaders変数には、"12345"ではなく12345として定義されているため、If-Matchの値が無効なハッシュ テーブルが割り当てられます。

ヘッダーが無効な Invoke-WebRequest を呼び出すと、書式設定された値が無効であることを示すエラーが返されます。 要求はエンドポイントに送信されません。

SkipHeaderValidation パラメーターを使用してInvoke-WebRequestを呼び出すと、検証エラーが無視され、エンドポイントに要求が送信されます。 エンドポイントは準拠していないヘッダー値を許容するため、コマンドレットはエラーなしで応答オブジェクトを返します。

例 10: HTTP 2.0 を使用して要求を送信する

この例では、HTTP 2.0 プロトコルを使用して Web ページ内のリンクを取得します。 Invoke-WebRequest コマンドレットを使用して Web ページのコンテンツを取得します。 次に、Invoke-WebRequestが返す BasicHtmlWebResponseObject の Links プロパティと、各リンクの Href プロパティを使用します。

(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.Href

例 11: Unix ソケット アプリケーションに要求を送信する

Docker などの一部のアプリケーションでは、通信用の Unix ソケットが公開されています。 この例では、Docker API を使用して Docker イメージの一覧を照会します。 このコマンドレットは、Unix ソケットを使用して Docker デーモンに接続します。

Invoke-WebRequest -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

パラメーター

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

入力

Object

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

出力

BasicHtmlWebResponseObject

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

メモ

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

• すべてのプラットフォーム:
  • iwr

PowerShell 6.0.0 以降では、 Invoke-WebRequest では基本的な解析のみがサポートされます。

詳細については、「 BasicHtmlWebResponseObjectを参照してください。

.NET Core 3.1 の変更により、PowerShell 7.0 以降では HttpClient.DefaultProxy プロパティを使用してプロキシ構成を決定します。

このプロパティの値は、プラットフォームによって決まります。

• Windows の場合: 環境変数からプロキシ構成を読み取ります。 これらの変数が定義されていない場合、プロパティはユーザーのプロキシ設定から派生します。
• macOS の場合: 環境変数からプロキシ構成を読み取ります。 これらの変数が定義されていない場合、プロパティはシステムのプロキシ設定から派生します。
• Linux の場合: 環境変数からプロキシ構成を読み取ります。 これらの変数が定義されていない場合、プロパティは、すべてのアドレスをバイパスする構成されていないインスタンスを初期化します。

Windows と Unix ベースのプラットフォームで DefaultProxy の初期化に使用される環境変数は、次のとおりです。

• HTTP_PROXY: HTTP 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• HTTPS_PROXY: HTTPS 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• ALL_PROXY: HTTP_PROXY または HTTPS_PROXY が定義されていない場合に、HTTP および HTTPS 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• NO_PROXY: プロキシから除外するホスト名のコンマ区切りの一覧。

PowerShell 7.4 では、Brotli 圧縮アルゴリズムのサポートが追加されました。

関連リンク

• Invoke-RestMethod
• ConvertFrom-Json
• ConvertTo-Json