了解 Azure Resource Graph 查询语言

Azure Resource Graph 查询语言支持多个运算符和函数。 每个运算符和函数的工作原理和操作方式基于 Kusto 查询语言 (KQL)。 若要了解 Resource Graph 使用的查询语言,请从 KQL 教程开始。

本文介绍 Resource Graph 支持的语言组件:

Resource Graph 表

Resource Graph 为其存储的有关 Azure 资源管理器资源类型及其属性的数据提供多个表。 一些表可以与 joinunion 运算符配合使用,以便从相关资源类型获取属性。 下面是 Resource Graph 中可用表的列表:

Resource Graph 表 与其他表之间可否执行 join 说明
资源 如果未在查询中定义,则为默认表。 此处显示了大多数资源管理器资源类型和属性。
ResourceContainers 包括订阅(预览版 -- Microsoft.Resources/subscriptions)和资源组 (Microsoft.Resources/subscriptions/resourcegroups) 资源类型和数据。
AdvisorResources 是(预览版) 包括与 Microsoft.Advisor 相关的资源。
AlertsManagementResources 是(预览版) 包括与 Microsoft.AlertsManagement 相关的资源。
GuestConfigurationResources 包括与 Microsoft.GuestConfiguration 相关的资源。
MaintenanceResources 部分可以,仅限联接到。 (预览版) 包括与 Microsoft.Maintenance 相关的资源。
PatchAssessmentResources 包括与 Azure 虚拟机补丁评估相关的资源。
PatchInstallationResources 包括与 Azure 虚拟机补丁安装相关的资源。
PolicyResources 包括与 Microsoft.PolicyInsights 相关的资源。 (预览版
RecoveryServicesResources 部分可以,仅限联接到。 (预览版) 包括与 Microsoft.RecoveryServices 相关的资源。
SecurityResources 是(预览版) 包括与 Microsoft.Security 相关的资源。
ServiceHealthResources 包括与 Microsoft.ResourceHealth 相关的资源。

有关包含资源类型的完整列表,请参阅参考:支持的表和资源类型

备注

Resources 是默认表。 查询 Resources 表时,无需提供表名称,除非使用 joinunion。 但是,建议的做法是始终在查询中包含初始表。

使用门户中的 Resource Graph 资源管理器来发现每个表中有哪些可用的资源类型。 或者,使用查询(如 <tableName> | distinct type)来获取环境中存在的给定 Resource Graph 表所支持的资源类型的列表。

以下查询显示了简单的 join 用法。 查询结果将列混合在一起,并且联接表中的所有重复列名称(在此示例中为 ResourceContainers)将附加 1。 由于 ResourceContainers 表具有用于订阅的类型和用于资源组的类型,因此可以使用任一类型来联接到 Resources 表中的资源。

Resources
| join ResourceContainers on subscriptionId
| limit 1

以下查询显示了 join 的更复杂用法。 首先,该查询使用 project 针对 Azure Key Vault 保管库资源类型从 Resources 获取字段。 下一步使用 join 将结果与 ResourceContainers合并,其中,type 是既在第一个表的 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

备注

限制具有 projectjoin 结果时,join 用于关联两个表的属性(在上述示例中为 subscriptionId)必须包含在 project 中。

扩展属性(预览)

作为预览功能,除了 Azure 资源管理器提供的属性以外,Resource Graph 中的某些资源类型还有其他类型相关的属性可供查询。 这组值(称为“扩展属性”)存在于 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 是该查询的“设置”页上的共享查询的资源 ID。 在此示例中,我们的共享查询 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 支持部分 KQL 数据类型标量函数标量运算符聚合函数。 Resource Graph 支持特定表格运算符,其中一些运算符具有不同的行为。

支持的表格/顶级运算符

下面是 Resource Graph 支持的 KQL 表格运算符的列表,以及特定示例:

KQL Resource Graph 示例查询 说明
计数 对密钥保管库进行计数
distinct 显示包含存储的资源
extend 按 OS 类型对虚拟机进行计数
join 具有订阅名称的密钥保管库 支持的联接类型:inneruniqueinnerleftouter。 单个查询中最多只能有 3 个 join(其中 1 个可以是跨表 join)。 如果所有跨表 join 都在 Resource 与 ResourceContainers 之间使用,则会允许 3 个跨表 join。 不允许使用自定义联接策略,如广播联接。 有关哪些表可以使用 join,请参阅 Resource Graph 表
limit 列出所有公共 IP 地址 Synonym of take. 无法与 Skip配合使用。
mvexpand 旧运算符,请改用 mv-expand。 RowLimit 最大值为 400。 默认值为 128。
mv-expand 列出具有特定写入位置的 Cosmos DB RowLimit 最大值为 400。 默认值为 128。 单个查询中的 mv-expand 数量限制为 2 个。
order 列出按名称排序的资源 sort 的同义词
project 列出按名称排序的资源
project-away 删除结果中的列
sort 列出按名称排序的资源 order 的同义词
summarize 对 Azure 资源进行计数 仅已简化首页
take 列出所有公共 IP 地址 Synonym of limit. 无法与 Skip配合使用。
返回页首 按名称及其 OS 类型显示前五个虚拟机
union 将两个查询的结果合并为单个结果 允许使用单个表:T | union [kind= inner|outer] [withsource=ColumnName] Table。 单个查询中的 union 分支限制为 3。 不允许对 union 分支表进行模糊解析。 可以在单个表中使用,也可以在 Resources 和 ResourceContainers 表中使用。
where 显示包含存储的资源

单个 Resource Graph SDK 查询中默认最多只能有 3 个 join 和 3 个 mv-expand 运算符。 可以通过“帮助 + 支持”来请求为租户提高这些限制。

为了支持“打开查询”门户体验,Azure Resource Graph 资源管理器具有比 Resource Graph SDK 更高的全局限制。

查询范围

查询返回的资源的订阅范围取决于访问 Resource Graph 的方法。 Azure CLI 和 Azure PowerShell 会根据授权用户的上下文填充要在请求中加入的订阅列表。 可以分别使用 subscriptions 和 Subscription 参数为每个订阅手动定义订阅列表 。 在 REST API 和所有其他 SDK 中,包括资源的订阅列表必须显式定义为请求的一部分。

作为预览版,REST API 版本 2020-04-01-preview 会添加一个属性,将查询范围限定到管理组。 此预览 API 也使订阅属性成为可选属性。 如果未定义管理组或订阅列表,则查询范围为所有资源。

新的 managementGroupId 属性采用管理组 ID,该 ID 不同于管理组的名称。 指定 managementGroupId 时,将包含在指定管理组层次结构中或其下的前 5,000 个订阅的资源。 managementGroupIdsubscriptions 不能同时使用。

示例:使用 ID“myMG”查询管理组层次结构中名为“我的管理组”的所有资源。

  • REST API URI

    POST https://management.chinacloudapi.cn/providers/Microsoft.ResourceGraph/resources?api-version=2020-04-01-preview
    
  • 请求正文

    {
        "query": "Resources | summarize count()",
        "managementGroupId": "myMG"
    }
    

转义字符

某些属性名称(例如,包含 .$ 的名称)必须在查询中进行包装或转义,否则属性名称将被错误解释,并且不会提供预期结果。

  • . - 包装属性名称,如下所示:['propertyname.withaperiod']

    用于包装属性 odata.type 的示例查询:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.['odata.type']
    
  • $ - 转义属性名称中的字符。 使用的转义字符取决于运行 Resource Graph 的 shell。

    • bash - \

      在 Bash 中对 $type 属性进行转义的示例查询:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.\$type
      
    • cmd - 不要转义 $ 字符。

    • PowerShell - `

      用于在 PowerShell 中转义属性 $type 的示例查询:

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

后续步骤