Dela via

Resources - Resources

  • Reference
Service:
Azure Resource Graph
API Version:
2024-04-01

Queries the resources managed by Azure Resource Manager for scopes specified in the request.

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

URI Parameters

Name In Required Type Description
api-version
 query True

string

The API version to use for this operation.

Request Body

Name Required Type Description
query True

string

The resources query.
facets

FacetRequest[]

An array of facet requests to be computed against the query result.
managementGroups

string[]

Azure management groups against which to execute the query. Example: [ 'mg1', 'mg2' ]
options

QueryRequestOptions

The query evaluation options
subscriptions

string[]

Azure subscriptions against which to execute the query.

Responses

Name Type Description
200 OK

QueryResponse

Result of the query operation
Other Status Codes

ErrorResponse

An error occurred while processing the request. See the error.code parameter to identify the specific error.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Access a properties field
Basic management group query
Basic query
Basic tenant query
Complex query
Filter resources
First page query
Next page query
Query with a facet request
Random page query
Summarize resources by location

Access a properties field

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | where type =~ 'Microsoft.Compute/virtualMachines' | summarize count() by tostring(properties.storageProfile.osDisk.osType)"
}

Sample response

Status code:
200 
{
  "totalRecords": 2,
  "count": 2,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "properties_storageProfile_osDisk_osType": "Linux",
      "count": 7
    },
    {
      "properties_storageProfile_osDisk_osType": "Windows",
      "count": 23
    }
  ]
}

Basic management group query

Sample request

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

{
  "managementGroups": [
    "e927f598-c1d4-4f72-8541-95d83a6a4ac8",
    "ProductionMG"
  ],
  "query": "Resources | project id, name, type, location, tags | limit 3"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "location": "westus",
      "tags": {}
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "location": "westus",
      "tags": {}
    }
  ]
}

Basic query

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | project id, name, type, location, tags | limit 3"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "location": "westus",
      "tags": {}
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "location": "westus",
      "tags": {}
    }
  ]
}

Basic tenant query

Sample request

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

{
  "query": "Resources | project id, name, type, location, tags | limit 3"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "location": "westus",
      "tags": {}
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "location": "westus",
      "tags": {}
    }
  ]
}

Complex query

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | project id, name, type, location | where type =~ 'Microsoft.Compute/virtualMachines' | summarize count() by location | top 3 by count_"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "location": "centralus",
      "count_": 11
    },
    {
      "location": "eastus",
      "count_": 11
    },
    {
      "location": "southcentralus",
      "count_": 3
    }
  ]
}

Filter resources

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | project id, name, type, location | where type =~ 'Microsoft.Compute/virtualMachines' | limit 3"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/virtualMachines/myVm1",
      "name": "myVm1",
      "type": "microsoft.compute/virtualmachines",
      "location": "centralus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Compute/virtualMachines/myVirtualMachine",
      "name": "myVirtualMachine",
      "type": "microsoft.compute/virtualmachines",
      "location": "eastus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG3/providers/Microsoft.Compute/virtualMachines/testVm",
      "name": "testVm",
      "type": "microsoft.compute/virtualmachines",
      "location": "eastus"
    }
  ]
}

First page query

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "options": {
    "$top": 3,
    "$skip": 0
  }
}

Sample response

Status code:
200 
{
  "totalRecords": 386,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ==",
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/yetanothertest_OsDisk_1_f396cbcb625a457bb69fe2abf5975820",
      "name": "yetanothertest_OsDisk_1_f396cbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "location": "eastus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA",
      "name": "TestAA",
      "type": "microsoft.automation/automationaccounts",
      "location": "westcentralus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA/runbooks/TestRB",
      "name": "TestRB",
      "type": "microsoft.automation/automationaccounts/runbooks",
      "location": "westcentralus"
    }
  ]
}

Next page query

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "options": {
    "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ=="
  }
}

Sample response

Status code:
200 
{
  "totalRecords": 386,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "$skipToken": "eyAibm8yIjogImx1Y2syIiwgImJ1dDIiOiAibmljZTIiLCAidHJ5MiI6ICIhIiB9",
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/second_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "name": "second_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "location": "eastus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/AATest",
      "name": "AATest",
      "type": "microsoft.automation/automationaccounts",
      "location": "westcentralus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA/runbooks/RBTest",
      "name": "RBTest",
      "type": "microsoft.automation/automationaccounts/runbooks",
      "location": "westcentralus"
    }
  ]
}

Query with a facet request

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | where type =~ 'Microsoft.Compute/virtualMachines' | project id, name, location, resourceGroup, properties.storageProfile.osDisk.osType | limit 5",
  "facets": [
    {
      "expression": "location",
      "options": {
        "sortOrder": "desc",
        "$top": 3
      }
    },
    {
      "expression": "properties.storageProfile.osDisk.osType",
      "options": {
        "sortOrder": "desc",
        "$top": 3
      }
    },
    {
      "expression": "nonExistingColumn",
      "options": {
        "sortOrder": "desc",
        "$top": 3
      }
    },
    {
      "expression": "resourceGroup",
      "options": {
        "sortBy": "tolower(resourceGroup)",
        "sortOrder": "asc",
        "$top": 3
      }
    },
    {
      "expression": "resourceGroup",
      "options": {
        "filter": "resourceGroup contains 'test'",
        "$top": 3
      }
    }
  ]
}

Sample response

Status code:
200 
{
  "totalRecords": 5,
  "count": 5,
  "resultTruncated": "false",
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/B-TEST-RG/providers/Microsoft.Compute/virtualMachines/myTestVm",
      "name": "myTestVm",
      "location": "eastus",
      "resourceGroup": "B-TEST-RG",
      "properties_storageProfile_osDisk_osType": "Windows"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/c-rg/providers/Microsoft.Compute/virtualMachines/myTestAccountVm",
      "name": "myTestAccountVm",
      "location": "westcentralus",
      "resourceGroup": "c-rg",
      "properties_storageProfile_osDisk_osType": "Windows"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/I-RG/providers/Microsoft.Compute/virtualMachines/yetanothertest",
      "name": "yetanothertest",
      "location": "eastus",
      "resourceGroup": "I-RG",
      "properties_storageProfile_osDisk_osType": "Linux"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/x-test-rg/providers/Microsoft.Compute/virtualMachines/drafttest1bux4cv7a7q3aw",
      "name": "drafttest1bux4cv7a7q3aw",
      "location": "southcentralus",
      "resourceGroup": "x-test-rg",
      "properties_storageProfile_osDisk_osType": "Linux"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/y-rg/providers/Microsoft.Compute/virtualMachines/testvmntp25370",
      "name": "testvmntp25370",
      "location": "eastus",
      "resourceGroup": "y-rg",
      "properties_storageProfile_osDisk_osType": "Windows"
    }
  ],
  "facets": [
    {
      "expression": "location",
      "resultType": "FacetResult",
      "totalRecords": 3,
      "count": 3,
      "data": [
        {
          "location": "eastus",
          "count": 3
        },
        {
          "location": "southcentralus",
          "count": 1
        },
        {
          "location": "westcentralus",
          "count": 1
        }
      ]
    },
    {
      "expression": "properties.storageProfile.osDisk.osType",
      "resultType": "FacetResult",
      "totalRecords": 2,
      "count": 2,
      "data": [
        {
          "properties_storageProfile_osDisk_osType": "Linux",
          "count": 2
        },
        {
          "properties_storageProfile_osDisk_osType": "Windows",
          "count": 3
        }
      ]
    },
    {
      "expression": "nonExistingColumn",
      "resultType": "FacetError",
      "errors": [
        {
          "code": "NoValidColumns",
          "message": "No valid columns in facet expression."
        },
        {
          "code": "InvalidColumnNames",
          "message": "Invalid column names: [nonExistingColumn]."
        }
      ]
    },
    {
      "expression": "resourceGroup",
      "resultType": "FacetResult",
      "totalRecords": 5,
      "count": 3,
      "data": [
        {
          "resourceGroup": "B-TEST-RG",
          "count": 1
        },
        {
          "resourceGroup": "c-rg",
          "count": 1
        },
        {
          "resourceGroup": "I-RG",
          "count": 1
        }
      ]
    },
    {
      "expression": "resourceGroup",
      "resultType": "FacetResult",
      "totalRecords": 2,
      "count": 2,
      "data": [
        {
          "resourceGroup": "B-TEST-RG",
          "count": 1
        },
        {
          "resourceGroup": "x-test-rg",
          "count": 1
        }
      ]
    }
  ]
}

Random page query

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "options": {
    "$top": 2,
    "$skip": 10
  }
}

Sample response

Status code:
200 
{
  "totalRecords": 386,
  "count": 2,
  "resultTruncated": "false",
  "facets": [],
  "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ==",
  "data": [
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/third_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "name": "third_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "location": "eastus"
    },
    {
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/CCTest",
      "name": "CCTest",
      "type": "microsoft.automation/automationaccounts",
      "location": "westcentralus"
    }
  ]
}

Summarize resources by location

Sample request

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

{
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ],
  "query": "Resources | project id, name, type, location | summarize by location"
}

Sample response

Status code:
200 
{
  "totalRecords": 3,
  "count": 3,
  "resultTruncated": "false",
  "facets": [],
  "data": [
    {
      "location": "centralus"
    },
    {
      "location": "eastus"
    },
    {
      "location": "westus"
    }
  ]
}

Definitions

Name Description
AuthorizationScopeFilter

Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.
Error

Error info.
ErrorDetails

Error details.
ErrorResponse

Error response.
FacetError

A facet whose execution resulted in an error.
FacetRequest

A request to compute additional statistics (facets) over the query results.
FacetRequestOptions

The options for facet evaluation
FacetResult

Successfully executed facet containing additional statistics on the response of a query.
FacetSortOrder

The sorting order by the selected column (count by default).
QueryRequest

Describes a query to be executed.
QueryRequestOptions

The options for query evaluation
QueryResponse

Query result.
ResultFormat

Defines in which format query result returned.
ResultTruncated

Indicates whether the query results are truncated.

AuthorizationScopeFilter

Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.

Name Type Description
AtScopeAboveAndBelow

string

AtScopeAndAbove

string

AtScopeAndBelow

string

AtScopeExact

string

Error

Error info.

Name Type Description
code

string

Error code identifying the specific error.
details

ErrorDetails[]

Error details
message

string

A human readable error message.

ErrorDetails

Error details.

Name Type Description
code

string

Error code identifying the specific error.
message

string

A human readable error message.

ErrorResponse

Error response.

Name Type Description
error

Error

Error info.
Error information.

FacetError

A facet whose execution resulted in an error.

Name Type Description
errors

ErrorDetails[]

An array containing detected facet errors with details.
expression

string

Facet expression, same as in the corresponding facet request.
resultType string:

FacetError

Result type

FacetRequest

A request to compute additional statistics (facets) over the query results.

Name Type Description
expression

string

The column or list of columns to summarize by
options

FacetRequestOptions

The options for facet evaluation

FacetRequestOptions

The options for facet evaluation

Name Type Default value Description
$top

integer

The maximum number of facet rows that should be returned.
filter

string

Specifies the filter condition for the 'where' clause which will be run on main query's result, just before the actual faceting.
sortBy

string

The column name or query expression to sort on. Defaults to count if not present.
sortOrder

FacetSortOrder

desc

The sorting order by the selected column (count by default).

FacetResult

Successfully executed facet containing additional statistics on the response of a query.

Name Type Description
count

integer

Number of records returned in the facet response.
data

object

A JObject array or Table containing the desired facets. Only present if the facet is valid.
expression

string

Facet expression, same as in the corresponding facet request.
resultType string:

FacetResult

Result type
totalRecords

integer

Number of total records in the facet results.

FacetSortOrder

The sorting order by the selected column (count by default).

Name Type Description
asc

string

desc

string

QueryRequest

Describes a query to be executed.

Name Type Description
facets

FacetRequest[]

An array of facet requests to be computed against the query result.
managementGroups

string[]

Azure management groups against which to execute the query. Example: [ 'mg1', 'mg2' ]
options

QueryRequestOptions

The query evaluation options
query

string

The resources query.
subscriptions

string[]

Azure subscriptions against which to execute the query.

QueryRequestOptions

The options for query evaluation

Name Type Default value Description
$skip

integer

The number of rows to skip from the beginning of the results. Overrides the next page offset when $skipToken property is present.
$skipToken

string

Continuation token for pagination, capturing the next page size and offset, as well as the context of the query.
$top

integer

The maximum number of rows that the query should return. Overrides the page size when $skipToken property is present.
allowPartialScopes

boolean

False

Only applicable for tenant and management group level queries to decide whether to allow partial scopes for result in case the number of subscriptions exceed allowed limits.
authorizationScopeFilter

AuthorizationScopeFilter

AtScopeAndBelow

Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.
resultFormat

ResultFormat

objectArray

Defines in which format query result returned.

QueryResponse

Query result.

Name Type Description
$skipToken

string

When present, the value can be passed to a subsequent query call (together with the same query and scopes used in the current request) to retrieve the next page of data.
count

integer

Number of records returned in the current response. In the case of paging, this is the number of records in the current page.
data

object

Query output in JObject array or Table format.
facets Facet[]:

Query facets.
resultTruncated

ResultTruncated

Indicates whether the query results are truncated.
totalRecords

integer

Number of total records matching the query.

ResultFormat

Defines in which format query result returned.

Name Type Description
objectArray

string

table

string

ResultTruncated

Indicates whether the query results are truncated.

Name Type Description
false

string

true

string