Quickstart: Run your first Resource Graph query using REST API

Članak
07/20/2021
4 min. za čitanje

The first step to using Azure Resource Graph with REST API is to check that you have a tool for calling REST APIs available. This quickstart then walks you through the process of running a query and retrieving the results by calling the Azure Resource Graph REST API endpoint.

At the end of this process, you'll have the tools for calling REST API endpoints and run your first Resource Graph query.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To run the code in this article in Azure Cloud Shell:

Start Cloud Shell.
Select the Copy button on a code block to copy the code.
Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code.

Getting started with REST API

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. This article uses these concepts to provide directions for working with Azure Resource Graph and assumes a working knowledge of them. Tools such as ARMClient and others may handle authorization automatically and are recommended for beginners.

For the Azure Resource Graph specs, see Azure Resource Graph REST API.

REST API and PowerShell

If you don't already have a tool for making REST API calls, consider using PowerShell for these instructions. The following code sample gets a header for authenticating with Azure. Generate an authentication header, sometimes called a Bearer token, and provide the REST API URI to connect to with any parameters or a Request Body:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = 'https://management.azure.com/subscriptions/{subscriptionId}?api-version=2020-01-01'
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

Replace {subscriptionId} in the $restUri variable to get information about your subscription. The $response variable holds the result of the Invoke-RestMethod cmdlet, which can be parsed with cmdlets such as ConvertFrom-Json. If the REST API service endpoint expects a Request Body, provide a JSON formatted variable to the -Body parameter of Invoke-RestMethod.

Run your first Resource Graph query

With the REST API tools added to your environment of choice, it's time to try out a simple subscription-based Resource Graph query. The query returns the first five Azure resources with the Name and Resource Type of each resource. 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.

In the request body of each REST API call, there's a variable that is used that you need to replace with your own value:

{subscriptionID} - Replace with your subscription ID

Run your first Azure Resource Graph query using the REST API and the resources endpoint:
- REST API URI
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- Request Body
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5"
}
```
Note

As this query example doesn't provide a sort modifier such as order by, running this query multiple times is likely to yield a different set of resources per request.
Update the call to the resouces endpoint and change the query to order by the Name property:
- REST API URI
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- Request Body
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5 | order by name asc"
}
```
Note

Just as with the first query, running this query multiple times is likely to yield 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 first limits the query results and then orders them.

Update the call to the resources endpoint and change the query to first order by the Name property and then limit to the top five results:

REST API URI

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

Request Body

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

When the final query is run several times, assuming that nothing in your environment is changing, the results returned are consistent and ordered by the Name property, but still limited to the top five results.

For more examples of REST API calls for Azure Resource Graph, see the Azure Resource Graph REST Examples.

Clean up resources

REST API has no libraries or modules to uninstall. If you installed a tool such as ARMClient or Postman to make the calls and no longer need it, you may uninstall the tool now.

Next steps

In this quickstart, you've called the Resource Graph REST API endpoint and run your first query. To learn more about the Resource Graph language, continue to the query language details page.

Get more information about the query language