通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

了解 Azure Resource Graph 查询语言

  • 项目

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

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

Resource Graph 表

Resource Graph 为其存储的有关 Azure 资源管理器资源类型及其属性的数据提供多个表。 Resource Graph 表可以与 join 运算符一起使用，以从相关资源类型获取属性。

Resource Graph 表支持 join 风格：

Resource Graph 表 与其他表之间可否执行 join？ 说明
AdvisorResources 是 包括与 Microsoft.Advisor 相关的资源。
AlertsManagementResources 是 包括与 Microsoft.AlertsManagement 相关的资源。
AppServiceResources 是 包括与 Microsoft.Web 相关的资源。
AuthorizationResources 是 包括与 Microsoft.Authorization 相关的资源。
AWSResources 是 包括与 Microsoft.AwsConnector 相关的资源。
AzureBusinessContinuityResources 是 包括与 Microsoft.AzureBusinessContinuity 相关的资源。
ChaosResources 是 包括与 Microsoft.Chaos 相关的资源。
CommunityGalleryResources 是 包括与 Microsoft.Compute 相关的资源。
ComputeResources 是 包括与 Microsoft.Compute 虚拟机规模集相关的资源。
DesktopVirtualizationResources 是 包括与 Microsoft.DesktopVirtualization 相关的资源。
DnsResources 是 包括与 Microsoft.Network 相关的资源。
EdgeOrderResources 是 包括与 Microsoft.EdgeOrder 相关的资源。
ElasticsanResources 是 包括与 Microsoft.ElasticSan 相关的资源。
ExtendedLocationResources 是 包括与 Microsoft.ExtendedLocation 相关的资源。
FeatureResources 是 包括与 Microsoft.Features 相关的资源。
GuestConfigurationResources 是 包括与 Microsoft.GuestConfiguration 相关的资源。
HealthResourceChanges 是 包括与 Microsoft.Resources 相关的资源。
HealthResources 是 包括与 Microsoft.ResourceHealth 相关的资源。
InsightsResources 是 包括与 Microsoft.Insights 相关的资源。
IoTSecurityResources 是 包括与 Microsoft.IoTSecurity 和 Microsoft.IoTFirmwareDefense 相关的资源。
KubernetesConfigurationResources 是 包括与 Microsoft.KubernetesConfiguration 相关的资源。
KustoResources 是 包括与 Microsoft.Kusto 相关的资源。
MaintenanceResources 是 包括与 Microsoft.Maintenance 相关的资源。
ManagedServicesResources 是 包括与 Microsoft.ManagedServices 相关的资源。
MigrateResources 是 包括与 Microsoft.OffAzure 相关的资源。
NetworkResources 是 包括与 Microsoft.Network 相关的资源。
OrbitalResources 是 包括与 Microsoft.Orbital 相关的资源。
PatchAssessmentResources 是 包括与 Azure 虚拟机补丁评估 Microsoft.Compute 和 Microsoft.HybridCompute 相关的资源。
PatchInstallationResources 是 包括与 Azure 虚拟机补丁安装 Microsoft.Compute 和 Microsoft.HybridCompute 相关的资源。
PolicyResources 是 包括与 Microsoft.PolicyInsights 相关的资源。
RecoveryServicesResources 是 包括与 Microsoft.DataProtection 和 Microsoft.RecoveryServices 相关的资源。
ResourceChanges 是 包括与 Microsoft.Resources 相关的资源。
ResourceContainerChanges 是 包括与 Microsoft.Resources 相关的资源。
ResourceContainers 是 包含管理组 (Microsoft.Management/managementGroups)、订阅 (Microsoft.Resources/subscriptions) 和资源组 (Microsoft.Resources/subscriptions/resourcegroups) 资源类型和数据。
资源 是 如果未在查询中定义表，则为默认表。 此处显示了大多数资源管理器资源类型和属性。
SecurityResources 是 包括与 Microsoft.Security 相关的资源。
ServiceFabricResources 是 包括与 Microsoft.ServiceFabric 相关的资源。
ServiceHealthResources 是 包括与 Microsoft.ResourceHealth/events 相关的资源。
SpotResources 是 包括与 Microsoft.Compute 相关的资源。
SupportResources 是 包括与 Microsoft.Support 相关的资源。
TagsResources 是 包括与 Microsoft.Resources/tagnamespaces 相关的资源。

有关包含资源类型的表的列表，请转到 Azure Resource Graph 表和资源类型引用。

注意

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

若要发现每个表中有哪些可用的资源类型，请使用门户中的 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

注意

限制具有 project 的 join 结果时，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 具有订阅名称的密钥保管库 支持的联接类型：innerunique、inner、leftouter 和 fullouter。 单个查询中最多只能有 3 个 join，其中 1 个可以是跨表 join。 如果所有跨表 join 都在 Resource 与 ResourceContainers 之间使用，则会允许 3 个跨表 join。 不允许使用自定义联接策略，如广播联接。 有关哪些表可以使用 join，请转到 Resource Graph 表。
limit 列出所有公共 IP 地址 Synonym of take. 无法与 Skip配合使用。
mvexpand 旧运算符，请改用 mv-expand。 RowLimit 最大值为 2,000。 默认值为 128。
mv-expand 列出具有特定写入位置的 Azure Cosmos DB RowLimit 最大值为 2,000。 默认值为 128。 单个查询中的 mv-expand 限制为 3。
order 列出按名称排序的资源 sort 的同义词
parse 获取网络接口的虚拟网络和子网 如果属性存在，则最好直接访问属性，而不是使用 parse。
project 列出按名称排序的资源
project-away 删除结果中的列
sort 列出按名称排序的资源 order 的同义词
summarize 对 Azure 资源进行计数 仅已简化首页
take 列出所有公共 IP 地址 Synonym of limit. 无法与 Skip配合使用。
返回页首 按名称及其 OS 类型显示前五个虚拟机
union 将两个查询的结果合并为单个结果 允许的单个表：| union [kind= inner|outer] [withsource=ColumnName] Table。 单个查询中存在 3 个 union 支线的限制。 不允许对 union 分支表进行模糊解析。 可以用在单个表中，也可以用在 Resources 表和 ResourceContainers 表之间。
where 显示包含存储的资源

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

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

注意

不能多次将表引用为右表，这会超出限值 1。 如果这样做，将会收到错误并显示代码 DisallowedMaxNumberOfRemoteTables。

查询范围

查询从中返回资源的订阅或管理组的范围默认为基于授权用户的上下文的订阅列表。 如果未定义管理组或订阅列表，则查询范围为所有资源且包括 Azure Lighthouse 委托资源。

可手动定义要查询的订阅或管理组列表，以更改结果的范围。 例如，REST API managementGroups 属性采用管理组 ID，该 ID 不同于管理组的名称。 指定 managementGroups 时，将包含在指定管理组层次结构中或其下的前 10,000 个订阅的资源。 managementGroups 与 subscriptions 不能同时使用。

示例：使用 ID myMG 查询管理组层次结构中名为 My Management Group 的所有资源。

  • REST API URI

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

  • 请求正文

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

通过 AuthorizationScopeFilter 参数，可以列出从上限范围继承的 AuthorizationResources 表中的 Azure Policy 分配和 Azure 基于角色的访问控制 (Azure RBAC) 角色分配。 AuthorizationScopeFilter 参数接受 PolicyResources 和 AuthorizationResources 表的以下值：

  • AtScopeAndBelow（在未指定的情况下为默认值）：返回给定范围和所有子范围的分配。
  • AtScopeAndAbove：返回给定范围和所有父范围的分配，但不返回子范围。
  • AtScopeAboveAndBelow：返回给定范围、所有父范围和所有子范围的分配。
  • AtScopeExact：仅返回给定范围的分配；不包括父范围或子范围。

注意

若要使用 AuthorizationScopeFilter 参数，请确保在请求中使用 2021-06-01-preview 或更高的 API 版本。

示例：获取 myMG 管理组和租户根（父）范围的所有策略分配。

  • REST API URI

    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 订阅、管理组和租户根范围的所有策略分配。

  • REST API URI

    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"]
}

转义字符

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

  • 点 (.) - 使用方括号将属性名称 ['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

后续步骤