Invoke-WebRequest

模組:: Microsoft.PowerShell.Utility Module

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

語法

Default (預設值)

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

Description

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

此 Cmdlet 已在 Windows PowerShell 3.0 中引進。

警告

預設情況下， Invoke-WebRequest 會剖析網頁的內容。剖剖頁面時，可能會執行網頁中的指令碼程式碼。使用 -UseBasicParsing 開關來避免執行指令碼程式碼。

可以使用、 curl或wget別名來iwr執行此指令。

範例

範例 1：傳送 Web 要求

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

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

Name       Value
----       -----
From Value 1
To Value   5280

傳 Invoke-WebRequest 回的數據會儲存在變數中 $Response 。回應 的 InputFields 屬性包含表單域。 Where-Object 可用來將表單域篩選為 Name 屬性就像 “* Value”。篩選的結果會透過管道傳送至 Select-Object，以選取 Name 和 Value 屬性。

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

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

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

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

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

第一個命令會使用 Invoke-WebRequest Cmdlet 來傳送登入要求。此命令會指定 SessionVariable 參數值的 “FB” 值，並將結果儲存在 $R 變數中。當命令完成時，$R 變數會包含 HtmlWebResponseObject，而 $FB 變數包含 WebRequestSession 物件。

Invoke-WebRequest Cmdlet 登入 facebook 之後，變數中 Web 回應物件的 $R 属性表示使用者已成功登入。

範例 3：從網頁取得連結

此命令會取得網頁中的連結。

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

Invoke-WebRequest Cmdlet 會取得網頁內容。然後會使用所傳回 HtmlWebResponseObject 的 Links 屬性來顯示每個連結的 Href 屬性。

範例 4：從 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。

範例 5：同時下載多個檔案

Invoke-WebRequest Cmdlet 一次只能下載一個檔案。下列範例會使用 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
}

備註

若要使用 Cmdlet，Start-ThreadJob您必須從 PowerShell 資源庫安裝 ThreadJob 模組。

參數

-Body

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

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

當輸入是 GET 要求，主體是 IDictionary（通常是哈希表），主體會新增至 URI 作為查詢參數。對於其他要求類型（例如 POST），本文會設定為標準 name=value 格式的要求本文值。

當本文是窗體，或它是 Invoke-WebRequest 呼叫的輸出時，PowerShell 會將要求內容設定為表單域。例如：

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

或-

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

參數屬性

類型:	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）。輸入憑證的指紋。

憑證用於客戶端憑證型驗證。憑證只能對應至本機用戶帳戶，而不是網域帳戶。

若要查看憑證指紋，請使用 Get-Item 或 Get-ChildItem 命令，在 Cert:\CurrentUser\My中尋找憑證。

參數屬性

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

參數集

(All)

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

-ContentType

指定 Web 要求的內容類型。

如果 ContentType 的值 包含編碼格式（如 charset），Cmdlet 會使用該格式來編碼 Web 要求的本文。如果 ContentType 未指定編碼格式，則會改用預設編碼格式。具有編碼格式的 ContentType 範例為 text/plain; charset=iso-8859-5，其會指定拉丁文/斯拉夫文字母。

如果您省略參數，內容類型可能會根據您使用的 HTTP 方法而有所不同：

針對 POST 方法，內容類型為 application/x-www-form-urlencoded
針對PUT方法，內容類型為 application/json
對於其他方法，在要求中未指定內容類型

如果您使用 InFile 參數來上傳檔案，您應該設定內容類型。通常，類型應該 application/octet-stream。不過，您必須根據端點的需求來設定內容類型。

參數屬性

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

參數集

(All)

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

-Credential

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

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

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

備註

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

參數屬性

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

參數集

(All)

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

-DisableKeepAlive

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

參數屬性

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

參數集

(All)

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

-Headers

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

若要設定 UserAgent 標頭，請使用 UserAgent 參數。您無法使用此參數來指定 UserAgent 或 Cookie 標頭。

參數屬性

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

參數集

(All)

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

-InFile

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

您也需要設定要求的內容類型。例如，若要上傳檔案，您應該設定內容類型。通常，類型應該 application/octet-stream。不過，您必須根據端點的需求來設定內容類型。

參數屬性

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

參數集

(All)

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

-MaximumRedirection

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

參數屬性

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

參數集

(All)

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

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

參數屬性

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

參數集

(All)

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

-OutFile

指定此 Cmdlet 儲存回應本文的輸出檔案。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。

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

參數屬性

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

參數集

(All)

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

-PassThru

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

備註

當您使用 PassThru 參數時，輸出會寫入管線，但檔案是空的。如需詳細資訊，請參閱 PowerShell 問題 #15409。

參數屬性

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

參數集

(All)

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

-Proxy

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

參數屬性

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

參數集

(All)

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

-ProxyCredential

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

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

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

參數屬性

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

參數集

(All)

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

-ProxyUseDefaultCredentials

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

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

參數屬性

類型:	SwitchParameter
預設值:	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

-TimeoutSec

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

功能變數名稱系統（DNS）查詢最多可能需要 15 秒才能傳回或逾時。如果您的要求包含需要解析的主機名，而且您將 TimeoutSec 設定為大於零的值，但小於 15 秒，則擲回 WebException 之前，可能需要 15 秒以上的時間，而且您的要求逾時。

參數屬性

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

參數集

(All)

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

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

參數屬性

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

參數集

(All)

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

-Uri

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

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

參數屬性

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

參數集

(All)

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

-UseBasicParsing

指出 Cmdlet 會針對沒有檔案物件模型（DOM）剖析的 HTML 內容使用回應物件。當計算機上未安裝 Internet Explorer 時，需要此參數，例如在 Windows Server 操作系統的 Server Core 安裝上。

參數屬性

類型:	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; Windows NT 6.1; en-US) WindowsPowerShell/3.0，每個作業系統和平臺都有輕微的變化。

若要使用大部分因特網瀏覽器所使用的標準使用者代理程式字串來測試網站，請使用 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。參數值優先於網路要求會話中的值。

若要建立 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 要求的主體傳遞給此 Cmdlet。

輸出

HtmlWebResponseObject

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

備註

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

iwr
curl
wget

意見反應

此頁面對您有幫助嗎？

共用方式為

Invoke-WebRequest

語法

Default (預設值)

Description

範例

範例 1：傳送 Web 要求

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

範例 3：從網頁取得連結

範例 4：從 Invoke-WebRequest 擷取非成功訊息

範例 5：同時下載多個檔案

參數

-Body

參數屬性

參數集

-Certificate

參數屬性

參數集

-CertificateThumbprint

參數屬性

參數集

-ContentType

參數屬性

參數集

-Credential

參數屬性

參數集

-DisableKeepAlive

參數屬性

參數集

-Headers

參數屬性

參數集

-InFile

參數屬性

參數集

-MaximumRedirection

參數屬性

參數集

-Method

參數屬性

參數集

-OutFile

參數屬性

參數集

-PassThru

參數屬性

參數集

-Proxy

參數屬性

參數集

-ProxyCredential

參數屬性

參數集

-ProxyUseDefaultCredentials

參數屬性

參數集

-SessionVariable

參數屬性

參數集

-TimeoutSec

參數屬性

參數集

-TransferEncoding

參數屬性

參數集

-Uri

參數屬性

參數集

-UseBasicParsing

參數屬性

參數集

-UseDefaultCredentials

參數屬性

參數集

-UserAgent

參數屬性

參數集

-WebSession

參數屬性