Invoke-WebRequest

參考

模組:: Microsoft.PowerShell.Utility

從因特網上的網頁取得內容。

Syntax

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>]

Description

Cmdlet 會將 Invoke-WebRequest HTTP 和 HTTPS 要求傳送至網頁或 Web 服務。它會剖析回應並傳回連結、影像及其他主要 HTML 元素的集合。

此 Cmdlet 是在 PowerShell 3.0 中引進。

從 PowerShell 7.0 開始， Invoke-WebRequest 支援環境變數所定義的 Proxy 組態。請參閱本文的附註一節。

重要

本文中的範例參考網域中的 contoso.com 主機。這是 Microsoft 用於範例的虛構網域。這些範例的設計目的是要示範如何使用 Cmdlet。不過，由於 contoso.com 網站不存在，因此範例無法運作。調整範例以在環境中裝載。

範例

範例 1：傳送 Web 要求

此範例會 Invoke-WebRequest 使用 Cmdlet 將 Web 要求傳送至 Bing.com 網站。

$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 。

第二個命令會取得 Name 屬性類似 "* Value"的任何 InputField。篩選的結果會以管線傳送至 Select-Object ，以選取 [名稱 ] 和 [ 值 ] 屬性。

範例 2：使用具狀態 Web 服務

此範例示範如何搭配具狀態 Web 服務使用 Invoke-WebRequest Cmdlet。

$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 ，需要使用者登入網站。儲存在變數中的 $Session 會話數據會將會話 Cookie 提供給登入期間所建立的網站。

範例 3：從網頁取得連結

這個範例會取得網頁中的連結。它會使用 Invoke-WebRequest Cmdlet 來取得網頁內容。然後它會使用 BasicHtmlWebResponseObject 的 Links 屬性來Invoke-WebRequest傳回，以及每個連結的 Href 屬性。

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

範例 4：使用要求頁面中定義的編碼方式，將響應內容寫入檔案

此範例會 Invoke-WebRequest 使用 Cmdlet 來擷取 PowerShell 檔頁面的網頁內容。

$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 。

第二個命令會建立 StreamWriter ，以用來將響應內容寫入檔案。響應物件的 Encoding 屬性是用來設定檔案的編碼方式。

最後幾個命令會將 Content 屬性寫入檔案，然後處置 StreamWriter。

請注意，如果 Web 要求未傳回文字內容， 則 Encoding 屬性為 Null。

範例 5：提交多部分/表單數據檔

此範例會 Invoke-WebRequest 使用 Cmdlet 上傳檔案作為 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

設定檔案表單需要下列欄位： firstName、、 lastName、 email、 avatar、 birthday和 hobbies。 API 預期會在欄位中提供使用者配置檔圖片的 avatar 影像。 API 也接受以相同形式提交多個 hobbies 專案。

建立 $Form HashTable時，索引鍵名稱會當做表單域名稱使用。根據預設，HashTable 的值會轉換成字串。如果 存在 System.IO.FileInfo 值，則會提交檔案內容。如果陣列或清單之類的集合存在，則會多次提交表單域。

在 Get-Item 索引鍵上使用 avatar 時，對象 FileInfo 會設定為值。結果是提交的影像數據 jdoe.png 。

藉由提供清單給 hobbies 索引鍵，字段 hobbies 就會出現在每個清單專案的提交中一次。

範例 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：同時下載多個檔案

Cmdlet Invoke-WebRequest 一次只能下載一個檔案。下列範例會使用 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 Cmdlet 會驗證具有標準定義值格式之已知標頭的值。下列範例示範此驗證如何引發錯誤，以及如何使用 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 會指派哈希表，其中的值 If-Match 無效，因為它定義為 12345 ，而不是 "12345"。

使用無效標頭呼叫 Invoke-WebRequest 會傳回錯誤報告格式化的值無效。要求不會傳送至端點。

使用 SkipHeaderValidation 參數呼叫 Invoke-WebRequest 會忽略驗證失敗，並將要求傳送至端點。因為端點容許不符合規範的標頭值，所以 Cmdlet 會傳回回應物件，而不會發生錯誤。

範例 10：使用 HTTP 2.0 傳送要求

此範例會使用 HTTP 2.0 通訊協定取得網頁中的連結。它會使用 Invoke-WebRequest Cmdlet 來取得網頁內容。然後它會使用 BasicHtmlWebResponseObject 的 Links 屬性來Invoke-WebRequest傳回，以及每個連結的 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

指定要用於要求的明確驗證類型。預設值為 [無]。 Authentication 參數無法與 UseDefaultCredentials 參數搭配使用。

可用的驗證選項：

None：未提供驗證時，這是預設選項。未使用明確驗證。
Basic：需要認證。認證會以 RFC 7617 基本身份驗證 Authorization: Basic 標頭的形式傳送，格式為 base64(user:password)。
Bearer：需要 Token 參數。使用提供的令牌傳送 RFC 6750 Authorization: Bearer 標頭。
OAuth：需要 Token 參數。使用提供的令牌傳送 RFC 6750 Authorization: Bearer 標頭。

提供驗證會覆寫提供給標頭或Authorization包含在 WebSession 中的任何標頭。

此功能已在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) ，本文會設定為標準 name=value 格式的要求本文值，並使用 URL 編碼的值。

當輸入為 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 要求的客戶端憑證。輸入包含憑證的變數，或可取得憑證的命令或運算式。

若要尋找憑證，請使用 Get-PfxCertificate 或使用 Get-ChildItem 憑證 (Cert:) 磁碟驅動器中的 Cmdlet。如果憑證無效或沒有足夠的授權，命令就會失敗。

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

-CertificateThumbprint

指定具有傳送要求權限之使用者帳戶的數位公開金鑰憑證 (X509)。請輸入憑證的憑證指紋。

憑證將用於用戶端憑證式驗證。憑證只能對應到本機用戶帳戶，而不能對應到網域帳戶。

若要查看憑證指紋，請使用 Get-Item 或 Get-ChildItem 命令在中 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 的值包含編碼格式 (為 charset) ，Cmdlet 會使用該格式來編碼 Web 要求的本文。如果 ContentType 未指定編碼格式，則會改用預設編碼格式。具有編碼格式的 ContentType 範例是 text/plain; charset=iso-8859-5，它會指定拉丁文/斯拉夫文字母。

如果省略此參數，且要求方法是 POST， Invoke-WebRequest 請將內容類型設定為 application/x-www-form-urlencoded。否則，不會在呼叫中指定內容類型。

當為 Body 提供 MultipartFormDataContent 物件時，就會覆寫 ContentType。

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

-Credential

指定具有傳送要求權限的使用者帳戶。預設為目前使用者。

輸入用戶名稱，例如User01或Domain01\User01，或輸入 Cmdlet 所產生的 Get-CredentialPSCredential 物件。

認證可以 單獨使用，或搭配特定驗證參數選項使用。單獨使用時，只有在遠端伺服器傳送驗證挑戰要求時，才會提供認證給遠端伺服器。搭配驗證選項使用時，會明確傳送認證。

認證會儲存在 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

表示 Cmdlet 會將 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 提交。表單不能與 Body 搭配使用。如果使用 ContentType ，則會忽略它。

字典的索引鍵會當做表單域名稱使用。根據預設，表單值會轉換成字串值。

如果值為 System.IO.FileInfo 物件，則會提交二進位文件內容。檔案的名稱會提交為 filename 屬性。 MIME 型態設定為 application/octet-stream。 Get-Item 可用來簡化 提供 System.IO.FileInfo 物件。

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

如果值是集合類型，例如 Arrays 或清單，則會多次提交 for 字段。清單的值預設會被視為字串。如果值為 System.IO.FileInfo 物件，則會提交二進位文件內容。不支援巢狀集合。

$Form = @{ tags = 'Vacation'， '義大利'， '2017' pictures = Get-ChildItem 'c：\Users\jdoe\Pictures\2017-義大利' }

在上述範例中，tags字段在窗體中提供三次，針對、 Italy和 2017的每個Vacation提供一次。此 pictures 欄位也會針對資料夾中的每個檔案 2017-Italy 提交一次。該資料夾中檔案的二進位內容會提交為值。

此功能已在PowerShell 6.1.0中新增。

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

-Headers

指定 Web 要求的標頭。輸入雜湊表或字典。

為 Body 提供 MultipartFormDataContent 物件時，會覆寫內容相關標頭，例如 Content-Type 。

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 會將連線重新導向至替代統一資源標識碼 (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 參數可用於上述未列出的 Request 方法。

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

表示 Cmdlet 不應該使用 Proxy 來到達目的地。當您需要略過環境中設定的 Proxy 時，請使用此參數。此功能已在PowerShell 6.0.0中新增。

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

-OutFile

指定此 Cmdlet 儲存回應本文的輸出檔。輸入路徑和檔名。若省略路徑，則預設為目前位置。名稱會被視為常值路徑。包含括弧 () [] 的名稱必須以單引弧括住 (') 。

根據預設， Invoke-WebRequest 會將結果傳回至管線。若要傳送結果至檔案與管線，請使用 Passthru 參數。

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

-PassThru

指出 Cmdlet 除了將它們寫入檔案之外，還會傳回結果。只有當命令中也使用 OutFile 參數時，此參數才會有效。

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

-PreserveAuthorizationOnRedirect

指出 Cmdlet 應該在重新導向之間保留 Authorization 標頭。

根據預設，Cmdlet 會在重新導向之前移除 Authorization 標頭。針對需要將標頭傳送至重新導向位置的情況，指定此參數會停用此邏輯。

此功能已在PowerShell 6.0.0中新增。

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

-Proxy

指定要求的 Proxy 伺服器，而不是直接連線到因特網資源。輸入網路 Proxy 伺服器的 URI。

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

-ProxyCredential

指定有權使用 Proxy 參數所指定 Proxy 伺服器的用戶帳戶。預設為目前使用者。

輸入使用者名稱，例如 User01 或 Domain01\User01，或輸入 PSCredential 物件，例如 Cmdlet 所產生的 Get-Credential 名稱。

只有當命令中也使用 Proxy 參數時，此參數才會有效。您無法在相同的命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 參數。

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

-ProxyUseDefaultCredentials

表示 Cmdlet 會使用目前使用者的認證來存取 Proxy 參數所指定的 Proxy 伺服器。

只有當命令中也使用 Proxy 參數時，此參數才會有效。您無法在相同的命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 參數。

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

-Resume

執行最佳嘗試以繼續下載部分檔案。繼續需要 OutFile。

繼續只會在本機檔案和遠端檔案的大小上運作，而且不會執行其他本機檔案和遠端檔案相同的驗證。

如果本機檔案大小小於遠端檔案大小，則 Cmdlet 會嘗試繼續下載檔案，並將剩餘的位元組附加至檔案結尾。

如果本機檔案大小與遠端檔案大小相同，則不會採取任何動作，而且 Cmdlet 會假設下載已完成。

如果本機檔案大小大於遠端檔案大小，則會覆寫本機檔案，並重新下載整個遠端檔案。此行為與不使用 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

指定此 Cmdlet 建立 Web 要求會話的變數，並將它儲存在值中。輸入不含貨幣符號的變數名稱， ($) 符號。

當您指定會話變數時，會建立 Web 要求會話物件， Invoke-WebRequest 並將它指派給 PowerShell 會話中具有指定名稱的變數。一旦命令完成，便可在工作階段中使用變數。

在 PowerShell 7.4 之前，Web 要求會話不是持續性連線。它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。您可以使用它在 Web 要求之間共用狀態與資料。

從 PowerShell 7.4 開始，只要後續要求中不會覆寫工作階段的屬性，Web 要求工作階段就會持續存在。當它們是時，Cmdlet 會使用新的值重新建立會話。持續性會話可減少重複要求的額外負荷，使其更快。

若要在後續 Web 要求中使用 Web 要求工作階段，請在 WebSession 參數值指定工作階段變數。 PowerShell 會在建立新的連接時，使用 Web 要求工作象中的數據。若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 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

指出 Cmdlet 應該在要求中新增標頭，而不需驗證。

此參數應該用於需要不符合標準的標頭值的網站。指定此參數會停用驗證，以允許未核取傳遞值。指定時，會新增所有標頭而不進行驗證。

此參數會停用傳遞至 ContentType、標頭和 UserAgent 參數的值驗證。

此功能已在PowerShell 6.0.0中新增。

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

-SkipHttpErrorCheck

此參數會導致 Cmdlet 忽略 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 參數做為值的陣列，或是這些值的逗號分隔字串。 Cmdlet 會使用二進位 OR 作業來結合值。將值當做數位傳遞是最簡單的選項，也可讓您在值上使用索引標籤完成。您可能無法在所有平台上定義多個選項。

注意

在非 Windows 平臺上，可能無法提供 Tls 或 Tls12 作為選項。 Tls13所有作業系統都無法使用支援，而且必須根據每個操作系統進行驗證。

這項功能已在PowerShell 6.0.0中新增，且已在PowerShell 7.1中新增支援 Tls13 。

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 設定為大於零的值，但小於 15 秒，則擲回 WebException 之前可能需要 15 秒以上的時間，而且您的要求逾時。

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

-Token

要包含在要求中的 OAuth 或持有人令牌。某些驗證選項需要令牌。它無法獨立使用。

Token 接受 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) 。輸入 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 要求只會使用基本剖析。此參數僅包含回溯相容性，且任何使用參數不會影響 Cmdlet 的作業。

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

-UseDefaultCredentials

表示 Cmdlet 會使用目前用戶的認證來傳送 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 每個作業系統和平臺的稍微變化。

若要使用大部分因特網瀏覽器所使用的標準使用者代理程式字串測試網站，請使用 PSUserAgent 類別的屬性，例如 Chrome、FireFox、InternetExplorer、Opera 和 Safari。

例如，下列命令會使用 Internet Explorer 的使用者代理程式字串： 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 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值的優先順序高於 Web 要求工作階段中的值。當為 Body 提供 MultipartFormDataContent 物件時，也會覆寫內容相關標頭，例如 Content-Type。

不同於遠端會話，Web 要求會話不是持續性連線。它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。您可以使用它在 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 要求的主體傳送至此 Cmdlet。

輸出

BasicHtmlWebResponseObject

此 Cmdlet 會傳回代表 Web 要求結果的響應物件。

備註

PowerShell 包含下列的 Invoke-WebRequest別名：

所有平台：
- iwr

從 PowerShell 6.0.0 Invoke-WebRequest 開始，僅支援基本剖析。

如需詳細資訊，請參閱 BasicHtmlWebResponseObject。

由於 .NET Core 3.1 中的變更，因此 PowerShell 7.0 和更新版本會使用 HttpClient.DefaultProxy 屬性來判斷 Proxy 組態。

此屬性的值是由您的平台所決定：

針對 Windows：從環境變數讀取 Proxy 組態。如果未定義這些變數，則屬性衍生自使用者的 Proxy 設定。
針對macOS：從環境變數讀取 Proxy 組態。如果未定義這些變數，則屬性衍生自系統的 Proxy 設定。
針對 Linux：從環境變數讀取 Proxy 組態。如果未定義這些變數，屬性會初始化略過所有位址的非設定實例。

Windows 和 Unix 平台上用於 DefaultProxy 初始化的環境變數如下：

HTTP_PROXY：HTTP 要求上使用之 Proxy 伺服器的主機名或IP位址。
HTTPS_PROXY：HTTPS 要求上使用之 Proxy 伺服器的主機名或IP位址。
ALL_PROXY：在 HTTP 和 HTTPS 要求上使用之 Proxy 伺服器的主機名或 IP 位址，以防HTTP_PROXYHTTPS_PROXY或未定義。
NO_PROXY：應從 Proxy 處理中排除的主機名稱清單 (以逗號分隔)。

共用方式為

Invoke-WebRequest

Syntax

Description

範例

範例 1：傳送 Web 要求

範例 2：使用具狀態 Web 服務

範例 3：從網頁取得連結

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

輸入

輸出

備註

相關連結

其他資源