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

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

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

• Общие сведения о языке запросов графика ресурсов Azure
  • таблицы Resource Graph;
  • Расширенные свойства
  • пользовательские элементы языка Resource Graph;
    • Синтаксис общего запроса (предварительная версия)
  • поддерживаемые элементы языка KQL;
    • Поддерживаемые операторы табличного или верхнего уровня
  • Область запроса
  • Персонажи Escape
  • Дальнейшие действия

Таблицы 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. Результат запроса объединяет столбцы, и любые дублирующиеся имена столбцов из объединённой таблицы, ResourceContainers в данном примере, добавляются 1. Поскольку таблица ResourceContainers содержит типы как для подписок, так и для групп ресурсов, любой из типов может использоваться для присоединения к ресурсу из Resources таблицы.

Resources
| join ResourceContainers on subscriptionId
| limit 1

В приведенном ниже запросе показано более сложное использование join. Во-первых, запрос используется project для получения полей из Resources типа ресурса Хранилища ключей Azure. Следующий шаг использует join слияние результатов с ResourceContainers , где тип является подпиской на свойство, которое находится как в project первой таблице, так и в объединённой таблице project. Переименование поля избегает join добавления его как name1 , поскольку свойство уже проецируется из 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

Расширенные свойства

В качестве функции предварительного просмотра некоторые типы ресурсов в Resource Graph имеют больше типовых свойств, доступных для запроса, помимо свойств, предоставляемых Azure Resource Manager. Этот набор значений, известный как расширенные свойства, существует на поддерживаемом типе ресурса в properties.extended. Чтобы показать типы ресурсов с расширенными свойствами, используйте следующий запрос:

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

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

В качестве функции предварительного просмотра общий запрос можно получить напрямую в запросе Resource Graph. Этот сценарий позволяет создавать стандартные запросы в виде общих и использовать их повторно. Чтобы вызвать общий запрос в рамках запроса Resource Graph, используйте синтаксис {{shared-query-uri}}. URI общего запроса — это идентификатор ресурса общего запроса на странице настроек для этого запроса. В этом примере наш 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

Граф ресурсов поддерживает подмножество типов данных KQL, скалярных функций, скалярных операторов и функций агрегации. Определённые табличные операторы поддерживаются графом ресурсов, некоторые из которых имеют разное поведение.

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

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

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

Для поддержки работы с порталом Open Query Azure Resource Graph Explorer имеет более высокий глобальный лимит, чем Resource Graph SDK.

Область запроса

Область подписок или групп управления , из которых ресурсы возвращаются по запросу, по умолчанию сводится к списку подписок на основе контекста уполномоченного пользователя. Если группа управления или список подписок не определены, область запроса — это все ресурсы и делегированные ресурсы Azure Lighthouse .

Список подписок или групп управления для запроса может быть определен вручную для изменения области результатов. Например, свойство 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
  

• Тело запроса

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

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

• AtScopeAndBelow (по умолчанию, если не указано): Возвращает назначения для данной области области и всех дочерних областей.
• AtScopeAndAbove: Возвращает назначения для данной области и всех родительских областей, но не для дочерних областей.
• AtScopeAboveAndBelow: Возвращает назначения для данной области, всех родительских областей и всех дочерних областей.
• AtScopeExact: Возвращает присваивания только для данной области; Не включены родительские или детские прицелы.

Пример: Получите все назначения полисов в управленческой группе myMG и Tenant Root (родительских) сферах.

• Универсальный код ресурса (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"]
  }
  

Пример: Получите все назначения политик в подписке mySubscriptionId , группе управления и корневом диапазоне арендаторов.

• Универсальный код ресурса (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-символы

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

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

  Пример запроса, который обворачивает свойство odata.type:

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

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

  • Удар: Используйте обратную черту (\) в качестве персонажа для побега.

    Пример запроса, который избегает свойства $type в Bash:

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

  • cmd: Не уходите от символа доллара ($) персонажа.

  • PowerShell: Используйте backtick (`) в качестве персонажа для побега.

    Пример запроса, который избегает свойства $type в PowerShell:

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

Функции оценки разрешений RBAC в Azure Resource Graph

Azure Resource Graph (ARG) предоставляет две функции, позволяющие оценить, имеет ли удостоверение запроса current querying identity имеет определенные разрешения для отдельных ресурсов:

• hasPermission()
• hasDataPermission()

Эти функции возвращают логическое значение (1 или 0) для каждого ресурса и обеспечивают такие сценарии, как фильтрация или сводка ресурсов на основе доступа.

hasPermission()

Функция hasPermission() оценивает, имеет ли запрашивающее удостоверение определенное разрешение на плоскость управления для ресурса.

Используйте следующий формат:hasPermission()

hasPermission('<permission-string>')

Функция hasPermission() использует эффективные назначения RBAC для идентификатора запроса и вычисляет каждую строку ресурса. Функция возвращает 1 — удостоверение имеет указанное разрешение на ресурс и 0 , если удостоверение не имеет.

Пример проверки доступа на запись к реестрам контейнеров Azure

resources
| where type =~ 'Microsoft.ContainerRegistry/registries'
| extend canPush = hasPermission('Microsoft.ContainerRegistry/registries/push/write')

В этом примере каждый ресурс реестра контейнеров оценивается по отдельности и canPush указывает, может ли запрашивающее удостоверение выполнять указанное действие записи в этом ресурсе. Результаты можно использовать для фильтрации, агрегирования или суммирования на основе возвращаемого значения.

hasDataPermission()

Определяет hasDataPermission() , имеет ли запрашивающее удостоверение определенное разрешение плоскости данных для ресурса.

Используйте следующий формат:hasDataPermission()

hasDataPermission('<permission-string>')

Функция hasDataPermission() использует эффективную оценку доступа на уровне данных для идентификатора запроса и вычисляется на строку ресурса. Функция возвращает значение 1, если удостоверение имеет указанное разрешение плоскости данных для ресурса и 0, если удостоверение не имеет.

Пример. Проверка доступа на чтение плоскости данных к Хранилище BLOB-объектов Azure

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| extend canReadBlobs = hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read')

В этом примере каждый ресурс хранилища оценивается по отдельности. Функция hasDataPermissions() проверяет, имеет ли запрашивающее удостоверение указанные разрешения data-pe. Возвращаемое значение можно использовать для фильтрации, сводки или создания отчетов.

Пример. Проверка доступа на чтение плоскости данных к Хранилище BLOB-объектов Azure с помощью фильтрации

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| where hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read') == 1

В этом примере возвращаются только учетные записи хранения, в которых удостоверение запроса имеет доступ на чтение BLOB-объектов.

Важные ограничения

Эти функции часто путаются с сценариями обнаружения ролей или разрешений. Для понимания важны следующие ограничения.

• hasDataPermission() Функции hasPermission() не определяют, какие разрешения предоставляет определение роли.
• Их нельзя использовать для запроса или фильтрации ресурсов microsoft.authorization/roledefinitions .
• Они не предназначены для ответа на такие вопросы, как:
  • "Какие роли предоставляют это разрешение?"
  • "Какие действия включают это определение роли?"

Дальнейшие шаги

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