Skip to content

Commit 67ea5dd

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #281003 from davidsmatlak/ds-arg-rest-quickstart-20240716
Updates Azure Resource Graph REST API quickstart
2 parents a4c2ab8 + 482c77d commit 67ea5dd

File tree

1 file changed

+105
-119
lines changed

1 file changed

+105
-119
lines changed

‎articles/governance/resource-graph/first-query-rest-api.md

Lines changed: 105 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,164 +1,150 @@
11
---
2-
title: "Quickstart: Your first REST API query"
3-
description: In this quickstart, you follow the steps to call the Resource Graph endpoint for REST API and run your first query.
4-
ms.date: 07/09/2021
2+
title: Run Azure Resource Graph query using REST API
3+
description: In this quickstart, you run an Azure Resource Graph query using REST API and Azure CLI.
4+
ms.date: 07/18/2024
55
ms.topic: quickstart
66
---
7-
# Quickstart: Run your first Resource Graph query using REST API
87

9-
The first step to using Azure Resource Graph with REST API is to check that you have a tool for
10-
calling REST APIs available. This quickstart then walks you through the process of running a query
11-
and retrieving the results by calling the Azure Resource Graph REST API endpoint.
8+
# Quickstart: Run Resource Graph query using REST API
129

13-
At the end of this process, you'll have the tools for calling REST API endpoints and run your first
14-
Resource Graph query.
10+
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.
11+
12+
If you're unfamiliar with REST API, start by reviewing [Azure REST API Reference](/rest/api/azure/)
13+
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](/rest/api/azureresourcegraph/resourcegraph/operation-groups).
1514

1615
## Prerequisites
1716

18-
If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/) account
19-
before you begin.
17+
- If you don't have an Azure account, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
18+
- Latest version of [PowerShell](/powershell/scripting/install/installing-powershell) or Bash shell like Git Bash.
19+
- Latest version of [Azure CLI](/cli/azure/install-azure-cli).
20+
- [Visual Studio Code](https://code.visualstudio.com/).
2021

21-
[!INCLUDE [cloud-shell-try-it.md](~/reusable-content/ce-skilling/azure/includes/cloud-shell-try-it.md)]
22+
## Connect to Azure
2223

23-
## Getting started with REST API
24+
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.
2425

25-
If you're unfamiliar with REST API, start by reviewing [Azure REST API Reference](/rest/api/azure/)
26-
to get a general understanding of REST API, specifically request URI and request body. This article
27-
uses these concepts to provide directions for working with Azure Resource Graph and assumes a
28-
working knowledge of them. Tools such as [ARMClient](https://github.com/projectkudu/ARMClient) and
29-
others may handle authorization automatically and are recommended for beginners.
30-
31-
For the Azure Resource Graph specs, see
32-
[Azure Resource Graph REST API](/rest/api/azure-resourcegraph/).
33-
34-
### REST API and PowerShell
35-
36-
If you don't already have a tool for making REST API calls, consider using PowerShell for these
37-
instructions. The following code sample gets a header for authenticating with Azure. Generate an
38-
authentication header, sometimes called a **Bearer token**, and provide the REST API URI to connect
39-
to with any parameters or a **Request Body**:
40-
41-
```azurepowershell-interactive
42-
# Log in first with Connect-AzAccount if not using Cloud Shell
43-
44-
$azContext = Get-AzContext
45-
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
46-
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
47-
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
48-
$authHeader = @{
49-
'Content-Type'='application/json'
50-
'Authorization'='Bearer ' + $token.AccessToken
51-
}
26+
```azurecli
27+
az login
5228
53-
# Invoke the REST API
54-
$restUri = "https://management.azure.com/subscriptions/$($azContext.Subscription.Id)?api-version=2020-01-01"
55-
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader
29+
# Run these commands if you have multiple subscriptions
30+
az account list --output table
31+
az account set --subscription {subscriptionID}
5632
```
5733

58-
The `$response` variable holds the result of the `Invoke-RestMethod` cmdlet, which can be parsed
59-
with cmdlets such as
60-
[ConvertFrom-Json](/powershell/module/microsoft.powershell.utility/convertfrom-json). If the REST
61-
API service endpoint expects a **Request Body**, provide a JSON formatted variable to the `-Body`
62-
parameter of `Invoke-RestMethod`.
34+
Use `az login` even if you're using PowerShell because the examples use Azure CLI [az rest](/cli/azure/reference-index#az-rest) commands.
6335

64-
## Run your first Resource Graph query
36+
## Review the REST API syntax
6537

66-
With the REST API tools added to your environment of choice, it's time to try out a simple
67-
subscription-based Resource Graph query. The query returns the first five Azure resources with the
68-
**Name** and **Resource Type** of each resource. To query by
69-
[management group](../management-groups/overview.md), use `managementgroups` instead of
70-
`subscriptions`. To query the entire tenant, omit both the `managementgroups` and `subscriptions`
71-
properties from the request body.
38+
There are two elements to run REST API commands: the REST API URI and the request body. For information, go to [Resources](/rest/api/azureresourcegraph/resourcegraph/resources/resources). To query by [management group](../management-groups/overview.md), use `managementGroups` instead of `subscriptions`. To query the entire tenant, omit both the `managementGroups` and `subscriptions` properties from the request body.
7239

73-
In the request body of each REST API call, there's a variable that is used that you need to replace
74-
with your own value:
40+
The following example shows the REST API URI syntax to run a query for an Azure subscription.
7541

76-
- `{subscriptionID}` - Replace with your subscription ID
42+
```http
43+
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01
44+
```
7745

78-
1. Run your first Azure Resource Graph query using the REST API and the `resources` endpoint:
46+
A request body is needed to run a query with REST API. The following example is the JSON to create a request body file.
7947

80-
- REST API URI
48+
```json
49+
{
50+
"subscriptions": [
51+
"{subscriptionID}"
52+
],
53+
"query": "Resources | project name, type | limit 5"
54+
}
55+
```
8156

82-
```http
83-
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
84-
```
57+
## Run Resource Graph query
8558

86-
- Request Body
59+
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.
8760

88-
```json
89-
{
90-
"subscriptions": [
91-
"{subscriptionID}"
92-
],
93-
"query": "Resources | project name, type | limit 5"
94-
}
95-
```
61+
To run all the query examples, use the following `az rest` command for your shell environment:
9662

97-
> [!NOTE]
98-
> As this query example doesn't provide a sort modifier such as `order by`, running this query
99-
> multiple times is likely to yield a different set of resources per request.
63+
# [PowerShell](#tab/powershell)
10064

101-
1. Update the call to the `resouces` endpoint and change the **query** to `order by` the **Name**
102-
property:
65+
```powershell
66+
az rest --method post --uri https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01 --body `@request-body.json
67+
```
10368

104-
- REST API URI
69+
In PowerShell, the backtick (``` ` ```) is needed to escape the `at sign` (`@`) to specify a filename for the request body.
10570

106-
```http
107-
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
108-
```
71+
# [Bash](#tab/bash)
10972

110-
- Request Body
73+
```bash
74+
az rest --method post --uri https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01 --body @request-body.json
75+
```
76+
77+
In a Bash shell like Git Bash, the backtick isn't needed to escape the `at sign` (`@`) to specify a filename for the request body.
11178

112-
```json
113-
{
114-
"subscriptions": [
115-
"{subscriptionID}"
116-
],
117-
"query": "Resources | project name, type | limit 5 | order by name asc"
118-
}
119-
```
79+
---
12080

121-
> [!NOTE]
122-
> Just as with the first query, running this query multiple times is likely to yield a different
123-
> set of resources per request. The order of the query commands is important. In this example,
124-
> the `order by` comes after the `limit`. This command order first limits the query results and
125-
> then orders them.
81+
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:
12682

127-
1. Update the call to the `resources` endpoint and change the **query** to first `order by` the
128-
**Name** property and then `limit` to the top five results:
83+
```azurecli
84+
az account show --query id --output tsv
85+
```
12986

130-
- REST API URI
87+
### List resources
13188

132-
```http
133-
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
134-
```
89+
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.
13590

136-
- Request Body
91+
The query returns five Azure resources with the `name` and `resource type` of each resource.
92+
93+
```json
94+
{
95+
"subscriptions": [
96+
"{subscriptionID}"
97+
],
98+
"query": "Resources | project name, type | limit 5"
99+
}
100+
```
137101

138-
```json
139-
{
140-
"subscriptions": [
141-
"{subscriptionID}"
142-
],
143-
"query": "Resources | project name, type | order by name asc | limit 5"
144-
}
145-
```
102+
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.
146103

147-
When the final query is run several times, assuming that nothing in your environment is changing,
148-
the results returned are consistent and ordered by the **Name** property, but still limited to the
149-
top five results.
104+
### Order by name property
150105

151-
For more examples of REST API calls for Azure Resource Graph, see the
152-
[Azure Resource Graph REST Examples](/rest/api/azureresourcegraph/resourcegraph(2021-03-01)/resources/resources#examples).
106+
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.
107+
108+
```json
109+
{
110+
"subscriptions": [
111+
"{subscriptionID}"
112+
],
113+
"query": "Resources | project name, type | limit 5 | order by name asc"
114+
}
115+
```
116+
117+
If you run this query multiple times, it yields a different set of resources per request.
118+
119+
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.
120+
121+
### Order by name property and limit results
122+
123+
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.
124+
125+
126+
```json
127+
{
128+
"subscriptions": [
129+
"{subscriptionID}"
130+
],
131+
"query": "Resources | project name, type | order by name asc | limit 5"
132+
}
133+
```
134+
135+
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.
153136

154137
## Clean up resources
155138

156-
REST API has no libraries or modules to uninstall. If you installed a tool like _ARMClient_ to make the calls and no longer need it, you may uninstall the tool now.
139+
Sign out of your Azure CLI session.
140+
141+
```azurecli
142+
az logout
143+
```
157144

158145
## Next steps
159146

160-
In this quickstart, you've called the Resource Graph REST API endpoint and run your first query. To
161-
learn more about the Resource Graph language, continue to the query language details page.
147+
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.
162148

163149
> [!div class="nextstepaction"]
164-
> [Get more information about the query language](./concepts/query-language.md)
150+
> [Understanding the Azure Resource Graph query language](./concepts/query-language.md)

0 commit comments

Comments
 (0)