Invoke-WebRequest

リファレンス

モジュール:: Microsoft.PowerShell.Utility

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

構文

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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

説明

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

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

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

重要

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

例

例 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値にの値を指定します。コマンドが完了すると、変数には $LoginResponseBasicHtmlWebResponseObject が含まれており、 $Session 変数にはオブジェクトが WebRequestSession 含まれます。これにより、ユーザーがサイトにログインします。

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

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

この例では、Web ページ内のリンクを取得します。コマンドレットを Invoke-WebRequest 使用して Web ページのコンテンツを取得します。次に、返される BasicHtmlWebResponseObjectInvoke-WebRequest の 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 は、のフォームフィールド documentContent-Typetext/plainとして送信されます。

$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

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

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

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

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

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

終了エラーは、Exception オブジェクトから 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
}

例 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 ページのコンテンツを取得します。次に、返される BasicHtmlWebResponseObjectInvoke-WebRequest の Links プロパティと、各リンクの Href プロパティを使用します。

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

パラメーター

-AllowUnencryptedAuthentication

暗号化されていない接続を介した資格情報とシークレットの送信を許可します。既定では、資格情報または認証オプションにで始https://まらない URI を指定すると、エラーが発生し、暗号化されていない接続を介してプレーンテキスト内のシークレットが意図せずに通信されないように要求が中止されます。この動作を自分の責任でオーバーライドするには、 AllowUnencryptedAuthentication パラメーターを指定します。

警告

このパラメーターの使用は安全ではなく、推奨されません。これは、暗号化された接続を提供できないレガシシステムとの互換性のためにのみ提供されます。ご自身の責任で使用してください。

この機能は PowerShell 6.0.0 で追加されました。

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

-Authentication

要求に使用する明示的な認証の種類を指定します。既定値は [None](なし) です。 Authentication パラメーターは、UseDefaultCredentials パラメーターでは使用できません。

使用可能な認証オプション:

None: 認証が指定されていない場合の既定のオプションです。明示的な認証は使用されません。
Basic: 資格情報が必要です。資格情報は、の形式base64(user:password)で RFC 7617 基本認証Authorization: Basicヘッダーとして送信されます。
Bearer: Token パラメーターが必要です。指定されたトークンを使用して RFC 6750 Authorization: Bearer ヘッダーを送信します。
OAuth: Token パラメーターが必要です。指定されたトークンを使用して RFC 6750 Authorization: Bearer ヘッダーを送信します。

認証を指定すると、ヘッダーに指定されたヘッダーまたは WebSession に含まれるヘッダーがAuthorizationオーバーライドされます。

この機能は PowerShell 6.0.0 で追加されました。

Type:	WebAuthenticationType
Accepted values:	None, Basic, Bearer, OAuth
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Body

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

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

入力が POST 要求で、本文が String の場合、最初の等号 (=) の左側の値がフォームデータのキーとして設定され、残りのテキストが値として設定されます。複数のキーを指定するには、Body にハッシュテーブルなどの IDictionary オブジェクトを使用します。

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

入力がSystem.Xml の場合 。XmlNode オブジェクトと XML 宣言はエンコードを指定します。そのエンコードは、 ContentType パラメーターでオーバーライドされない限り、要求内のデータに使用されます。

Body パラメーターは、オブジェクトも受け入れますSystem.Net.Http.MultipartFormDataContent。これにより、要求が multipart/form-data 容易になります。 Body に MultipartFormDataContent オブジェクトを指定すると、ContentType、Headers、または WebSession パラメーターに指定された Content 関連ヘッダーは、MultipartFormDataContent オブジェクトの Content ヘッダーによってオーバーライドされます。この機能は PowerShell 6.0.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証明書を見つけます。

注意

この機能は、Windows OS プラットフォームでのみサポートされています。

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

-ContentType

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

ContentType の値にエンコード形式 (ascharset) が含まれている場合、コマンドレットはその形式を使用して Web 要求の本文をエンコードします。 ContentType でエンコード形式が指定されていない場合は、代わりに既定のエンコード形式が使用されます。エンコード形式を持つ ContentType の例として、があります text/plain; charset=iso-8859-5。これは、ラテン/キリル文字のアルファベットを指定します。

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

ContentType は、Body に MultipartFormDataContent オブジェクトが指定されるとオーバーライドされます。

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

-Credential

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

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

資格情報 は、単独で使用することも、特定の認証パラメーターオプションと組み合わせて使用することもできます。単独で使用する場合、リモートサーバーが認証チャレンジ要求を送信する場合にのみ、資格情報がリモートサーバーに提供されます。認証オプションと共に使用すると、資格情報が明示的に送信されます。

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

注意

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

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

-CustomMethod

Web 要求に使用されるカスタムメソッドを指定します。これは、エンドポイントで必要な要求メソッドがメソッドで使用できないオプションである場合に使用できます。 メソッド と CustomMethod を一緒に使用することはできません。

この例では、 TEST API に対して HTTP 要求を行います。

Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

この機能は PowerShell 6.0.0 で追加されました。

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

-DisableKeepAlive

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

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

-Form

ディクショナリを送信に multipart/form-data 変換します。 Form を Body と共に使用することはできません。 ContentType が使用されている場合は無視されます。

ディクショナリのキーは、フォームフィールド名として使用されます。既定では、フォーム値は文字列値に変換されます。

値が System.IO.FileInfo オブジェクトの場合、バイナリファイルの内容が送信されます。ファイルの名前は filename プロパティとして 送信されます。 MIME の種類はとして application/octet-stream設定されます。 Get-Item を使用すると、 System.IO.FileInfo オブジェクトの指定を簡略化できます。

$Form = @{ resume = 'c:\Users\jdoe\Documents\John Doe.pdf' } を Get-Item

値が Array やListsなどのコレクション型の場合、for フィールドは複数回送信されます。リストの値は、既定で文字列として扱われます。値が System.IO.FileInfo オブジェクトの場合、バイナリファイルの内容が送信されます。入れ子になったコレクションはサポートされていません。

$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

上記の例では、tagsフィールドは、および 2017のそれぞれにVacationItaly対して 1 回、フォームに 3 回指定されています。この pictures フィールドは、フォルダー内 2017-Italy のファイルごとに 1 回送信されます。そのフォルダー内のファイルのバイナリコンテンツは、値として送信されます。

この機能は、PowerShell 6.1.0 で追加されました。

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

-Headers

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

などContent-Type、コンテンツ関連のヘッダーは、Body に MultipartFormDataContent オブジェクトが指定されたときにオーバーライドされます。

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

-HttpVersion

要求に使用される HTTP バージョンを指定します。既定値は、1.1 です。

有効な値は次のとおりです。

Type:	Version
Position:	Named
Default value:	1.1
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:	5
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRetryCount

400 から 599 までのエラーコード (304 を含む) を受信したときに、PowerShell が接続を再試行する回数を指定します。再試行回数の指定については、「 RetryIntervalSec パラメーター」も参照してください。

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

CustomMethod パラメーターは、上記に記載されていない要求メソッドに使用できます。

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

-NoProxy

コマンドレットがプロキシを使用して宛先に到達しないことを示します。環境で構成されているプロキシをバイパスする必要がある場合は、このスイッチを使用します。この機能は PowerShell 6.0.0 で追加されました。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	True
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:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PreserveAuthorizationOnRedirect

コマンドレットがリダイレクト間でヘッダーを Authorization 保持する必要があることを示します。

既定では、コマンドレットはリダイレクトする前にヘッダーを Authorization 削除します。このパラメーターを指定すると、ヘッダーをリダイレクトの場所に送信する必要がある場合にこのロジックが無効になります。

この機能は PowerShell 6.0.0 で追加されました。

Type:	SwitchParameter
Position:	Named
Default value:	False
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 パラメーターで指定されたプロキシサーバーを使用するアクセス許可を持つユーザーアカウントを指定します。既定値は現在のユーザーです。

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

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

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

-ProxyUseDefaultCredentials

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

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

-Resume

部分ファイルのダウンロードを再開するためのベストエフォート試行を実行します。再開には OutFile が必要です。

Resume は、ローカルファイルとリモートファイルのサイズに対してのみ機能し、ローカルファイルとリモートファイルが同じであるという他の検証は実行しません。

ローカルファイルサイズがリモートファイルサイズよりも小さい場合、コマンドレットはファイルのダウンロードを再開し、残りのバイトをファイルの末尾に追加しようとします。

ローカルファイルサイズがリモートファイルサイズと同じ場合、アクションは実行されません。コマンドレットはダウンロードが既に完了していることを前提としています。

ローカルファイルサイズがリモートファイルサイズより大きい場合は、ローカルファイルが上書きされ、リモートファイル全体が再ダウンロードされます。この動作は、Resume なしで OutFile を使用する場合と同じです。

リモートサーバーでダウンロード再開がサポートされていない場合は、ローカルファイルが上書きされ、リモートファイル全体が再ダウンロードされます。この動作は、Resume なしで OutFile を使用する場合と同じです。

ローカルファイルが存在しない場合は、ローカルファイルが作成され、リモートファイル全体がダウンロードされます。この動作は、Resume なしで OutFile を使用する場合と同じです。

この機能は、PowerShell 6.1.0 で追加されました。

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

-RetryIntervalSec

400 から 599 までのエラーコード (304 を含む) を受信したときの接続の再試行間隔を指定します。再試行回数の指定については、「 MaximumRetryCount パラメーター」も参照してください。値はとの[int]::MaxValue間1である必要があります。

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

-SessionVariable

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

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

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

PowerShell 7.4 以降では、後続の要求でセッションのプロパティがオーバーライドされない限り、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

-SkipCertificateCheck

証明書の検証チェックをスキップします。これには、有効期限、失効、信頼されたルート機関などのすべての検証が含まれます。

警告

このパラメーターの使用はセキュリティで保護されていないため、推奨されません。このスイッチは、テスト目的で自己署名証明書を使用して既知のホストに対してのみ使用することを目的としています。ご自身の責任で使用してください。

この機能は PowerShell 6.0.0 で追加されました。

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

-SkipHeaderValidation

コマンドレットが検証なしで要求にヘッダーを追加する必要があることを示します。

このスイッチは、標準に準拠していないヘッダー値を必要とするサイトに使用する必要があります。このスイッチを指定すると、検証が無効になり、値をオフにして渡すことができます。指定すると、すべてのヘッダーが検証なしで追加されます。

このスイッチは、 ContentType、 Headers 、 UserAgent の各パラメーターに渡される値の検証を無効にします。

この機能は PowerShell 6.0.0 で追加されました。

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

-SkipHttpErrorCheck

このパラメーターを指定すると、コマンドレットは HTTP エラーの状態を無視し、応答の処理を続行します。エラー応答は、成功したかのようにパイプラインに書き込まれます。

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

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

-SslProtocol

Web 要求に対して許容される SSL/TLS プロトコルを設定します。既定では、システムでサポートされている SSL/TLS プロトコルはすべて許可されます。 SslProtocol を使用すると、コンプライアンスのために特定のプロトコルに制限できます。

これらの値は、フラグベースの列挙体として定義されます。複数の値を組み合わせて、このパラメーターを使用して複数のフラグを設定できます。値は、値の配列として、またはそれらの値のコンマ区切り文字列として SslProtocol パラメーターに渡すことができます。コマンドレットは、binary-OR 操作を使用して値を結合します。配列として値を渡すことは最も簡単なオプションであり、値にタブ補完を使用することもできます。すべてのプラットフォームで複数のオプションを定義できない場合があります。

注意

Windows 以外のプラットフォームでは、または Tls12 をオプションとして提供Tlsできない場合があります。の Tls13 サポートはすべてのオペレーティングシステムで利用できるわけではありません。オペレーティングシステムごとに確認する必要があります。

この機能は PowerShell 6.0.0 で追加され、の Tls13 サポートは PowerShell 7.1 で追加されました。

Type:	WebSslProtocol
Accepted values:	Default, Tls, Tls11, Tls12
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TimeoutSec

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

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

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

-Token

要求に含める OAuth またはベアラートークン。 トークン は、特定の認証オプションで必要です。個別に使用することはできません。

トークン は、トークンを SecureString 含むを受け取ります。トークンを手動で指定するには、次を使用します。

Invoke-WebRequest -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

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

Type:	SecureString
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 要求の送信先となるインターネットリソースの URI (Uniform Resource Identifier) を指定します。 URI を入力します。このパラメーターは HTTP または HTTPS のみをサポートします。

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

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

-UseBasicParsing

このパラメーターは非推奨になりました。 PowerShell 6.0.0 以降では、すべての Web 要求で基本的な解析のみが使用されます。このパラメーターは下位互換性のためにのみ含まれており、このパラメーターを使用してもコマンドレットの操作には影響しません。

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

-UseDefaultCredentials

コマンドレットが現在のユーザーの資格情報を使用して Web 要求を送信することを示します。これは認証または 資格情報 では使用できません。また、すべてのプラットフォームでサポートされているわけではありません。

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

-UserAgent

Web 要求のユーザーエージェント文字列を指定します。

既定のユーザーエージェントは、と似ています Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 が、オペレーティングシステムとプラットフォームごとに若干のバリエーションがあります。

ほとんどのインターネットブラウザーで使用される標準のユーザーエージェント文字列を使用して Web サイトをテストするには、Chrome、FireFox、InternetExplorer、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 要求セッションの値よりも優先されます。などのContent-Typeコンテンツ関連ヘッダーは、Body に MultipartFormDataContent オブジェクトが指定されている場合にもオーバーライドされます。

リモートセッションとは異なり、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 要求の本文をこのコマンドレットにパイプできます。

出力

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

次の方法で共有

Invoke-WebRequest

構文

説明

例

例 1: Web 要求を送信する

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

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

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

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

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

例 7: Invoke-WebRequest から成功しないメッセージをキャッチする

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

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

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

パラメーター

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

入力

出力

メモ

関連リンク

その他のリソース

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

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