Edit

Invoke-AzRestMethod

Send an authenticated REST request to Azure Resource Manager and return the raw response.

Syntax

Default (Default)

Invoke-AzRestMethod
    [-Method <string>]
    [-Uri <string>]
    [-Payload <string>]
    [-Headers <Object>]
    [-SubscriptionId <string>]
    [-ResourceGroupName <string>]
    [-ResourceProviderName <string>]
    [-ResourceType <string[]>]
    [-Name <string[]>]
    [-ApiVersion <string>]
    [-UriParameters <Object>]
    [-Profile <string>]
    [<CommonParameters>]

Description

Invoke-AzRestMethod is a universal authenticated ARM REST passthrough, mirroring az rest and Invoke-AzRestMethod. It sends an arbitrary HTTP request through the already-authenticated AzClips pipeline to Azure Resource Manager and returns the raw response: the HTTP status code, the response headers, and the response body. When the response body is JSON, a parsed Json representation is also returned alongside the raw content.

The target URL can be supplied two ways. In Uri mode, pass -Uri with an absolute ARM URL or a relative ARM path (relative paths are prefixed with https://management.azure.com, and the token {subscriptionId} is replaced with the current subscription). In ByParameters mode, build the URL piece-wise from -SubscriptionId, -ResourceGroupName, -ResourceProviderName, -ResourceType, -Name, and -ApiVersion. The two modes are mutually exclusive.

This cmdlet performs no long-running-operation polling and no automatic pagination, and it targets the Azure Resource Manager audience only. Use it to call ARM endpoints that do not yet have a dedicated cmdlet.

Examples

Example 1: List resource groups in a subscription (Uri mode)

Send a GET to an absolute ARM path and read the parsed JSON from the response.

Invoke-AzRestMethod -Method GET -Uri "/subscriptions/{subscriptionId}/resourcegroups?api-version=2021-04-01"

Example 2: Get a resource group built from parameters (ByParameters mode)

Build the ARM URL piece-wise instead of passing a full URI. The default method is GET.

Invoke-AzRestMethod -ResourceGroupName myRg -ApiVersion 2021-04-01

Example 3: Create or update a resource group with a JSON payload

Send a PUT with a request body and a custom header.

Invoke-AzRestMethod -Method PUT -Uri "/subscriptions/{subscriptionId}/resourcegroups/myRg?api-version=2021-04-01" -Payload '{"location":"eastus"}' -Headers @{ 'Content-Type' = 'application/json' }

Parameters

-ApiVersion

The api-version used when building an ARM URL from piece-wise parameters. Required in ByParameters mode. Mutually exclusive with -Uri.

Parameter properties

Type:String
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

Optional request headers, supplied either as a hashtable (@{ 'Accept' = 'application/json' }) or as a string array in KEY=VALUE form ('Accept=application/json').

Parameter properties

Type:Object
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

The HTTP method to use (GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS). Defaults to GET.

Parameter properties

Type:String
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

-Name

Resource name segments, interleaved with -ResourceType (may have one fewer entry than -ResourceType for a collection GET). Used to build an ARM URL from piece-wise parameters. Mutually exclusive with -Uri.

Parameter properties

Type:

String[]

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

-Payload

Optional request body (typically JSON). Sent whenever provided, for any HTTP method.

Parameter properties

Type:String
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

-Profile

Use the named profile for this command, overriding the active profile.

Parameter properties

Type:String
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

-ResourceGroupName

Resource group name segment used to build an ARM URL from piece-wise parameters. Mutually exclusive with -Uri.

Parameter properties

Type:String
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

-ResourceProviderName

Resource provider namespace (for example, Microsoft.Resources) used to build an ARM URL from piece-wise parameters. Mutually exclusive with -Uri.

Parameter properties

Type:String
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

-ResourceType

Resource type segments, interleaved with -Name, used to build an ARM URL from piece-wise parameters. Mutually exclusive with -Uri.

Parameter properties

Type:

String[]

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

-SubscriptionId

Subscription id used to build an ARM URL from piece-wise parameters. Defaults to the current subscription. Mutually exclusive with -Uri.

Parameter properties

Type:String
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

Absolute URL or relative ARM path for the request. Relative paths are prefixed with https://management.azure.com, and the token {subscriptionId} is replaced with the current subscription. Mutually exclusive with the piece-wise ByParameters inputs (-SubscriptionId, -ResourceGroupName, -ResourceProviderName, -ResourceType, -Name, -ApiVersion).

Parameter properties

Type:String
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

-UriParameters

Optional query-string parameters, supplied either as a hashtable (@{ '$top' = '3' }) or as a string array in KEY=VALUE form ('$top=3'). Appended to the final URL in either mode.

Parameter properties

Type:Object
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.

Outputs

Microsoft.Azure.Azclips.Extensions.Resources.Models.RestResponse

A RestResponse object containing the HTTP status code, response headers, parsed JSON body (when applicable), and raw body text.

Notes

This cmdlet targets the Azure Resource Manager audience only. It does not poll long-running operations and does not page through nextLink results; for paged endpoints, follow the returned nextLink yourself with another call.