Invoke-RestMethod

Send an HTTP or HTTPS request to a RESTful web service.

Syntax
      Invoke-RestMethod [-Uri] Uri [-Body Object] [-Certificate X509Certificate] [-CertificateThumbprint String] 
         [-ContentType String] [-Credential PSCredential] [-DisableKeepAlive] [-Headers IDictionary]
            [-InFile String] [-MaximumRedirection Int32]
               [-Method {Default | Get | Head | Post | Put | Delete | Trace | Options | Merge | Patch}]
                  [-OutFile String] [-PassThru] [-Proxy Uri] [-ProxyCredential PSCredential] 
                     [-ProxyUseDefaultCredentials] [-SessionVariable String] [-TimeoutSec Int32]
                        [-TransferEncoding {chunked | compress | deflate | gzip | identity}]
                           [-UseBasicParsing] [-UseDefaultCredentials] [-UserAgent String] 
                              [-WebSession WebRequestSession] [CommonParameters]


Key
   -Body Object
       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 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, 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]`

   -Certificate X509Certificate
       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.
        
   -CertificateThumbprint String
       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.
       
   -ContentType String
       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 is not specified in the call.
        
   -Credential PSCredential
       A user account that has permission to send the request. The default is the current user.
        
       Type a user name, such as User64 or ss64Dom\User64, or enter a PSCredential object, such as one generated by 
       the Get-Credential cmdlet.
        
   -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.
        
   -Headers IDictionary
       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.
        
   -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.
        
   -MaximumRedirection Int32
       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.
       
   -Method WebRequestMethod
       The method used for the web request. The acceptable values for this parameter are:
        
        - Default
        - Delete
        - Get
        - Head
        - Merge
        - Options
        - Patch
        - Post
        - Put
        - Trace
        
   -OutFile String
       The output file for which this cmdlet saves the response body. 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.
        
   -PassThru
       Indicates that the cmdlet 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.

   -Proxy Uri
       A proxy server for the request, rather than connecting directly to the Internet resource. Enter the 
       URI of a network proxy server.
        
   -ProxyCredential PSCredential
       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.
        
   -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 cannot use the 
       ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
        
   -SessionVariable String
       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 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.
      
   -TimeoutSec Int32
       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.
        
   -TransferEncoding String
       A value for the transfer-encoding HTTP response header. The acceptable values for this parameter are:
        - Chunked
        - Compress
        - Deflate
        - GZip
        - Identity

   -Uri Uri
       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.
        
   -UseBasicParsing
       Indicates that the cmdlet uses basic parsing.
       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 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 is the output of another Invoke-WebRequest call, 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]`
        
   -UseDefaultCredentials
       Indicates that the cmdet uses the credentials of the current user to send the web request.
        
   -UserAgent String
       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)`
        
   -WebSession WebRequestSession
       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-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 cannot use the SessionVariable and WebSession parameters in the same command.

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, Windows 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 was introduced in PowerShell 3.0.

Standard Aliases for Invoke-RestMethod: irm

Examples

Parse the output of a Bing query result:

PS C:\> $R = Invoke-WebRequest -URI https://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

This command uses Invoke-WebRequest to send a web request to Bing.com. 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.

Get links from a web page:

PS C:\> (Invoke-WebRequest -Uri "https://ss64.com/nt/").Links.Href

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

Download a zip file:

$link = 'https://download.sysinternals.com/files/PSTools.zip'
$dest = 'C:\downloads\PSTools.zip'
Invoke-RestMethod -Uri $link -OutFile $dest -UseBasicParsing
Unblock-File -Path $dest

Retrieve a specific command page from ss64.com/ps, and then display the quotation by selecting the CSS class 'quote':

Function Get-SS64Quote {
    Param([string]$command)
    $ExThrown = $False
    $command = $command.ToLower()
    Try {$GetUrl = Invoke-WebRequest -uri ss64.com/ps/$command.html}
    Catch {$ExThrown = $True}
    Finally {
        If ($ExThrown -eq $False) {
            $Quote = $GetUrl.AllElements | Where-Object { $_.Class -eq 'quote' } | Select-Object innertext
            Write-Host $Quote.innerText
        }
    }
}

(via Reddit/PowerShell)

“I think that I've learned to relax, and trust in and hire very talented people, and trust in their abilities a little more” ~ Mark Romanek

Related PowerShell Cmdlets

ConvertTo-Json – Convert an object to a JSON-formatted string.
invoke-webrequest – Get content from a web page on the Internet.
New-WebServiceProxy – Create a Web service proxy object.


 
Copyright © 1999-2024 SS64.com
Some rights reserved