Invoke-WebRequest

模組:: Microsoft.PowerShell.Utility Module

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

語法

StandardMethod (預設值)

Invoke-WebRequest
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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>]

StandardMethodNoProxy

Invoke-WebRequest
    [-Uri] <Uri>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethod

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Description

Invoke-WebRequest Cmdlet 會將 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 變數中。

第二個命令會取得任何 InputField，其中 Name 屬性就像 "* Value"。篩選的結果會透過管道傳送至 Select-Object，以選取 Name 和 Value 屬性。

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

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

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

$Session

$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

$ProfileResponse

第一次呼叫 Invoke-WebRequest 會傳送登入要求。該命令為 -SessionVariable 參數的值指定值“Session”，並將結果保存在變數中 $LoginResponse 。命令完成後， $LoginResponse 變數包含物件 BasicHtmlWebResponseObject ， $Session 變數包含物件 WebRequestSession 。這會將用戶記錄到網站。

調用 $Session 本身顯示 WebRequestSession 變數中的物件。

第二次調用提取 Invoke-WebRequest 使用者的配置檔，這需要用戶登錄到網站。存儲在變數中的 $Session 會話數據用於向登錄期間創建的網站提供會話 cookie。結果保存在變數中 $ProfileResponse 。

對的 $ProfileResponse 呼叫自己在變數中顯示 the BasicHtmlWebResponseObject 。

範例 3：從網頁取得連結

本範例會取得網頁中的連結。它會使用 Invoke-WebRequest Cmdlet 來取得網頁內容。然後，它使用返回的的 BasicHtmlWebResponseObjectInvoke-WebRequestLinks 屬性和每個連結的 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 會以 document的 Content-Type 作為 text/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：簡化的多部分/Form-Data 提交

某些 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

終止錯誤是由 catch 區塊攔截，它會從 Exception 物件擷取 StatusCode。

參數

-AllowUnencryptedAuthentication

允許透過未加密連線傳送認證和秘密。默認情況下，提供 Credential 或任何 Authentication 選項，其 Uri 開頭不是為會導致 https:// 錯誤，並且請求將中止，以防止無意中通過未加密的連接以純文本形式通信機密。若要以您自己的風險覆寫此行為，請提供 AllowUnencryptedAuthentication 參數。

警告

使用此參數並不安全，不建議使用。它僅適用於無法提供加密連線的舊版系統相容性。以您自己的風險使用。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Authentication

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

可用的驗證選項：

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

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	WebAuthenticationType
預設值:	None
接受的值:	None, Basic, Bearer, OAuth
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Body

指定請求的主體內容。請求的主體是緊接著標頭的內容。您也可以將資料流參數的值傳送至 Invoke-WebRequest。

Body 參數可用來指定查詢參數清單或指定回應的內容。

當輸入是 GET 請求並且正文是 IDictionary （通常是哈希表）時，正文將作為查詢參數添加到 URI 中。對於其他要求類型（例如 POST），本文會設定為標準 name=value 格式的要求本文值。

Body 參數也可以接受物件System.Net.Http.MultipartFormDataContent。這有助於 multipart/form-data 要求。當 MultipartFormDataContent 物件提供給 Body時，提供給 ContentType、Headers或 WebSession 參數的任何內容相關標頭會由 MultipartFormDataContent 物件的 Content 標頭覆寫。此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	Object
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Certificate

指定用於安全 Web 要求的客戶端憑證。輸入包含憑證的變數，或取得憑證的命令或表達式。

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

參數屬性

類型:	X509Certificate
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CertificateThumbprint

指定有權傳送要求之用戶帳戶的數位公鑰憑證（X509）。輸入憑證的指紋。

憑證用於客戶端憑證型驗證。它們只能對應至本機用戶帳戶;它們無法與網域帳戶搭配使用。

若要取得憑證指紋，請使用PowerShell Get-Item 磁碟驅動器中的 Get-ChildItem 或 Cert: 命令。

備註

此功能目前僅支援 Windows OS 平臺。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ContentType

指定 Web 要求的內容類型。

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

當 MultipartFormDataContent 物件提供給 Body時，會覆寫 contentType 。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Credential

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

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

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

認證會儲存在 PSCredential 物件中，密碼會儲存為 secureString 。

備註

如需 SecureString 數據保護的詳細資訊，請參閱 SecureString 有多安全？。

參數屬性

類型:	PSCredential
預設值:	Current user
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CustomMethod

指定用於 Web 要求的自訂方法。如果端點所需的要求方法不是方法上的可用選項，就可以使用這個選項。方法和 CustomMethod 無法一起使用。

此範例會向 API 提出 TEST HTTP 要求：

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	公分

參數集

CustomMethod

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-DisableKeepAlive

指出 Cmdlet 會將 HTTP 標頭中的 KeepAlive 值設定為 False。根據預設，KeepAlive是 true。 KeepAlive 會建立與伺服器的持續性連線，以利後續的要求。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Form

將字典轉換成 multipart/form-data 提交。 Form 不能與 Body搭配使用。如果使用 ContentType，則會予以忽略。

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

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

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

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

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

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

此功能已在PowerShell 6.1.0中新增。

參數屬性

類型:	IDictionary
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Headers

指定 Web 要求的標頭。輸入哈希表或字典。

若要設定 UserAgent 標頭，請使用 UserAgent 參數。不能使用此參數指定 User-Agent 或 Cookie 標頭。

與內容相關的標頭，例如Content-Type，當為 Body 提供 MultipartFormDataContent 物件時，將被覆蓋。

參數屬性

類型:	IDictionary
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InFile

從檔案取得 Web 要求的內容。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumRedirection

指定 PowerShell 在連線失敗之前，將連線重新導向至替代統一資源識別碼（URI）的次數。預設值為 5。值為 0 （零）會防止所有重新導向。

參數屬性

類型:	Int32
預設值:	5
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumRetryCount

指定收到 400 到 599 之間的失敗碼或 304 時，PowerShell 重試連線的次數。另請參閱 RetryIntervalSec 參數以指定重試次數。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Method

指定用於 Web 要求的方法。此參數可接受的值為：

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

CustomMethod 參數可用於上述未列出的要求方法。

參數屬性

類型:	WebRequestMethod
預設值:	None
接受的值:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

StandardMethodNoProxy

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-NoProxy

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-OutFile

指定此 Cmdlet 儲存回應本文的輸出檔案。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。名稱會被視為字面上的路徑。包含方括弧（[]）的名稱必須以單引弧括住（'）。

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PassThru

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PreserveAuthorizationOnRedirect

指出當存在時，Cmdlet 應該在重定向過程中保留 Authorization 標頭。

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Proxy

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

參數屬性

類型:	Uri
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProxyCredential

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

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

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

參數屬性

類型:	PSCredential
預設值:	Current user
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProxyUseDefaultCredentials

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

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Resume

盡最大努力繼續下載部分檔案。繼續需要 OutFile。

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

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

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

如果本機檔案大小大於遠端檔案大小，則會覆寫本機檔案，並重新下載整個遠端檔案。此行為等同於使用 OutFile 而不使用 Resume。

如果遠端伺服器不支援恢復下載，則覆蓋本地檔並重新下載整個遠端檔。此行為等同於使用 OutFile 而不使用 Resume。

如果本地檔不存在，則創建本地檔並下載整個遠端檔。此行為等同於使用 OutFile 而不使用 Resume。

此功能已在PowerShell 6.1.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-RetryIntervalSec

指定當收到 400 到 599（包含）或 304 的失敗碼時，連線重試的間隔。另請參閱 MaximumRetryCount 參數，以指定重試次數。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SessionVariable

指定此 Cmdlet 建立 Web 要求工作階段並將它儲存在值的變數。輸入不含 "$" 符號（$）的變數名稱。

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

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

若要在後續的網頁請求中使用網頁請求會話，請在 WebSession 參數的值中指定會話變數。 PowerShell 會在建立新的連線時，使用 Web 要求工作階段物件中的數據。若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值優先於網路要求會話中的值。

您無法在相同的命令中使用 SessionVariable 和 WebSession 參數。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	SV

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipCertificateCheck

略過憑證驗證檢查。這包括所有驗證，例如到期、撤銷、受信任的根授權單位等。

警告

使用此參數並不安全，不建議使用。此開關僅限用於在使用自我簽署憑證進行測試的已知主機上。以您自己的風險使用。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipHeaderValidation

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

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

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipHttpErrorCheck

此參數會使 Cmdlet 忽略 HTTP 錯誤狀態，並繼續處理回應。錯誤回應會被寫入管線，呈現方式就像是成功回應一樣。

此參數是在 PowerShell 7 中引進的。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SslProtocol

設定 Web 要求允許的 SSL/TLS 通訊協定。根據預設，系統支援 SSL/TLS 通訊協定。 SslProtocol 允許針對特定通訊協議進行合規性限制。

這些值會定義為旗標型列舉。您可以將多個值結合在一起，以使用此參數來設定多個旗標。這些值可以傳遞至 SslProtocol 參數做為值的陣列，或做為這些值的逗號分隔字串。 Cmdlet 會使用二進位 OR 作業來合併值。將值以陣列的形式傳遞是最簡單的選擇，還可以讓您在使用 Tab 鍵時自動完成值。您可能無法在所有平台上定義多個選項。

備註

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

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

參數屬性

類型:	WebSslProtocol
預設值:	None
接受的值:	Default, Tls, Tls11, Tls12
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TimeoutSec

指定請求逾時前可擱置的時間長度。輸入以秒為單位的數值。預設值 0 表示無限期等待。

功能變數名稱系統（DNS）查詢最多可能需要 15 秒才能返回或超時。如果您的請求包含需要解析的主機名，並且您將 TimeoutSec 設置為大於零但小於 15 秒的值，則可能需要 15 秒或更長時間才能引發 WebException，並且您的請求超時。

參數屬性

類型:	Int32
預設值:	0
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Token

要包含在要求中的 OAuth 或 Bearer 令牌。某些驗證選項需要令牌。它不能獨立使用。

令牌接受包含令牌的 SecureString。若要手動提供令牌，請使用下列專案：

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

此參數是在 PowerShell 6.0 中引進的。

參數屬性

類型:	SecureString
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TransferEncoding

指定傳輸編碼 HTTP 回應標頭的值。此參數可接受的值為：

分塊
壓縮
洩氣
GZip
身份

參數屬性

類型:	String
預設值:	None
接受的值:	chunked, compress, deflate, gzip, identity
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Uri

指定傳送 Web 要求之因特網資源的統一資源識別碼（URI）。輸入 URI。此參數僅支援 HTTP 或 HTTPS。

這是必要參數。 uri 參數名稱是選擇性的。

參數屬性

類型:	Uri
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UseBasicParsing

此參數已被取代。從 PowerShell 6.0.0 開始，所有網頁請求只會使用基本解析。此參數僅供回溯相容性使用，且任何使用它不會影響 Cmdlet 的作業。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UseDefaultCredentials

指出 Cmdlet 會使用目前使用者的認證來傳送 Web 要求。這無法與驗證或認證搭配使用，而且在所有平臺上都不支援。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UserAgent

指定 Web 要求的使用者代理字串。

默認使用者代理程式類似於 Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0，每個作業系統和平臺都有輕微的變化。

若要使用大多數 Internet 瀏覽器使用的標準使用者代理字串測試網站，請使用 PSUserAgent 類的屬性，例如 Chrome、FireFox、InternetExplorer、Opera 和 Safari。

例如，下列命令使用 Internet Explorer 的使用者代理程式字串：Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-WebSession

指定網頁要求會話。輸入變數名稱，包括貨幣符號（$）。

若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值優先於網路要求會話中的值。當 Content-Type 物件提供 Body時，也會覆寫內容相關標頭，例如。

若要建立 Web 要求會話，請在命令的 Invoke-WebRequest 參數的值中輸入變數名稱，但不包含美元符號。 Invoke-WebRequest 建立會話，並將它儲存在變數中。在後續命令中，使用變數作為 WebSession 參數的值。

您無法在相同的命令中使用 SessionVariable 和 WebSession 參數。

參數屬性

類型:	WebRequestSession
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。如需詳細資訊，請參閱 about_CommonParameters。

輸入

Object

您可以使用管線將 Web 要求的本文傳送至 Invoke-WebRequest。

輸出

BasicHtmlWebResponseObject

備註

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

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

由於 .NET Core 3.1 中的更改，PowerShell 7.0 及更高版本使用 HttpClient.DefaultProxy 屬性來確定代理配置。

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

適用於 Windows：從環境變數讀取 Proxy 組態。如果未定義這些變數，則該屬性派生自使用者的代理設置。
for macOS：從環境變數讀取 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

語法

StandardMethod (預設值)

StandardMethodNoProxy

CustomMethod

CustomMethodNoProxy

Description

範例

範例 1：傳送 Web 要求

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

範例 3：從網頁取得連結

範例 4：使用請求頁面中定義的編碼將響應內容寫入檔。

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

範例 6：簡化的多部分/Form-Data 提交

範例 7：從 Invoke-WebRequest 攔截非成功訊息

參數

-AllowUnencryptedAuthentication

參數屬性

參數集

-Authentication

參數屬性

參數集

-Body

參數屬性

參數集

-Certificate

參數屬性

參數集

-CertificateThumbprint

參數屬性

參數集

-ContentType

參數屬性

參數集

-Credential

參數屬性

參數集

-CustomMethod

參數屬性

參數集

-DisableKeepAlive

參數屬性

參數集

-Form

參數屬性

參數集

-Headers

參數屬性

參數集

-InFile

參數屬性

參數集

-MaximumRedirection

參數屬性

參數集

-MaximumRetryCount

參數屬性

參數集

-Method

參數屬性

參數集

-NoProxy

參數屬性

參數集

-OutFile

參數屬性

參數集

-PassThru

參數屬性

參數集

-PreserveAuthorizationOnRedirect

參數屬性

參數集

-Proxy

參數屬性

參數集

-ProxyCredential

參數屬性

參數集