Export (0) Print
Expand All
2 out of 5 rated this helpful - Rate this topic

Invoke-WebRequest

Updated: October 17, 2013

Applies To: Windows PowerShell 4.0

Invoke-WebRequest

Gets content from a web page on the Internet.

Syntax

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




Detailed Description

The Invoke-WebRequest cmdlet sends HTTP and HTTPS requests to a web page or web service. It parses the response and returns collections of forms, links, images, and other significant HTML elements.

This parameter is introduced in Windows PowerShell 3.0.

Parameters

-Body<Object>

Specifies the body of the request. The body is the content of the request that follows the headers. You can also pipe a body value to Invoke-WebRequest.

The Body parameter can be used to specify a list of query parameters or specify the content of the response.

When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.

When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.

For example:

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

- or -

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


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByValue)

Accept Wildcard Characters?

false

-Certificate<X509Certificate>

Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.

To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CertificateThumbprint<String>

Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.

Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.

To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ContentType<String>

Specifies the content type of the web request.

If this parameter is omitted and the request method is POST, Invoke-WebRequest sets the content type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the call.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Credential<PSCredential>

Specifies a user account that has permission to send the request. The default is the current user.

Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.


Aliases

none

Required?

false

Position?

named

Default Value

Current user

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-DisableKeepAlive

Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.


Aliases

none

Required?

false

Position?

named

Default Value

KeepAlive

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Headers<IDictionary>

Specifies the headers of the web request. Enter a hash table or dictionary.

To set UserAgent headers, use the UserAgent parameter. You cannot use this parameter to specify UserAgent or cookie headers.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-InFile<String>

Gets the content of the web request from a file.

Enter a path and file name. If you omit the path, the default is the current location.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-MaximumRedirection<Int32>

Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.


Aliases

none

Required?

false

Position?

named

Default Value

5

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Method<WebRequestMethod>

Specifies the method used for the web request. Valid values are Default, Delete, Get, Head, Merge, Options, Patch, Post, Put, and Trace.


Aliases

none

Required?

false

Position?

named

Default Value

Default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-OutFile<String>

Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.

By default, Invoke-WebRequest returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-PassThru

Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Proxy<Uri>

Uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ProxyCredential<PSCredential>

Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.

Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.

This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.


Aliases

none

Required?

false

Position?

named

Default Value

Current user

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ProxyUseDefaultCredentials

Uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.

This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SessionVariable<String>

Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol.

When you specify a session variable, Invoke-WebRequest creates a web request session object and assigns it to a variable with the specified name in your Windows PowerShell session. You can use the variable in your session as soon as the command completes.

Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.

To use the web request session in subsequent web requests, specify the session variable in the value of the WebSession parameter. Windows PowerShell uses the data in the web request session object when establishing the new connection. To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.

You cannot use the SessionVariable and WebSession parameters in the same command.


Aliases

SV

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TimeoutSec<Int32>

Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.


Aliases

none

Required?

false

Position?

named

Default Value

0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TransferEncoding<String>

Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Uri<Uri>

Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. Enter a URI. This parameter supports HTTP, HTTPS, FTP, and FILE values.

This parameter is required. The parameter name (-Uri) is optional.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-UseBasicParsing

Uses the response object for HTML content without Document Object Model (DOM) parsing.

This parameter is required when Internet Explorer is not installed on the computers, such as on a Server Core installation of a Windows Server operating system.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-UseDefaultCredentials

Uses the credentials of the current user to send the web request.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-UserAgent<String>

Specifies a user agent string for the web request.

The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" with slight variations for each operating system and platform.

To test a website with the standard user agent string that is used by most Internet browsers, use the properties of the PSUserAgent class, such as Chrome, FireFox, InternetExplorer, Opera, and Safari.

For example, the following command uses the user agent string for Internet

Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WebSession<WebRequestSession>

Specifies a web request session. Enter the variable name, including the dollar sign ($).

To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.

Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.

To create a web request session, enter a variable name (without a dollar sign) in the value of the SessionVariable parameter of an Invoke-WebRequest command. Invoke-WebRequest creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the WebSession parameter.

You cannot use the SessionVariable and WebSession parameters in the same command.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.Object

    You can pipe the body of a web request to Invoke-WebRequest


Outputs

The output type is the type of the objects that the cmdlet emits.

  • Microsoft.PowerShell.Commands.HtmlWebResponseObject

Examples

Example 1

This command uses the Invoke-WebRequest cmdlet to send a web request to the Bing.com site.

The first command issues the request and saves the response in the $r variable.

The second command gets the InnerHtml property when it includes an equal sign, sorts the inner HTML by length and selects the 5 shortest values. Sorting by the shortest HTML value often helps you find the most specific element that matches that text.


PS C:\> $r = Invoke-WebRequest -URI http://www.bing.com?q=how+many+feet+in+a+mile
PS C:\>$r.AllElements | where {$_.innerhtml -like "*=*"} | Sort { $_.InnerHtml.Length } | Select InnerText -First 5
innerText---------1 =5280 feet1 mile

Example 2

This example shows how to use the Invoke-WebRequest cmdlet with a stateful web service, such as Facebook.


 

The first command uses the Invoke-WebRequest cmdlet to send a sign-in request. The command specifies a value of "fb" for the value of the SessionVariable parameter, and saves the result in the $r variable.

When the command completes, the $r variable contains an HtmlWebResponseObject and the $fb variable contains a WebRequestSession object.


PS C:\> $r=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb

 

The second command shows the WebRequestSession object in the $fb variable.


PS C:\> $fb

 

The third command gets the first form in the Forms property of the HTTP response object in the $r variable, and saves it in the $form variable.


PS C:\> $form = $r.Forms[0]

 

The fourth command pipes the properties of the form in the $form variable into a list by using the Format-List cmdlet.


PS C:\> $form | Format-List

 

The fifth command displays the keys and values in the hash table (dictionary) object in the Fields property of the form.


PS C:\> $form.fields

 

The sixth and seventh commands populate the values of the "email" and "pass" keys of the hash table in the Fields property of the form. You can replace the email and password with values that you want to use.


PS C:\> $form.Fields["email"]="User01@Fabrikam.com"
$form.Fields["pass"]="P@ssw0rd"

 

The eighth command uses the Invoke-WebRequest cmdlet to sign into the Facebook web service.

The value of the Uri parameter is the value of the Action property of the form. The WebRequestSession object in the $fb variable (the session variable specified in the first command) is now the value of the WebSession parameter. The value of the Body parameter is the hash table in the Fields property of the form and the value of the Method parameter is POST. The command saves the output in the $r variable.


PS C:\> $r=Invoke-WebRequest -Uri ("https://www.facebook.com" + $form.Action) -WebSession $fb -Method POST -Body $form.Fields

 

The full script, then, is as follows.


PS C:\> # Sends a sign-in request by running the Invoke-WebRequest cmdlet. The command specifies a value of "fb" for the SessionVariable parameter, and saves the results in the $r variable.

$r=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb

# Use the session variable that you created in Example 1. Output displays values for Headers, Cookies, Credentials, etc. 

$fb

# Gets the first form in the Forms property of the HTTP response object in the $r variable, and saves it in the $form variable. 

$form = $r.Forms[0]

# Pipes the form properties that are stored in the $forms variable into the Format-List cmdlet, to display those properties in a list. 

$form | Format-List

# Displays the keys and values in the hash table (dictionary) object in the Fields property of the form.

$form.fields

# The next two commands populate the values of the "email" and "pass" keys of the hash table in the Fields property of the form. Of course, you can replace the email and password with values that you want to use. 

$form.Fields["email"] = "User01@Fabrikam.com"
$form.Fields["pass"] = "P@ssw0rd"

# The final command uses the Invoke-WebRequest cmdlet to sign in to the Facebook web service. 

$r=Invoke-WebRequest -Uri ("https://www.facebook.com" + $form.Action) -WebSession $fb -Method POST -Body $form.Fields

 

When the command finishes, the StatusDescription property of the web response object in the $r variable indicates that the user is signed in successfully.


PS C:\> $r.StatusDescription

Example 3

This command gets the links in a web page. It uses the Invoke-WebRequest cmdlet to get the web page content. Then it users the Links property of the HtmlWebResponseObject that Invoke-WebRequest returns, and the Href property of each link.


PS C:\> (Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx").Links.Href

Related topics



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.