Invoke-RestMethod
Sends an HTTP or HTTPS request to a RESTful web service.
Syntax
StandardMethod (Default)
Invoke-RestMethod
[-Uri] <Uri>
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <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]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
StandardMethodNoProxy
Invoke-RestMethod
[-Uri] <Uri>
-NoProxy
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <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>]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
CustomMethod
Invoke-RestMethod
[-Uri] <Uri>
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <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]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
CustomMethodNoProxy
Invoke-RestMethod
[-Uri] <Uri>
-CustomMethod <String>
-NoProxy
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <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>]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Description
The Invoke-RestMethod cmdlet sends HTTP and HTTPS requests to Representational State Transfer
(REST) web services that return richly structured data.
PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or deserializes, the content into objects.
This cmdlet is introduced in Windows PowerShell 3.0.
Parameters
-AllowUnencryptedAuthentication
Allows sending of credentials and secrets over unencrypted connections. By default, supplying
Credential or any Authentication option with a Uri that does not begin with https://
will result in an error and the request will abort to prevent unintentionally communicating secrets
in plain text over unencrypted connections. To override this behavior at your own risk, supply the
AllowUnencryptedAuthentication parameter.
Warning
Using this parameter is not secure and is not recommended. It is provided only for compatibility with legacy systems that cannot provide encrypted connections. Use at your own risk.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Authentication
Specifies the explicit authentication type to use for the request. The default is None. Authentication can't be used with UseDefaultCredentials.
Available Authentication Options:
- None: This is the default option when Authentication is not supplied. No explicit authentication will be used.
- Basic: Requires Credential. The credentials will be used to send an RFC 7617 Basic
Authentication
Authorization: Basicheader in the format ofbase64(user:password). - Bearer: Requires Token. Will send and RFC 6750
Authorization: Bearerheader with the supplied token. This is an alias for OAuth - OAuth: Requires Token. Will send an RFC 6750
Authorization: Bearerheader with the supplied token. This is an alias for Bearer
Supplying Authentication will override any Authorization headers supplied to Headers or
included in WebSession.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | WebAuthenticationType |
| Default value: | None |
| Accepted values: | None, Basic, Bearer, OAuth |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Body
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-RestMethod.
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 Uniform Resource Identifier (URI) as query parameters. For other request types
(such as POST), 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's the output of another Invoke-WebRequest call, PowerShell sets the
request content to the form fields.
The Body parameter may also accept a System.Net.Http.MultipartFormDataContent object. This
will facilitate multipart/form-data requests. When a MultipartFormDataContent object is
supplied for Body, any content related headers supplied to the ContentType, Headers, or
WebSession parameters will be overridden by the content headers of the
MultipartFormDataContent object. This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | Object |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Certificate
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 isn't valid or doesn't have sufficient authority, the command
fails.
Parameter properties
| Type: | X509Certificate |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-CertificateThumbprint
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 PowerShell
Cert: drive.
Note
This feature is currently only supported on Windows OS platforms.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ContentType
Specifies the content type of the web request.
If this parameter is omitted and the request method is POST, Invoke-RestMethod sets the content
type to application/x-www-form-urlencoded. Otherwise, the content type isn't specified in the
call.
ContentType will be overridden when a MultipartFormDataContent object is supplied for
Body.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Credential
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
generated by the Get-Credential cmdlet.
Credential can be used alone or in conjunction with certain Authentication parameter options. When used alone, it will only supply credentials to the remote server if the remote server sends an authentication challenge request. When used with Authentication options, the credentials will be explicitly sent.
Credentials are stored in a PSCredential object and the password is stored as a SecureString.
Note
For more information about SecureString data protection, see How secure is SecureString?.
Parameter properties
| Type: | PSCredential |
| Default value: | Current user |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-CustomMethod
Specifies custom method used for the web request. This can be used with the Request Method required by the endpoint is not an available option on the Method. Method and CustomMethod cannot be used together.
Example:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
This makes a TEST HTTP request to the API.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | CM |
Parameter sets
CustomMethodNoProxy
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CustomMethod
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DisableKeepAlive
Indicates that the cmdlet 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-FollowRelLink
Indicates the cmdlet should follow relation links.
Some REST APIs support pagination via Relation Links per RFC5988. Instead of parsing the header to get the URL for the next page, you can have the cmdlet do this for you. To set how many times to follow relation links, use the MaximumFollowRelLink parameter.
When using this switch, the cmdlet returns a collection of pages of results. Each page of results may contain multiple result items.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | FL |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Form
Converts a dictionary to a multipart/form-data submission. Form may not be used with Body.
If ContentType will be ignored.
The keys of the dictionary will be used as the form field names. By default, form values will be converted to string values.
If the value is a System.IO.FileInfo object, then the binary file contents will be submitted.
The name of the file will be submitted as the filename. The MIME will be set as
application/octet-stream. Get-Item can be used to simplify supplying the System.IO.FileInfo
object.
$Form = @{
resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf'
}
If the value is a collection type, such as an Array or List, the for field will be submitted multiple times. The values of the list will be treated as strings by default. If the value is a System.IO.FileInfo object, then the binary file contents will be submitted. Nested collections aren't supported.
$Form = @{
tags = 'Vacation', 'Italy', '2017'
pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy\'
}
In the above example, the tags field will be supplied three times in the form, once for each of
Vacation, Italy, and 2017. The pictures field will also be submitted once for each file in
the 2017-Italy folder. The binary contents of the files in that folder will be submitted as the
values.
This feature was added in PowerShell 6.1.0.
Parameter properties
| Type: | IDictionary |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Headers
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
User-Agent or cookie headers.
Content related headers, such as Content-Type will be overridden when a MultipartFormDataContent
object is supplied for Body.
Parameter properties
| Type: | IDictionary |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-InFile
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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumFollowRelLink
Specifies how many times to follow relation links if FollowRelLink is used. A smaller value may
be needed if the REST api throttles due to too many requests. The default value is
[Int32]::MaxValue. A value of 0 (zero) prevents following relation links.
Parameter properties
| Type: | Int32 |
| Default value: | Int32.MaxValue |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | ML |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumRedirection
Specifies how many times 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.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumRetryCount
Specifies how many times PowerShell retries a connection when a failure code between 400 and 599, inclusive or 304 is received. Also see RetryIntervalSec parameter for specifying number of retries.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Method
Specifies the method used for the web request. The acceptable values for this parameter are:
- Default
- Delete
- Get
- Head
- Merge
- Options
- Patch
- Post
- Put
- Trace
The CustomMethod parameter can be used for Request Methods not listed above.
Parameter properties
| Type: | WebRequestMethod |
| Default value: | None |
| Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
StandardMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
StandardMethodNoProxy
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-NoProxy
Indicates that the cmdlet will not use a proxy to reach the destination.
When you need to bypass the proxy configured in Internet Explorer, or a proxy specified in the environment, use this switch.
This parameter was introduced in PowerShell 6.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
StandardMethodNoProxy
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CustomMethodNoProxy
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-OutFile
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-RestMethod returns the results to the pipeline. To send the results to a file
and to the pipeline, use the Passthru parameter.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | No output |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-PreserveAuthorizationOnRedirect
Indicates the cmdlet should preserve the Authorization header, when present, across redirections.
By default, the cmdlet strips the Authorization header before redirecting. Specifying this
parameter disables this logic for cases where the header needs to be sent to the redirection
location.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Proxy
Uses a proxy server for the request, rather than connecting directly to the internet resource. Enter the Uniform Resource Identifier (URI) of a network proxy server.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | Uri |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
StandardMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CustomMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ProxyCredential
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, User@Domain.Com, 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 can't use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
Parameter properties
| Type: | PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
StandardMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CustomMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ProxyUseDefaultCredentials
Indicates that the cmdlet 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 can't use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
StandardMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CustomMethod
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ResponseHeadersVariable
Creates a Response Headers Dictionary and saves it in the value of the specified variable. The keys of the dictionary will contain the field names of the Response Header returned by the web server and the values will be the respective field values.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | RHV |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Resume
Performs a best effort attempt to resume downloading a partial file. The Resume parameter requires the OutFile parameter.
Resume only operates on the size of the local file and remote file and performs no other validation that the local file and the remote file are the same.
If the local file size is smaller than the remote file size, then the cmdlet will attempt to resume downloading the file and append the remaining bytes to the end of the file.
If the local file size is the same as the remote file size, then no action is taken and the cmdlet assumes the download already completed.
If the local file size is larger than the remote file size, then the local file will be overwritten and the entire remote file will be completely re-downloaded. This behavior is the same as using OutFile without Resume.
If the remote server does not support download resuming, then the local file will be overwritten and the entire remote file will be completely re-downloaded. This behavior is the same as using OutFile without Resume.
If the local file doesn't exist, then the local file will be created and the entire remote file will be completely downloaded. This behavior is the same as using OutFile without Resume.
This feature was added in PowerShell 6.1.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RetryIntervalSec
Specifies the interval between retries for the connection when a failure code between 400 and 599, inclusive or 304 is received. Also see MaximumRetryCount parameter for specifying number of retries.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SessionVariable
Specifies a variable for which this cmdlet creates a web request session and saves it in the value.
Enter a variable name without the dollar sign ($) symbol.
When you specify a session variable, Invoke-RestMethod creates a web request session object and
assigns it to a variable with the specified name in your PowerShell session. You can use the
variable in your session as soon as the command completes.
Unlike a remote session, the web request session isn't a persistent connection. It's 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. 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 can't use the SessionVariable and WebSession parameters in the same command.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | SV |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SkipCertificateCheck
Skips certificate validation checks that include all validations such as expiration, revocation, trusted root authority, etc.
Warning
Using this parameter is not secure and is not recommended. This switch is only intended to be used against known hosts using a self-signed certificate for testing purposes. Use at your own risk.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SkipHeaderValidation
Indicates the cmdlet should add headers to the request without validation.
This switch should be used for sites that require header values that do not conform to standards. Specifying this switch disables validation to allow the value to be passed unchecked. When specified, all headers are added without validation.
This will disable validation for values passed to the ContentType, Headers, and UserAgent parameters.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SslProtocol
Sets the SSL/TLS protocols that are permissible for the web request. By default all, SSL/TLS protocols supported by the system are allowed. SslProtocol allows for limiting to specific protocols for compliance purposes.
SslProtocol uses the WebSslProtocol Flag Enum. It is possible to supply more than one protocol
using flag notation or combining multiple WebSslProtocol options with -bor, however supplying
multiple protocols is not supported on all platforms.
Note
On non-Windows platforms it may not be possible to supply 'Tls, Tls12' as an option.
This feature was added in PowerShell 6.0.0.
Parameter properties
| Type: | WebSslProtocol |
| Default value: | None |
| Accepted values: | Default, Tls, Tls11, Tls12 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TimeoutSec
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.
A Domain Name System (DNS) query can take up to 15 seconds to return or time out. If your request contains a host name that requires resolution, and you set TimeoutSec to a value greater than zero, but less than 15 seconds, it can take 15 seconds or more before a WebException is thrown, and your request times out.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Token
The OAuth or Bearer token to include in the request. Token is required by certain Authentication options. It can't be used independently.
Token takes a SecureString that contains the token. To supply the token, manually use the
following:
Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
This parameter was introduced in PowerShell 6.0.
Parameter properties
| Type: | SecureString |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TransferEncoding
Specifies a value for the transfer-encoding HTTP response header. The acceptable values for this parameter are:
- Chunked
- Compress
- Deflate
- GZip
- Identity
Parameter properties
| Type: | String |
| Default value: | None |
| Accepted values: | chunked, compress, deflate, gzip, identity |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Uri
Specifies the Uniform Resource Identifier (URI) of the internet resource to which the web request is sent. This parameter supports HTTP, HTTPS, FTP, and FILE values.
This parameter is required. The parameter name (Uri) is optional.
Parameter properties
| Type: | Uri |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UseBasicParsing
This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic parsing only. This parameter is included for backwards compatibility only and any use of it will have no effect on the operation of the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UseDefaultCredentials
Indicates that the cmdlet uses the credentials of the current user to send the web request. This can't be used with Authentication or Credential and may not be supported on all platforms.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UserAgent
Specifies a user agent string for the web request.
The default user agent is similar to
Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WebSession
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. Content
related headers, such as Content-Type, will be also be overridden when a
MultipartFormDataContent object is supplied for Body.
Unlike a remote session, the web request session isn't a persistent connection. It's 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-RestMethod command. Invoke-RestMethod creates the
session and saves it in the variable. In subsequent commands, use the variable as the value of the
WebSession parameter.
You can't use the SessionVariable and WebSession parameters in the same command.
Parameter properties
| Type: | WebRequestSession |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
Object
You can pipe the body of a web request to Invoke-RestMethod.
Outputs
System.Int64, System.String, System.Xml.XmlDocument
The output of the cmdlet depends upon the format of the content that is retrieved.
PSObject
If the request returns JSON strings, Invoke-RestMethod returns a PSObject that represents the
strings.
Notes
Some features may not be available on all platforms.
For more information about how .NET provides proxy services to PowerShell, see Accessing the Internet Through a Proxy.