Introduction to Invoke-WebRequest in PowerShell

Invoke-WebRequest is a powerful cmdlet in PowerShell that allows you to interact with web servers and APIs. It provides an easy way to make web requests and get responses in PowerShell without needing additional libraries or modules.

In this comprehensive guide, we will cover everything you need to know about using Invoke-WebRequest.

What is Invoke-WebRequest?

Invoke-WebRequest sends HTTP and HTTPS requests to a web page or web service and gets back a response. It allows you to interact with APIs, download files, submit data to web servers, authenticate with credentials, and more.

The cmdlet handles all the details of making web requests behind the scenes using the .NET Framework – you just need to provide the URL. The response comes back as an object with properties like status code, returned content, headers, images, links and more, making it easy to parse and work with programmatically.

Why Use Invoke-WebRequest?

Here are some of the key reasons to use Invoke-WebRequest:

• No external libraries/modules needed – it‘s built into PowerShell already
• Easy to make web requests without dealing with all the plumbing code
• Returns a rich object with status, content, headers etc instead of just raw text
• Supports HTTP basic authentication for APIs requiring logins
• Certificate authentication support for HTTPS sites
• Flexible parameters to customize requests and handle responses
• Perfect for interacting with REST APIs and webhooks from your scripts

Overall it provides a simple way to get data from web services without needing to use externals libraries or write boilerplate web client code.

Making Web Requests

The most basic Invoke-WebRequest usage is to provide a URL. This will make a GET request to the webpage and return an object with the response:

$Response = Invoke-WebRequest -Uri "https://www.example.com"

The $Response object will contain properties like:

• StatusCode – HTTP status code
• StatusDescription
• Content – The HTML content
• RawContent – The full response body
• Headers – Response headers
• Images/Links/Forms – Parsed representations of these elements

Many times the content is the most interesting part. You can access it directly:

$content = $Response.Content

Or convert it to a string:

$stringContent = [string]$Response.Content

You can then parse this content using PowerShell‘s built-in string and processing capabilities.

Customizing Requests

Invoke-WebRequest has a lot of parameters for customizing your web requests. Here some useful ones:

Method – The HTTP method verb:

Invoke-WebRequest -Uri "https://api.example.com/data" -Method POST

Body – For POST/PUT requests, provide a request body:

$Body = @{
    username = "user" 
    password = "P@ssword"
}

Invoke-WebRequest -Uri "https://api.example.com/login" -Method POST -Body ($Body | ConvertTo-Json)

Headers – Add custom headers like API keys:

$Headers = @{
    "Authorization" = "Bearer YOUR_API_TOKEN" 
}

Invoke-WebRequest -Uri "https://api.example.com/data" -Headers $Headers

OutFile – Save response directly to a file:

Invoke-WebRequest -Uri "https://files.example.com/report.pdf" -OutFile "C:\Reports\report.pdf"

There are many other parameters available – review them to construct advanced customized requests.

Handling Responses

When making requests, you also need to handle the responses appropriately:

Check Status Codes

Always check the StatusCode first:

$Response = Invoke-WebRequest -Uri "https://api.example.com/data"

if($Response.StatusCode -ne 200){
    Write-Host "Error requesting data: $($Response.StatusCode)" 
    return
}

This makes sure you got a successful response before working with the content.

Handling Errors

Wrap Invoke-WebRequest in try/catch to handle issues:

try {

    $Response = Invoke-WebRequest -Uri "https://api.example.com/data"  

} catch {

    Write-Host "Error making web request: $_"

}

Now you can handle cases like the server being unavailable etc.

Parse Content

Use properties like Content, Images, Links or construct custom parsing with cmdlets like ConvertFrom-Json, ConvertFrom-Csv or string manipulation on RawContent/Content to extract info you need from the response.

Common Usage Examples

Now that we have covered the basics, here are some common use cases and examples for using Invoke-WebRequest in scripts and daily tasks:

Working with REST APIs

# Get auth token
$AuthResponse = Invoke-WebRequest -Uri "https://api.server.com/token" -Method POST -Body $AuthBody
$Token = ($AuthResponse | ConvertFrom-Json).access_token

# Call API
$Headers = @{
    "Authorization" = "Bearer $Token"
}
$ApiResponse = Invoke-WebRequest -Uri "https://api.server.com/users" -Headers $Headers

$Json = ($ApiResponse | ConvertFrom-Json)
$Json.users

This allows easy integration with any REST API.

Downloading Files

# Download from URI directly to file
Invoke-WebRequest -Uri "https://files.server.com/reports/reportA.xlsx" -OutFile "C:\Reports\reportA.xlsx"

# Download to file path 
$Response = Invoke-WebRequest -Uri "https://files.server.com/reports/reportB PDF"
$FileContent = $Response.Content
$FileContent | Set-Content -Path "C:\Reports\reportB.pdf" -Encoding byte -Stream

Submitting Web Forms

$Form = @{
    "username" = "user123"
    "password" = "Test@123"
    "login" = "Sign In"
}

$Response = Invoke-WebRequest -Uri "https://www.mysite.com/login" -Method Post -Body $Form 

# Check if login succeded
if ($Response.StatusCode -eq 200 -and $Response.Content -like "*Welcome User123*") {
    Write-Host "Login successful"
} else {
    Write-Host "Invalid login" 
}

Checking Websites

$Response = Invoke-WebRequest -Uri "http://www.mywebsite.com"

if ($Response.StatusCode -eq 200) {
    Write-Host "Website OK"  
} 
else {
    Write-Host "Website Down: $($Response.StatusCode)"
}

This pings a website and checks if it is up.

Interacting with Webhooks/APIs

$Body = @{
    "event" = "order_completed"
    "data" = $OrderObject
} | ConvertTo-Json

Invoke-WebRequest -Method POST -Body $Body -Uri "https://api.acme.com/hooks/neworder"

Easily call external webhooks or APIs from your scripts.

Advanced Techniques

Invoke-WebRequest provides easy web interactions but also supports more advanced scenarios:

HTTP Authentication

Pass usernames/passwords for basic authentication:

$Credential = Get-Credential

Invoke-WebRequest -Uri "https://api.example.com/data" -Authentication Basic -Credential $Credential

Or use API keys:

$Headers = @{
    "Authorization" = "Bearer YOUR_API_KEY"
}

Invoke-WebRequest -Uri "https://api.example.com/data" -Headers $Headers 

Handling Redirects

By default redirects are not followed:

$Response = Invoke-WebRequest -Uri "http://bit.ly/2m0jGSf" 

Write-Host $Response.StatusCode # Prints 301

To follow redirects automatically use:

Invoke-WebRequest -Uri "http://bit.ly/2m0jGSf" -MaximumRedirection 5 -UseBasicParsing

Now you will land on final URL instead of the redirect.

Specifying User Agent

Spoof or customize user agent like:

Invoke-WebRequest -Uri "https://www.example.com" -UserAgent "Mozilla/5.0 (iPad; U; CPU OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) ...."

Helps mimic browsers or certain devices.

Handling Secure Certificates

Specify certificate thumbprints or disable SSL certificate checks for insecure self-signed certificates on secure websites:

Invoke-WebRequest -Uri "https://self-signed.badssl.com/" -SkipCertificateCheck

# or specify certificate

$Cert = Get-ChildItem -Path Cert:\LocalMachine\My 

Invoke-WebRequest -Uri "https://self-signed.badssl.com/" -Certificate $Cert 

This helps securely interact with websites using custom SSL certificates

Summary

To recap:

• Invoke-WebRequest sends HTTP/HTTPS requests and returns rich response objects
• Easy way to interact with web APIs, submit forms, download files etc from PowerShell
• Customize requests with headers, authentication, body and other parameters
• Flexibly handle response status, errors, redirects, content
• Saves time over coding manual web requests and using external libraries
• Perfect command for handling web interactions in automated scripts

Hopefully this guide gave you a comprehensive overview of everything needed to fully utilize the Invoke-WebRequest cmdlet within your PowerShell code!