Общие сведения о языке запросов графика ресурсов Azure

Язык запросов для Azure Resource Graph поддерживает множество операторов и функций. Каждый из них работает так же, как элементы языка запросов Kusto (KQL). Чтобы ознакомиться с языком запросов, используемом в Resource Graph, начните с учебника по KQL.

В этой статье рассматриваются компоненты языка, поддерживаемые Resource Graph:

• Общие сведения о языке запросов графика ресурсов Azure
  • таблицы Resource Graph;
  • Extended properties
  • пользовательские элементы языка Resource Graph;
    • Синтаксис общего запроса (предварительная версия)
  • поддерживаемые элементы языка KQL;
    • Поддерживаемые операторы табличного или верхнего уровня
  • Query scope
  • Escape characters
  • Next steps

Таблицы Resource Graph

Resource Graph предоставляет несколько таблиц для хранения данных по типам ресурсов Azure Resource Manager и их свойствам. Таблицы Resource Graph можно использовать с оператором join для получения свойств из связанных типов ресурсов.

Таблицы Graph ресурсов поддерживают join вкусы:

• innerunique
• inner
• leftouter
• fullouter

Список таблиц, включающих типы ресурсов, перейдите в таблицу Azure Resource Graph и ссылку на тип ресурса.

Чтобы узнать, какие типы ресурсов доступны в каждой таблице, используйте обозреватель Resource Graph на портале. В качестве альтернативы можно использовать такой запрос, как <tableName> | distinct type, чтобы получить список имеющихся в среде типов ресурсов, которые поддерживаются данной таблицей Resource Graph.

В приведенном ниже запросе показана простая операция join. The query result blends the columns together and any duplicate column names from the joined table, ResourceContainers in this example, are appended with 1. As ResourceContainers table has types for both subscriptions and resource groups, either type might be used to join to the resource from Resources table.

Resources
| join ResourceContainers on subscriptionId
| limit 1

В приведенном ниже запросе показано более сложное использование join. Во-первых, запрос используется project для получения полей из Resources типа ресурса Хранилища ключей Azure. The next step uses join to merge the results with ResourceContainers where the type is a subscription on a property that is both in the first table's project and the joined table's project. The field rename avoids join adding it as name1 since the property already is projected from Resources. Результатом запроса является хранилище ключей, которое представляет тип, название, местоположение и группу ресурсов хранилища, а также название подписки.

Resources
| where type == 'microsoft.keyvault/vaults'
| project name, type, location, subscriptionId, resourceGroup
| join (ResourceContainers | where type=='microsoft.resources/subscriptions' | project SubName=name, subscriptionId) on subscriptionId
| project type, name, location, resourceGroup, SubName
| limit 1

Extended properties

As a preview feature, some of the resource types in Resource Graph have more type-related properties available to query beyond the properties provided by Azure Resource Manager. This set of values, known as extended properties, exists on a supported resource type in properties.extended. To show resource types with extended properties, use the following query:

Resources
| where isnotnull(properties.extended)
| distinct type
| order by type asc

Пример: получить количество виртуальных машин по instanceView.powerState.code:

Resources
| where type == 'microsoft.compute/virtualmachines'
| summarize count() by tostring(properties.extended.instanceView.powerState.code)

пользовательские элементы языка Resource Graph

Синтаксис общего запроса (Предварительная версия)

As a preview feature, a shared query can be accessed directly in a Resource Graph query. Этот сценарий позволяет создавать стандартные запросы в виде общих и использовать их повторно. Чтобы вызвать общий запрос в рамках запроса Resource Graph, используйте синтаксис {{shared-query-uri}}. The URI of the shared query is the Resource ID of the shared query on the Settings page for that query. В этом примере наш URI общего запроса — /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS. Этот URI указывает на подписку, группу ресурсов и полное имя общего запроса, на который мы хотим ссылаться в другом запросе. Этот запрос совпадает с запросом, который был создан в Руководстве по созданию запроса и предоставлению общего доступа к нему.

Пример 1. Используйте только общий запрос:

Результаты этого запроса Resource Graph совпадают с результатами запроса, хранящегося в общем запросе.

{{/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS}}

Пример 2. Включение общего запроса в состав более крупного запроса:

Сначала этот запрос использует общий запрос, а затем использует limit для ограничения результатов.

{{/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS}}
| where properties_storageProfile_osDisk_osType =~ 'Windows'

Поддерживаемые элементы языка KQL

Resource Graph supports a subset of KQL data types, scalar functions, scalar operators, and aggregation functions. Specific tabular operators are supported by Resource Graph, some of which have different behaviors.

Поддерживаемые табличные операторы и операторы верхнего уровня

Ниже приведен список табличных операторов KQL, поддерживаемых Resource Graph с определенными примерами:

Ограничение по умолчанию — три join и три mv-expand оператора в одном запросе пакета SDK для Resource Graph. Чтобы увеличить эти ограничения для своего клиента, выберите Справка + поддержка.

To support the Open Query portal experience, Azure Resource Graph Explorer has a higher global limit than Resource Graph SDK.

Query scope

The scope of the subscriptions or management groups from which resources are returned by a query defaults to a list of subscriptions based on the context of the authorized user. If a management group or a subscription list isn't defined, the query scope is all resources, and includes Azure Lighthouse delegated resources.

Список подписок или групп управления для запроса может быть определен вручную для изменения области результатов. Например, свойство managementGroups REST API принимает идентификатор группы управления, который отличается от названия группы управления. При managementGroups указании включены ресурсы из первых 10 000 подписок в указанной иерархии групп управления или в ней. managementGroups нельзя использовать в то же время, что и subscriptions.

Пример. Запрос всех ресурсов в иерархии группы управления с My Management Group идентификатором myMG.

• Универсальный код ресурса (URI) REST API

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

• Request Body

  {
    "query": "Resources | summarize count()",
    "managementGroups": ["myMG"]
  }
  

Этот AuthorizationScopeFilter параметр позволяет перечислять Политика Azure назначения и назначения ролей на основе ролей Azure (Azure RBAC) в AuthorizationResources таблице, унаследованной от верхних областей. Параметр AuthorizationScopeFilter принимает следующие значения для PolicyResources таблиц и AuthorizationResources таблиц:

• AtScopeAndBelow (default if not specified): Returns assignments for the given scope and all child scopes.
• AtScopeAndAbove: Returns assignments for the given scope and all parent scopes, but not child scopes.
• AtScopeAboveAndBelow: Returns assignments for the given scope, all parent scopes, and all child scopes.
• AtScopeExact: Returns assignments only for the given scope; no parent or child scopes are included.

Example: Get all policy assignments at the myMG management group and Tenant Root (parent) scopes.

• Универсальный код ресурса (URI) REST API

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

• Пример текста запроса

  {
    "options": {
      "authorizationScopeFilter": "AtScopeAndAbove"
    },
    "query": "PolicyResources | where type =~ 'Microsoft.Authorization/PolicyAssignments'",
    "managementGroups": ["myMG"]
  }
  

Example: Get all policy assignments at the mySubscriptionId subscription, management group, and Tenant Root scopes.

• Универсальный код ресурса (URI) REST API

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

• Пример текста запроса

  {
    "options": {
      "authorizationScopeFilter": "AtScopeAndAbove"
    },
    "query": "PolicyResources | where type =~ 'Microsoft.Authorization/PolicyAssignments'",
    "subscriptions": ["mySubscriptionId"]
  }
  

Escape characters

Некоторые имена свойств, например включающие в себя . или $, должны заключаться в оболочку или экранироваться в запросе, иначе они будут интерпретироваться неправильно и давать непредвиденные результаты.

• Точка (.): заключите имя ['propertyname.withaperiod'] свойства с помощью квадратных скобок.

  Example query that wraps the property odata.type:

  where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.['odata.type']
  

• Знак доллара ($): экранируйте символ в имени свойства. Используемый escape-символ зависит от оболочки, которая запускает Resource Graph.

  • Bash: Use a backslash (\) as the escape character.

    Example query that escapes the property $type in Bash:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.\$type
    

  • cmd: Don't escape the dollar sign ($) character.

  • PowerShell: Use a backtick (`) as the escape character.

    Example query that escapes the property $type in PowerShell:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.`$type
    

Next steps

• Azure Resource Graph query language Starter queries and Advanced queries.
• Узнайте больше о том, как изучить ресурсы Azure.