This article is contributed. See the original author and article here.

`Invoke-AzRestMethod` is a new Azure PowerShell cmdlet. It allows you to make custom HTTP requests to the Azure Resource Management (ARM) endpoint using the Az context.

This cmdlet is useful when you want to manage Azure services for features that aren’t yet available in the Az PowerShell modules.

 

How to use Invoke-AzRestMethod?

As an example, you can allow access to Azure Container Registry (ACR) only for specific networks or deny public access. This feature isn’t available yet in the Az.ContainerRegistry PowerShell module. However, it can be managed in the interim with `Invoke-AzRestMethod`.

We want to disable public access to the existing ACR named `ameacr` in the `amedemo` resource group. Let’s start by understanding how the cmdlet works with a GET operation:

 

Invoke-AzRestMethod
-ResourceGroupName “amedemo”
-ResourceProviderName "Microsoft.ContainerRegistry"
-ResourceType “registries”
-Name “ameacr”
-ApiVersion 2019-12-01-preview
-Method GET

Invoke-AzRest-GET.png

To allow maximum flexibility, most of the parameters are optional. However, when you’re managing resources within a resource group, you’ll most likely need to provide either the full ID to the resource or parameters like resource group, resource provider and resource type.

The ‘ResourceType‘ and ‘Name‘ parameters can take multiple values when targeting resources that require more than one name. For example, to manipulate a saved search in a Log Analytics workspace, the parameters look like the following:

‘-ResourceType @(‘workspaces’, ‘savedsearches’) -Name @(‘ame-la’, ‘ame-search’)’

Using a mapping based on the position in the array, the cmdlet constructs the following resource Id:‘/workspaces/yabo-test-la/savedsearches/ame-search’.

 

The ‘APIVersion’ parameter allows you to use a specific API, including preview ones as it is the case here. The supported API versions for Azure Resource providers can be found in the following repository: https://github.com/Azure/azure-rest-api-specs

 

You can find the definition for the 2019-12-01-preview version of ACR at the following location: https://github.com/Azure/azure-rest-api-specs/tree/master/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview

To disable the public network access, we need to make a PATCH call to the API that changes the value of the “publicNetwokAccess” parameter:

Invoke-AzRestMethod
-ResourceGroupName amedemo
-Name "ameacr"
-ResourceProviderName "Microsoft.ContainerRegistry"
-ResourceType "registries"
-ApiVersion 2019-12-01-preview
-Payload '{ "properties": {
"publicNetworkAccess": "Disabled"
} }'
-Method PATCH

The Payload property is a JSON string that shows the path of the property to be modified.

 

Invoke-AzRest-PATCH.png

All the parameters for this API are described in the rest-api-spec file associated with this API. More specifically, the definition for the publicNetworkAccess parameter can be found in the following JSON file: https://github.com/Azure/azure-rest-api-specs/blob/2a9da9a79d0a7b74089567ec4f0289f3e0f31bec/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/2019-12-01-preview/containerregistry.json

 

To only allow access to the registry from a specific IP address, the payload needs to be adjusted as follows:

Invoke-AzRestMethod
-ResourceGroupName amedemo
-Name "ameacr"
-ResourceProviderName "Microsoft.ContainerRegistry"
-ResourceType "registries"
-ApiVersion 2019-12-01-preview
-Payload '{ "properties": {
"networkRuleSet": {
"defaultAction": "Deny",
"ipRules": [ {
"action": "Allow",
"value": "24.22.123.123"
} ]
}
} }'
-Method PATCH

 

Invoke-AzRest-PATCH-CustomIP.png

 

How does this compare to the (New|Get|Set)-AzResource?

 

The *-AzResource cmdlets allow you to customize the REST API call to Azure by specifying the resource type, the API version, and the properties to be updated. However, the properties need to be a PSObject which can easily become complicated to create.

With `Invoke-AzRestMethod`, we wanted to offer a simpler way to manage Azure resources. In the previous example, you can see that the payload is a JSON string. You don’t have to struggle with the conversion between JSON and PSObjects.

If you’re already familiar with the *-AzResource cmdlets, you can continue using them. We have no plans to stop supporting them. With `Invoke-AzRestMethod`, we have added a new cmdlet to the family.

 

Feedback

As always, we value your feedback and welcome issues and contributions on our GitHub repo: https://github.com/Azure/azure-powershell

We’re also conducting a survey until August 15th about the PowerShell modules for Azure. Please take some time to provide your feedback on how we’re doing, it shapes our strategy: 

https://microsoft.qualtrics.com/jfe/form/SV_bK37YHU5FBZepcF?Q_CHL=blog 

 

 

 

Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.