Edit

Share via

Quickstart: Run Resource Graph query using REST API

  • Article

This quickstart describes how to run an Azure Resource Graph query with REST API and view the results. The REST API elements are a URI that includes the API version and request body that contains the query. The examples use Azure CLI to sign into Azure and that authenticates your account to run az rest commands.

If you're unfamiliar with REST API, start by reviewing Azure REST API Reference to get a general understanding of REST API, specifically request URI and request body. For the Azure Resource Graph specifications, see Azure Resource Graph REST API.

Prerequisites

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.

az login

# Run these commands if you have multiple subscriptions
az account list --output table
az account set --subscription {subscriptionID}

Use az login even if you're using PowerShell because the examples use Azure CLI az rest commands.

Review the REST API syntax

There are two elements to run REST API commands: the REST API URI and the request body. For information, go to Resources. To query by management group, use managementGroups instead of subscriptions. To query the entire tenant, omit both the managementGroups and subscriptions properties from the request body.

The following example shows the REST API URI syntax to run a query for an Azure subscription.

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01

A request body is needed to run a query with REST API. The following example is the JSON to create a request body file.

{
  "subscriptions": [
    "{subscriptionID}"
  ],
  "query": "Resources | project name, type | limit 5"
}

Run Resource Graph query

The examples use the same az rest command but you change the request body to get different results. The examples list resources, order resources by the name property, and order resources by the name property and limit the number of results.

To run all the query examples, use the following az rest command for your shell environment:

az rest --method post --uri https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01 --body `@request-body.json

In PowerShell, the backtick (`) is needed to escape the at sign (@) to specify a filename for the request body.

In each request body example, replace {subscriptionID} with your Azure subscription ID. Run the following command to get your Azure subscription ID for the request body:

az account show --query id --output tsv

List resources

In Visual Studio Code, create a new file named request-body.json. Copy and paste the following JSON into the file and save the file.

The query returns five Azure resources with the name and resource type of each resource.

{
  "subscriptions": [
    "{subscriptionID}"
  ],
  "query": "Resources | project name, type | limit 5"
}

Because this query example doesn't provide a sort modifier like order by, running this query multiple times yields a different set of resources per request.

Order by name property

Update request-body.json with the following code that changes the query to order by the name property. Save the file and use the az rest command to run the query.

{
  "subscriptions": [
    "{subscriptionID}"
  ],
  "query": "Resources | project name, type | limit 5 | order by name asc"
}

If you run this query multiple times, it yields a different set of resources per request.

The order of the query commands is important. In this example, the order by comes after the limit. This command order limits the query results to five resources and then orders them.

Order by name property and limit results

Update request-body.json with the following code to order by the name property and then limit to the top five results. Save the file and use the same az rest command to run the query.

{
  "subscriptions": [
    "{subscriptionID}"
  ],
  "query": "Resources | project name, type | order by name asc | limit 5"
}

If the query is run several times, assuming that nothing in your environment changed, the results returned are consistent and ordered by the name property, but limited to the top five results.

Clean up resources

Sign out of your Azure CLI session.

az logout

Next steps

In this quickstart, you used the Azure Resource Graph REST API endpoint to run a query. To learn more about the Resource Graph language, continue to the query language details page.

Understanding the Azure Resource Graph query language