Using the Azure Resource Manager REST API
Microsoft Azure was released into public preview in 2008. A year later, the Azure Service Management (ASM) REST API was released to support the management of Azure PaaS cloud services and Azure Storage. Since then, the ASM control plane has been expanded to support the many new Azure services introduced in the last six years. However, ASM is starting to show its age since it had not been designed to support the wide variety of services now provided by Azure.
The Azure Resource Manager (ARM) was introduced in 2015 to provide a modern control plane for Azure that would support the management of both existing and new services in a coherent and robust manner. Like many services accessible over the Internet, the definitive way to access ARM is through a REST API. There are also a variety of client libraries built on top of the REST API including: .NET, Java, Node.js PHP, python and Ruby. However, using the ARM REST API directly can be helpful for new features that have not yet been exposed through a client library.
This post provides a short overview of using the ARM REST API as well as some examples of using it.
ARM REST API
Authentication – Get Bearer Token
The ARM REST API uses oauth2 authentication which requires that a bearer token be sent as a request header with each operation. This bearer token expires so must be periodically refreshed. Client libraries can support the automatic refresh of the bearer token but this must be done manually when the REST API is used.
The Get Bearer Token operation uses an Azure Active Directory (AAD) service principal to retrieve a bearer token. The creation of the service principal and its addition to an appropriate RBAC role is documented here and described in this post.
An oauth2 bearer token can be generated by creating the following HTTPS request:
- POST /TENANT-NAME/oauth2/token?api-version=1.0
- Host: login.windows.net
- Cache-Control: no-cache
- Connection: Keep-Alive
- Content-Type: application/x-www-form-urlencoded
- Expect: 100-continue
TENANT-NAME must be replaced with the name of the AAD tenant, similar to: contoso.onmicrosoft.com or contoso.com.
The request requires a body created using the following parameters:
- grant_type=client_credentials
- resource=https://management.azure.com/
- client_id=APPLICATION-GUID
- client_secret=URL-ENCODED-PASSWORD
The parameters are concatenated into an ampersand-separated string in which the service principal password has been URL encoded, leading to the following:
grant_type=client_credentials&resource=https://management.azure.com/&client_id=APPLICATION-GUID&client_secret=URL-ENCODED-PASSWORD
On successful invocation, the Get Bearer Token operation returns a response body similar to the following:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1455680701",
"not_before": "1455676801",
"resource": "https://management.azure.com/",
"access_token": "eyJ0eXAiOi..."
}
access_token is the bearer token used to authenticate ARM REST API requests.
Resources
In ARM, the atomic unit of service deployment is a resource – e.g., VM, VNET, NIC, public IP address, storage account, etc. Each resource is contained in precisely one resource group, and an Azure subscription can have many resource groups. A resource is managed by a resource provider – such as Microsoft.Compute, Microsoft.Storage, etc. – each of which manages one or more types of resource – such as Microsoft.Compute/virtualMachines, Microsoft.Storage/storageAccounts, etc.
The URL for the ARM REST API is typically a standard combination of subscription ID, resource group name, resource type and resource – along with an API version that is specific to the resource provider. For example:
/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/STORAGE_ACCOUNT?api-version=2015-06-15
In this example, Microsoft.Storage/storageAccounts is the resource type. The appropriate values need to be substituted for SUBSCRIPTION_ID, RESOURCE_GROUP and STORAGE_ACCOUNT.
The host part of the URL is always the following for the ARM REST API:
The following headers are needed for all operations, and other headers may be required for some operations:
- Authorization: Bearer bearer_token
- Content-Type: application/json
Operation: List all Resource Groups
The list of resource groups in a subscription can be retrieved using the List all Resource Groups operation.
The operation is a GET request to the following URL:
https://management.azure.com/subscriptions/SUBSCRIPTION_ID/resourcegroups?api-version=2015-01-01
The request headers for the operation are:
- Authorization: Bearer BEARER_TOKEN
- Cache-Control: no-cache
- Content-Type: application/json
SUBSCRIPTION-ID must be replaced by the subscription ID of the subscription to be queried. BEARER_TOKEN must be replaced with the access_token returned by the Get Bearer Token operation.
On success, the List all Resource Groups operation returns a JSON array as follows:
{
"value": [
{
"id": "/subscriptions/SUBSCRIPTION_ID/resourceGroups/Default-SQL-CentralUS",
"name": "Default-SQL-CentralUS",
"location": "centralus",
"properties": {
"provisioningState": "Succeeded"
}
},
...
Operation: Create a Storage Account
An Azure storage account (ARM/v2) can be created using the Create a Storage Account operation in the ARM Storage REST API.
The operation is a PUT request to the following URL:
The request headers for the operation are:
- Authorization: Bearer BEARER_TOKEN
- Cache-Control: no-cache
- Content-Type: application/json
SUBSCRIPTION-ID must be replaced by the subscription ID of the subscription to be queried. BEARER_TOKEN must be replaced with the access_token returned by the Get Bearer Token operation.
The request body for the operation is:
{
"location": "LOCATION",
"properties": {
"accountType": "ACCOUNT_TYPE"
}
}
LOCATION must be replaced by the standard name of the Azure region for the storage account, such as westus. ACCOUNT_TYPE must be replaced by the Azure Storage account type, such as STANDARD_LRS.
Operation: Get Consumption Data for an Azure Subscription
The billing data for an Azure Subscription can be retrieved using the Get Consumption Data for an Azure Subscription operation from the ARM Billing REST API.
The simplest operation is a GET request to the following URL (although a variety of other request parameters are supported):
The request headers for the operation are:
- Authorization: Bearer BEARER_TOKEN
- Cache-Control: no-cache
- Content-Type: application/json
SUBSCRIPTION-ID must be replaced by the subscription ID of the subscription to be queried. BEARER_TOKEN must be replaced with the access_token returned by the Get Bearer Token operation. START_TIME and END_TIME are times, in ISO8601 format, representing the start and end times of the billing records to be retrieved – and will look something like the following: 2015-12-01+00%3A00%3A00Z.
On success, the Get Consumption Data for an Azure Subscription operation returns a JSON array like the following:
{
"value": [
{
"id": "/subscriptions/SUBSCRIPTION_ID/providers/Microsoft.Commerce/UsageAggregates/Daily_BRSDT_20151201_0000",
"name": "Daily_BRSDT_20151201_0000",
"type": "Microsoft.Commerce/UsageAggregate",
"properties": {
"subscriptionId": "SUBSCRIPTION_ID",
"usageStartTime": "2015-11-30T00:00:00+00:00",
"usageEndTime": "2015-12-01T00:00:00+00:00",
"meterName": "Free App Service",
"meterCategory": "Azure App Service",
"unit": "Apps",
"meterId": "c0f5cb45-6fb1-41c9-8545-72ad400d9da4",
"infoFields": {
"meteredRegion": "West US",
"meteredService": "Azure App Service",
"meteredServiceType": "Default1",
"project": "myproject"
},
"quantity": 0.002688
}
}, …
Summary
This post shows how easy it is to use the Azure Resource Manager REST API by providing several examples from different parts of the API.