Quickstart: Create a Resource Graph shared query using Azure PowerShell

Article
06/28/2024

In this quickstart, you create an Azure Resource Graph shared query using the Az.ResourceGraph Azure PowerShell module. The module is included with the latest version of Azure PowerShell and adds cmdlets for Resource Graph.

A shared query can be run from Azure CLI with the experimental feature's commands, or you can run the shared query from the Azure portal. A shared query is an Azure Resource Manager object that you can grant permission to or run in Azure Resource Graph Explorer. When you finish, you can remove the Resource Graph extension.

Prerequisites

If you don't have an Azure account, create a free account before you begin.
Latest versions of PowerShell and Azure PowerShell.
Visual Studio Code.

Install the module

If you installed the latest versions of PowerShell and Azure PowerShell, you already have the Az.ResourceGraph module and required version of PowerShellGet.

Optional module installation

Use the following steps to install the Az.ResourceGraph module so that you can use Azure PowerShell to run Azure Resource Graph queries. The Azure Resource Graph module requires PowerShellGet version 2.0.1 or higher.

Verify your PowerShellGet version:
```
Get-Module -Name PowerShellGet
```
If you need to update, go to PowerShellGet.
Install the module:
```
Install-Module -Name Az.ResourceGraph -Repository PSGallery -Scope CurrentUser
```
The command installs the module in the CurrentUser scope. If you need to install in the AllUsers scope, run the installation from an administrative PowerShell session.
Verify the module was installed:
```
Get-Command -Module Az.ResourceGraph -CommandType Cmdlet
```
The command displays the Search-AzGraph cmdlet version and loads the module into your PowerShell session.

Connect to Azure

From a Visual Studio Code terminal session, connect to Azure. If you have more than one subscription, run the commands to set context to your subscription. Replace <subscriptionID> with your Azure subscription ID.

Connect-AzAccount

# Run these commands if you have multiple subscriptions
Get-AzSubScription
Set-AzContext -Subscription <subscriptionID>

Create a shared query

The shared query is an Azure Resource Manager object that you can grant permission to or run in Azure Resource Graph Explorer. The query summarizes the count of all resources grouped by location.

Create a resource group to store the Azure Resource Graph shared query.
```
New-AzResourceGroup -Name demoSharedQuery -Location westus2
```

Create the Azure Resource Graph shared query.

$params = @{
  Name = 'Summarize resources by location'
  ResourceGroupName = 'demoSharedQuery'
  Location = 'westus2'
  Description = 'This shared query summarizes resources by location for a pinnable map graphic.'
  Query = 'Resources | summarize count() by location'
}

New-AzResourceGraphQuery @params

The $params variable uses PowerShell splatting to improve readability for the parameter values used in the command to create the shared query.

List all shared queries in the resource group.

Get-AzResourceGraphQuery -ResourceGroupName demoSharedQuery

Limit the results to a specific shared query.

Get-AzResourceGraphQuery -ResourceGroupName demoSharedQuery -Name 'Summarize resources by location'

Run the shared query

You can verify the shared query works using Azure Resource Graph Explorer. To change the scope, use the Scope menu on the left side of the page.

Sign in to Azure portal.
Enter resource graph into the search field at the top of the page.
Select Resource Graph Explorer.
Select Open query.
Change Type to Shared queries.
Select the query Count VMs by OS.
Select Run query and the view output in the Results tab.
Select Charts and then select Map to view the location map.

You can also run the query from your resource group.

In Azure, go to the resource group, demoSharedQuery.
From the Overview tab, select the query Count VMs by OS.
Select the Results tab to view a list.
Select Charts and then select Map to view the location map.

Clean up resources

When you finish, you can remove the Resource Graph shared query and resource group from your Azure environment. When a resource group is deleted, the resource group and all its resources are deleted.

Remove the shared query:

Remove-AzResourceGraphQuery -ResourceGroupName demoSharedQuery -Name 'Summarize resources by location'

Delete the resource group:

Remove-AzResourceGroup -Name demoSharedQuery

To sign out of your Azure PowerShell session:

Disconnect-AzAccount

Optional clean up steps

If you installed the latest version of Azure PowerShell, the Az.ResourceGraph module is included and shouldn't be removed. The following steps are optional if you did a manual install of the Az.ResourceGraph module and want to remove the module.

To remove the Az.ResourceGraph module from your PowerShell session, run the following command:

Remove-Module -Name Az.ResourceGraph

To uninstall the Az.ResourceGraph module from your computer, run the following command:

Uninstall-Module -Name Az.ResourceGraph

A message might be displayed that module Az.ResourceGraph is currently in use. If so, you need to shut down your PowerShell session and start a new session. Then run the command to uninstall the module from your computer.

Next steps

In this quickstart, you created a Resource Graph shared query using Azure PowerShell. To learn more about the Resource Graph language, continue to the query language details page.

Understanding the Azure Resource Graph query language

Share via