Using az rest

Introduction

The easiest way to test REST API calls is with the Azure CLI’s az rest command. The command simplifies the access token and also substitutes {subscriptionId}.

Here are the steps to read a resource group, delete it, recreate it and then update the tags.

Pre-reqs

The lab starts with an empty resource group.

1. Log in using az login

2. Check context using az account show

   You can switch context using az account set.

3. Create a resource group

   az group create --name "myResourceGroup" --location "West Europe"
   

   Use a different resource group name if that already exists in your subscription.

Token

There is no need to get the token with the az rest command.

1. Authenticate with az login
2. Check context with az account show

The CLI will cache the token in ~/.azure/msal_token_cache.json.

You can also display the token with az account get-access-token --query accessToken.

The token is a standard JSON web token. Paste the value into https://jwt.ms to view the claims.

See az login --help for examples if authenticating as a service principal or managed identity.

Get

Another benefit of the az rest command is that {subscriptionId} in all of the references will be replace by the value of az account show --query id.

1. View the Resource Groups - Get documentation

   See the example:

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}?api-version=2021-04-01
   

2. Use az rest to get

   Note that if method is not specified then az rest defaults to GET.

   az rest --uri https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01
   

   Example output:

   {
     "id": "/subscriptions/2d31be49-d959-4415-bb65-8aec2c90ba62/resourceGroups/myResourceGroup",
     "location": "westeurope",
     "name": "myResourceGroup",
     "properties": {
       "provisioningState": "Succeeded"
     },
     "type": "Microsoft.Resources/resourceGroups"
   }
   

   Note that you can combine with standard –query and –output switches, e.g. az rest --uri $uri --query id --output tsv.

Delete

The delete uses the same uri. You specify the DELETE method.

1. View the Resource Groups - Delete documentation

2. Use az rest to delete

   az rest --method delete --uri https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01
   

   Note that the command returns immediately. The az group delete command usually waits unless --no-wait is specified. You can check status using the get call.

Create or Update

The create uses PUT, and requires a request body.

1. View the Resource Groups - Create Or Update documentation

   Use the In this article link to jump to the Request Body and the Examples

   The example JSON request body for resource groups is simple:

   {
     "location": "westeurope"
   }
   

   We will use more complex JSON to assign the new managedBy property using a variable.

2. Set a variable for your objectId

   objectId=$(az ad signed-in-user show --query objectId --output tsv --only-show-errors)
   

3. Use az rest to create

   az rest --method put --body "{\"location\":\"westeurope\",\"managedBy\":\"$objectId\"}"  --uri https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01
   

   Note that the minified JSON for the --body switch is a double quoted string. The $objectId will be resolved. Using double quotes means that all quotes within the JSON need to be escaped with a backslash.

   If your request body string is literal then you can use single quotes, e.g. '{"location":"westeurope"}'.

Update

The update uses PATCH and also requires a JSON request body. We’ll use a variable in the JSON and update the tags.

1. View the Resource Groups - Update documentation

   Note the ResourceGroupPatchable section. This is a subset of the overall resource group properties.

   For instance, you cannot update the location as that would force a deletion and recreation for the resource group.

2. Create variables

   It is common to use variables for the --uri and --body switches.

   uri=https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup?api-version=2021-04-01
   

   owner="Your Name"
   

   body=$(cat <<EOF
   {
     "tags": {
       "owner": "$owner",
       "site": "Azure Citadel"
     }
   }
   EOF
   )
   

   The last command uses a heredoc with a variable. There are other ways of dynamically generating JSON, e.g. jq.

3. Use az rest to patch

   Update the tags.

   az rest --method patch --body "$body" --uri $uri
   

The resource group’s tags will be updated.

Summary

You have used the REST API via the Azure CLI’s az rest command to show, delete, recreate and update a resource.