Programmatically create Azure dashboards
This article walks you through the process of programmatically creating and publishing Azure dashboards. The sample dashboard shown below is referenced throughout the document.
Overview
Shared dashboards in the Azure portal are resources, just like virtual machines and storage accounts. You can manage resources programmatically by using the Azure Resource Manager REST APIs, the Azure CLI, and Azure PowerShell commands.
Many features build on these APIs to make resource management easier. Each of these APIs and tools offers ways to create, list, retrieve, modify, and delete resources. Since dashboards are resources, you can pick your favorite API or tool to use.
Whichever tools you use, to create a dashboard programmatically, you construct a JSON representation of your dashboard object. This object contains information about the tiles on the dashboard. It includes sizes, positions, resources they're bound to, and any user customizations.
The most practical way to generate this JSON document is to use the Azure portal to create an initial dashboard with the tiles you want. Then export the JSON and create a template from the result that you can modify further and use in scripts, programs, and deployment tools.
Create a dashboard
To create a dashboard, select Dashboard from the Azure portal menu, then select New dashboard.
For detailed instructions, see Create a dashboard in the Azure portal.
Share the dashboard
After you configure the dashboard, the next step is to publish the dashboard using the Share command.
When you share a dashboard, you'll need to choose which subscription and resource group to publish to. You must have write access to the subscription and resource group that you choose. For more information, see Assign Azure roles using the Azure portal.
For detailed instructions, see Share Azure dashboards by using Azure role-based access control.
Fetch the JSON representation of the dashboard
Sharing the dashboard only takes a few seconds. When it's done, the next step is to export the JSON using the Download command.
You can also retrieve information about the dashboard resource programmatically by using REST APIs or other methods.
Create a template from the JSON
The next step is to create a template from this JSON. You'll be able to use the template programmatically with the appropriate resource management APIs, command-line tools, or within the portal.
You don't have to fully understand the dashboard JSON structure to create a template. In most cases, you want to preserve the structure and configuration of each tile. Then parameterize the set of Azure resources that the tiles point to.
Look at your exported JSON dashboard and find all occurrences of Azure resource IDs. Our example dashboard has multiple tiles that all point at a single Azure virtual machine. That's because our dashboard only looks at this single resource. If you search the sample JSON, included at the end of the document, for "/subscriptions", you'll find several occurrences of this ID.
/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1
To publish this dashboard for any virtual machine in the future, parameterize every occurrence of this string within the JSON.
There are two approaches for APIs that create resources in Azure:
- Imperative APIs create one resource at a time. For more information, see Resources.
- A template-based deployment system that creates multiple, dependent resources with a single API call. For more information, see Deploy resources with Resource Manager templates and Azure PowerShell.
Template-based deployment supports parameterization and templating. We use this approach in this article.
Programmatically create a dashboard from your template using a template deployment
Azure offers the ability to orchestrate the deployment of multiple resources. You create a deployment template that expresses the set of resources to deploy and the relationships between them. The JSON format of each resource is the same as if you were creating them one by one. The difference is that the template language adds a few concepts like variables, parameters, basic functions, and more. This extended syntax is only supported in the context of a template deployment. It doesn't work if used with the imperative APIs discussed earlier. For more information, see Understand the structure and syntax of Azure Resource Manager templates.
Parameterization should be done using the template's parameter syntax. You replace all instances of the resource ID we found earlier as shown here.
Example JSON property with hard-coded resource ID:
id: "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
Example JSON property converted to a parameterized version based on template parameters
id: "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
Declare required template metadata and the parameters at the top of the JSON template like this:
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"virtualMachineName": {
"type": "string"
},
"virtualMachineResourceGroup": {
"type": "string"
},
"dashboardName": {
"type": "string"
}
},
"variables": {},
... rest of template omitted ...
Once you've configured your template, deploy it using any of the following methods:
Next you'll see two versions of our example dashboard JSON. The first is the version that we exported from the portal that was already bound to a resource. The second is the template version that can be programmatically bound to any virtual machine and deployed using Azure Resource Manager.
JSON representation of our example dashboard
This example is similar to what you'll see if you followed along with this article. The instructions exported the JSON representation of a dashboard that is already deployed. The hard-coded resource identifiers show that this dashboard is pointing at a specific Azure virtual machine.
{
"properties": {
"lenses": {
"0": {
"order": 0,
"parts": {
"0": {
"position": {
"x": 0,
"y": 0,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/MarkdownPart",
"settings": {
"content": {
"settings": {
"content": "## Azure Virtual Machines Overview\r\nNew team members should watch this video to get familiar with Azure Virtual Machines.",
"title": "",
"subtitle": ""
}
}
}
}
},
"1": {
"position": {
"x": 3,
"y": 0,
"rowSpan": 4,
"colSpan": 8
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/MarkdownPart",
"settings": {
"content": {
"settings": {
"content": "This is the team dashboard for the test VM we use on our team. Here are some useful links:\r\n\r\n1. [Getting started](https://www.contoso.com/tsgs)\r\n1. [Troubleshooting guide](https://www.contoso.com/tsgs)\r\n1. [Architecture docs](https://www.contoso.com/tsgs)",
"title": "Test VM Dashboard",
"subtitle": "Contoso"
}
}
}
}
},
"2": {
"position": {
"x": 0,
"y": 2,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/VideoPart",
"settings": {
"content": {
"settings": {
"title": "",
"subtitle": "",
"src": "https://www.youtube.com/watch?v=YcylDIiKaSU&list=PLLasX02E8BPCsnETz0XAMfpLR1LIBqpgs&index=4",
"autoplay": false
}
}
}
}
},
"3": {
"position": {
"x": 0,
"y": 4,
"rowSpan": 3,
"colSpan": 11
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1",
"chartType": 0,
"metrics": [
{
"name": "Percentage CPU",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"4": {
"position": {
"x": 0,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1",
"chartType": 0,
"metrics": [
{
"name": "Disk Read Operations/Sec",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
},
{
"name": "Disk Write Operations/Sec",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"5": {
"position": {
"x": 3,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1",
"chartType": 0,
"metrics": [
{
"name": "Disk Read Bytes",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
},
{
"name": "Disk Write Bytes",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"6": {
"position": {
"x": 6,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1",
"chartType": 0,
"metrics": [
{
"name": "Network In",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
},
{
"name": "Network Out",
"resourceId": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"7": {
"position": {
"x": 9,
"y": 7,
"rowSpan": 2,
"colSpan": 2
},
"metadata": {
"inputs": [
{
"name": "id",
"value": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/contoso/providers/Microsoft.Compute/virtualMachines/myVM1"
}
],
"type": "Extension/Microsoft_Azure_Compute/PartType/VirtualMachinePart",
"asset": {
"idInputName": "id",
"type": "VirtualMachine"
},
"defaultMenuItemId": "overview"
}
}
}
}
},
"metadata": { }
},
"id": "/subscriptions/6531c8c8-df32-4254-d717-b6e983273e5d/resourceGroups/dashboards/providers/Microsoft.Portal/dashboards/aa9786ae-e159-483f-b05f-1f7f767741a9",
"name": "aa9786ae-e159-483f-b05f-1f7f767741a9",
"type": "Microsoft.Portal/dashboards",
"location": "westus",
"tags": {
"hidden-title": "Created via API"
}
}
Template representation of our example dashboard
The template version of the dashboard has defined three parameters called virtualMachineName, virtualMachineResourceGroup, and dashboardName. The parameters let you point this dashboard at a different Azure virtual machine every time you deploy. This dashboard can be programmatically configured and deployed to point to any Azure virtual machine. To test this feature, copy the following template and paste it into the Azure portal template deployment page.
This example deploys a dashboard by itself, but the template language lets you deploy multiple resources, and bundle one or more dashboards alongside them.
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"virtualMachineName": {
"type": "string"
},
"virtualMachineResourceGroup": {
"type": "string"
},
"dashboardName": {
"type": "string"
}
},
"variables": {},
"resources": [
{
"properties": {
"lenses": {
"0": {
"order": 0,
"parts": {
"0": {
"position": {
"x": 0,
"y": 0,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/MarkdownPart",
"settings": {
"content": {
"settings": {
"content": "## Azure Virtual Machines Overview\r\nNew team members should watch this video to get familiar with Azure Virtual Machines.",
"title": "",
"subtitle": ""
}
}
}
}
},
"1": {
"position": {
"x": 3,
"y": 0,
"rowSpan": 4,
"colSpan": 8
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/MarkdownPart",
"settings": {
"content": {
"settings": {
"content": "This is the team dashboard for the test VM we use on our team. Here are some useful links:\r\n\r\n1. [Getting started](https://www.contoso.com/tsgs)\r\n1. [Troubleshooting guide](https://www.contoso.com/tsgs)\r\n1. [Architecture docs](https://www.contoso.com/tsgs)",
"title": "Test VM Dashboard",
"subtitle": "Contoso"
}
}
}
}
},
"2": {
"position": {
"x": 0,
"y": 2,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [],
"type": "Extension[azure]/HubsExtension/PartType/VideoPart",
"settings": {
"content": {
"settings": {
"title": "",
"subtitle": "",
"src": "https://www.youtube.com/watch?v=YcylDIiKaSU&list=PLLasX02E8BPCsnETz0XAMfpLR1LIBqpgs&index=4",
"autoplay": false
}
}
}
}
},
"3": {
"position": {
"x": 0,
"y": 4,
"rowSpan": 3,
"colSpan": 11
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]",
"chartType": 0,
"metrics": [
{
"name": "Percentage CPU",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"4": {
"position": {
"x": 0,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]",
"chartType": 0,
"metrics": [
{
"name": "Disk Read Operations/Sec",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
},
{
"name": "Disk Write Operations/Sec",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"5": {
"position": {
"x": 3,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]",
"chartType": 0,
"metrics": [
{
"name": "Disk Read Bytes",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
},
{
"name": "Disk Write Bytes",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"6": {
"position": {
"x": 6,
"y": 7,
"rowSpan": 2,
"colSpan": 3
},
"metadata": {
"inputs": [
{
"name": "queryInputs",
"value": {
"timespan": {
"duration": "PT1H",
"start": null,
"end": null
},
"id": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]",
"chartType": 0,
"metrics": [
{
"name": "Network In",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
},
{
"name": "Network Out",
"resourceId": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
]
}
}
],
"type": "Extension/Microsoft_Azure_Monitoring/PartType/MetricsChartPart",
"settings": {}
}
},
"7": {
"position": {
"x": 9,
"y": 7,
"rowSpan": 2,
"colSpan": 2
},
"metadata": {
"inputs": [
{
"name": "id",
"value": "[resourceId(parameters('virtualMachineResourceGroup'), 'Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
],
"type": "Extension/Microsoft_Azure_Compute/PartType/VirtualMachinePart",
"asset": {
"idInputName": "id",
"type": "VirtualMachine"
},
"defaultMenuItemId": "overview"
}
}
}
}
}
},
"metadata": { },
"apiVersion": "2015-08-01-preview",
"type": "Microsoft.Portal/dashboards",
"name": "[parameters('dashboardName')]",
"location": "westus",
"tags": {
"hidden-title": "[parameters('dashboardName')]"
}
}
]
}
Now that you've seen an example of using a parameterized template to deploy a dashboard, you can try deploying the template by using the Azure Resource Manager REST APIs, the Azure CLI, or Azure PowerShell commands.
Programmatically create a dashboard by using Azure CLI
Prepare your environment for the Azure CLI.
Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
- These examples use the following dashboard: portal-dashboard-template-testvm.json. Be sure to replace all of the content in angled brackets with your values.
Run the az portal dashboard create command to create a dashboard based on your template:
az portal dashboard create --resource-group myResourceGroup --name 'Simple VM Dashboard' \
--input-path portal-dashboard-template-testvm.json --location centralus
You can update a dashboard by using the az portal dashboard update command:
az portal dashboard update --resource-group myResourceGroup --name 'Simple VM Dashboard' \
--input-path portal-dashboard-template-testvm.json --location centralus
See the details of a dashboard by running the az portal dashboard show command:
az portal dashboard show --resource-group myResourceGroup --name 'Simple VM Dashboard'
To see all the dashboards for the current subscription, use az portal dashboard list:
az portal dashboard list
You can also see all the dashboards for a resource group:
az portal dashboard list --resource-group myResourceGroup
Next steps
- Learn how to use markdown tiles on Azure dashboards to show custom content.
- Explore all Azure CLI commands for dashboards, see az portal dashboard.
- Learn how to manage Azure portal settings and preferences.
Feedback
Submit and view feedback for