Query the Azure REST API of Azure DevTest Labs with Postman

At the moment I am middle in the process of writing my ARM templates for deploying an Azure DevTest Lab environment based on an Azure DevOps CI/CD pipeline. Unfortunately not all the options you can configure from the Azure portal are exported by the automation script option of the resource group or are available within the Azure Resource Explorer. So much of the information you need you have to find in the REST API documentation of DevTest Labs.

To find out what the results are from the Policies - List GET method I need to query the REST API. I will be using the Postman app for this purpose. To query the Azure REST API you will need to be authenticated. You can do this in two ways: with your own Microsoft/Azure AD account or with a service principal. Because of the ad-hoc character of my research the Microsoft account route is the one I will use.

Retrieving bearer token

To retrieve the bearer token of my Microsoft account I need to authenticate myself. For this purpose we will have to install the ARMClient app. For the installation I will use Chocolatey.

Start a PowerShell console with administrator rights and use the following command to install Chocolatey if it's not installed on your machine.

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Close your PowerShell console to ensure that chocolatey is loaded correctly. Open a new PowerShell console with administrator rights and use the following command to install ARMClient.

choco install armclient

To retrieve the bearer token you will have to login with the ARMClient. Use the following command.

ARMClient login

Sign in to your Azure account in the prompt you will see. To retrieve the bearer token in your clipboard you will need the following command.

ARMClient token

Save the value for later usage in the Postman app.

Querying the Azure DevTest Labs REST API

Now we have the bearer token we can start quering the REST API of Azure DevTest Labs. Download the Postman app en install it on your machine. After Postman is installed start the app and choose the Request building block.

We have to give the request a name. In this case we enter the value 'List Policies' for the request name field. The request also has to be added to a collection. Via the create collection option we create a new collection named 'Azure DevTest Labs'. After selecting the newly created collection we can save our new request.

From the documentation we copy the GET URL we need to list the policies which are configured within our Azure DevTest lab environment. Extra accolades are added to use the Postman variables.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.DevTestLab/labs/{{labName}}/policysets/{{policySetName}}/policies?api-version=2016-05-15

In this URL we have a few placeholders which have to be replaced with actual values. We can manually replace them in the URL or we can used the environment option of Postman. In the right corner of Postman you will find an option to manage environments. Because we don't have any environments we will have to add one.

We will enter 'Azure DevTest Labs' as the environment name. After that we fill the key-value pairs of the variables. We will have to create a variable for the subscriptionId, resoureceGroupName, labName and policySetName. For the policySetName we use the value 'default'. When all the variables are configured we add the environment via the add button. Don't forget to select the created environment in the pulldown menu.

On the authorization tab we have to select the type. From the pulldown menu we select the Bearer Token option. In the token field we will add the bearer token we retrieved with the ARMClient. After saving the constructed request it's time to test it.

We send the GET request to the REST API and receive an error.

{
    "error": {
        "code": "ArgumentException",
        "message": "Requested value 'ScheduleEditPermission' was not found."
    }
}

This looks like that there is a PolicyFactName received which is not part the API definition at the moment. According the current documentation (API Version: 2016-05-15) this is not an allowed value. It's one of the new option which is already available in the UI but not is described in the REST API documentation.

When I change the api-version value to an invalid value like '2100-01-01' I get an error message which indicates that there are newer API versions than listed in the online documentation.

{
    "error": {
        "code": "NoRegisteredProviderFound",
        "message": "No registered resource provider found for location 'westeurope' and API version '2018-01-01' for type 'labs'. The supported api-versions are '2018-10-15-preview, 2018-09-15, 2017-04-26-preview, 2016-05-15, 2015-05-21-preview'. The supported locations are 'westcentralus, japaneast, westus, australiacentral, australiasoutheast, canadacentral, centralindia, centralus, eastasia, francecentral, koreacentral, northeurope, southcentralus, ukwest, westindia, australiacentral2, australiaeast, brazilsouth, canadaeast, eastus, eastus2, francesouth, japanwest, koreasouth, northcentralus, southindia, southeastasia, uksouth, westeurope, westus2'."
    }
}

After changing the api-version to the latest version, currently 2018-10-15-preview, retrieving a list of policies works like a charm.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.DevTestLab/labs/{{labName}}/policysets/{{policySetName}}/policies?api-version=2018-10-15-preview

Because retrieving the list now works I also now know how to configure the missing policies which are available in the UI and where not described in the REST API documentation.