Información del lenguaje de consulta de Azure Resource Graph

  • Artículo

El lenguaje de consulta de Azure Resource Graph admite muchos operadores y funciones. Cada uno funciona en función del lenguaje de consulta de Kusto (KQL). Para información sobre el lenguaje de consulta usado por Resource Graph, comience con el tutorial para KQL.

En este artículo se tratan los componentes de idioma admitidos por Resource Graph:

Tablas de Resource Graph

Resource Graph proporciona varias tablas para los datos que almacena sobre los tipos de recursos de Azure Resource Manager y sus propiedades. Las tablas de Resource Graph se pueden usar con el operador join para obtener propiedades de los tipos de recursos relacionados.

Las tablas de Resource Graph admiten los tipos de join:

Tabla de Resource Graph ¿Se puede usar join con otras tablas? Descripción
AdvisorResources Sí Incluye recursos relacionados con Microsoft.Advisor.
AlertsManagementResources Sí Incluye recursos relacionados con Microsoft.AlertsManagement.
AppServiceResources Sí Incluye recursos relacionados con Microsoft.Web.
AuthorizationResources Sí Incluye recursos relacionados con Microsoft.Authorization.
AWSResources Sí Incluye recursos relacionados con Microsoft.AwsConnector.
AzureBusinessContinuityResources Sí Incluye recursos relacionados con Microsoft.AzureBusinessContinuity.
ChaosResources Sí Incluye recursos relacionados con Microsoft.Chaos.
CommunityGalleryResources Sí Incluye recursos relacionados con Microsoft.Compute.
ComputeResources Sí Incluye recursos relacionados con Microsoft.ComputeVirtual Machine Scale Sets.
DesktopVirtualizationResources Sí Incluye recursos relacionados con Microsoft.DesktopVirtualization.
DnsResources Sí Incluye recursos relacionados con Microsoft.Network.
EdgeOrderResources Sí Incluye recursos relacionados con Microsoft.EdgeOrder.
ElasticsanResources Sí Incluye recursos relacionados con Microsoft.ElasticSan.
ExtendedLocationResources Sí Incluye recursos relacionados con Microsoft.ExtendedLocation.
FeatureResources Sí Incluye recursos relacionados con Microsoft.Features.
GuestConfigurationResources Sí Incluye recursos relacionados con Microsoft.GuestConfiguration.
HealthResourceChanges Sí Incluye recursos relacionados con Microsoft.Resources.
HealthResources Sí Incluye recursos relacionados con Microsoft.ResourceHealth.
InsightsResources Sí Incluye recursos relacionados con Microsoft.Insights.
IoTSecurityResources Sí Incluye recursos relacionados con Microsoft.IoTSecurity y Microsoft.IoTFirmwareDefense.
KubernetesConfigurationResources Sí Incluye recursos relacionados con Microsoft.KubernetesConfiguration.
KustoResources Sí Incluye recursos relacionados con Microsoft.Kusto.
MaintenanceResources Sí Incluye recursos relacionados con Microsoft.Maintenance.
ManagedServicesResources Sí Incluye recursos relacionados con Microsoft.ManagedServices.
MigrateResources Sí Incluye recursos relacionados con Microsoft.OffAzure.
NetworkResources Sí Incluye recursos relacionados con Microsoft.Network.
OrbitalResources Sí Incluye recursos relacionados con Microsoft.Orbital.
PatchAssessmentResources Sí Incluye los recursos relacionados con la evaluación de revisiones de Azure Virtual MachinesMicrosoft.Compute y Microsoft.HybridCompute.
PatchInstallationResources Sí Incluye los recursos relacionados con la instalación de revisiones de Azure Virtual MachinesMicrosoft.Compute y Microsoft.HybridCompute.
PolicyResources Sí Incluye recursos relacionados con Microsoft.PolicyInsights.
RecoveryServicesResources Sí Incluye recursos relacionados con Microsoft.DataProtection y Microsoft.RecoveryServices.
ResourceChanges Sí Incluye recursos relacionados con Microsoft.Resources.
ResourceContainerChanges Sí Incluye recursos relacionados con Microsoft.Resources.
ResourceContainers Sí Incluye el grupo de administración (Microsoft.Management/managementGroups), la suscripción (Microsoft.Resources/subscriptions) y los tipos de datos del grupo de recursos (Microsoft.Resources/subscriptions/resourcegroups) del grupo de recursos y los datos.
Recursos Sí Tabla predeterminada si una tabla no está definida en la consulta. La mayoría de los tipos de recursos y propiedades de Resource Manager están aquí.
SecurityResources Sí Incluye recursos relacionados con Microsoft.Security.
ServiceFabricResources Sí Incluye recursos relacionados con Microsoft.ServiceFabric.
ServiceHealthResources Sí Incluye recursos relacionados con Microsoft.ResourceHealth/events.
SpotResources Sí Incluye recursos relacionados con Microsoft.Compute.
SupportResources Sí Incluye recursos relacionados con Microsoft.Support.
TagsResources Sí Incluye recursos relacionados con Microsoft.Resources/tagnamespaces.

Para obtener una lista de tablas que incluye tipos de recursos, vaya a La tabla de Azure Resource Graph y la referencia de tipo de recurso.

Nota:

Resources es la tabla predeterminada. Al consultar la tabla Resources, no es necesario proporcionar el nombre de la tabla a menos que se usen join o union. Pero la práctica recomendada es incluir siempre la tabla inicial en la consulta.

Para detectar qué tipos de recursos están disponibles en cada tabla, use el Explorador de Resource Graph en el portal. Como alternativa, utilice una consulta como <tableName> | distinct type para obtener una lista de los tipos de recursos que admite la tabla de Resource Graph que existe en su entorno.

En la consulta siguiente se muestra un uso sencillo de join. El resultado de la consulta combina las columnas y los nombres de columna duplicados de la tabla combinada, ResourceContainers en este ejemplo, se anexan con 1. Como tabla ResourceContainers tiene tipos para suscripciones y grupos de recursos, puede usarse cualquier tipo para unirse al recurso de tabla Resources.

Resources
| join ResourceContainers on subscriptionId
| limit 1

En la consulta siguiente se muestra un uso más complejo de join. En primer lugar, la consulta usa project para obtener los campos Resources para el tipo de recurso almacenes de Azure Key Vault. En el paso siguiente se usa join para combinar los resultados con ResourceContainers, donde el tipo es una suscripción en una propiedad que se encuentra en el elemento project de la primera tabla y en el elemento project de la tabla combinada. El cambio de nombre del campo evita join agregarlo como nombre1 ya que la propiedad ya está proyectada desde Resources. El resultado de la consulta es un solo almacén de claves que muestra su tipo, nombre, ubicación y el grupo de recursos del almacén de claves, junto con el nombre de la suscripción en que se encuentra.

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

Nota

Al limitar los resultados de join con project, la propiedad utilizada por join para relacionar las dos tablas, subscriptionId en el ejemplo anterior, debe incluirse en project.

Propiedades extendidas

Como característica de versión preliminar, algunos de los tipos de recursos de Resource Graph tienen propiedades más relacionadas con tipos disponibles para consultar más allá de las propiedades proporcionadas por Azure Resource Manager. Este conjunto de valores, conocido como propiedades extendidas, existe en un tipo de recurso compatible con properties.extended. Para mostrar los tipos de recursos con propiedades extendidas, use la consulta siguiente:

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

Ejemplo: Obtenga el recuento de máquinas virtuales mediante instanceView.powerState.code:

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

Elementos del lenguaje personalizado de Resource Graph

Sintaxis de consulta compartida (versión preliminar)

Como característica en vista previa, se puede acceder directamente a una consulta compartida en una consulta de Resource Graph. Este escenario permite crear consultas estándar como consultas compartidas, así como reutilizarlas. Para llamar a una consulta compartida dentro de una consulta de Resource Graph, use la sintaxis {{shared-query-uri}}. El URI de la consulta compartida es el identificador de recurso de la consulta compartida en la página Configuración de dicha consulta. En este ejemplo, el URI de la consulta compartida es /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS. Este URI apunta a la suscripción, al grupo de recursos y al nombre completo de la consulta compartida a la que se desea hacer referencia en otra consulta. Esta consulta es la misma que la creada en Tutorial: Creación y uso compartido de una consulta.

Nota

No se puede guardar como consulta compartida una consulta que haga referencia a una consulta compartida.

Ejemplo 1: Usar solo la consulta compartida:

Los resultados de esta consulta de Resource Graph son los mismos que los de la consulta almacenada en la consulta compartida.

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

Ejemplo 2: Incluir la consulta compartida como parte de una consulta mayor:

En primer lugar, esta consulta usa la consulta compartida y, a continuación, usa limit para restringir aún más los resultados.

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

Elementos del lenguaje KQL admitidos

Resource Graph admite un subconjunto de todos los tipos de datos, funciones escalares, operadores escalares y funciones de agregado de KQL. Resource Graph admite operadores tabulares específicos, algunos de los cuales tienen comportamientos distintos.

Operadores de nivel superior o tabulares compatibles

Esta es la lista de operadores tabulares KQL admitidos por Resource Graph con ejemplos específicos:

KQL Consulta de ejemplo de Resource Graph Notas
count Contador de almacenes de claves
distinct Mostrar los recursos que contienen almacenamiento
extend Count virtual machines by OS type
join Almacén de claves con el nombre de la suscripción Tipos de combinación admitidos: innerunique, inner, leftouter, y fullouter. Límite de tres join en una sola consulta, una de las cuales podría ser una entre tablasjoin. Si todos las join tablas cruzada se usan entre Resource y ResourceContainers, se permiten tres join entre tablas. No se permiten las estrategias de combinación personalizadas, como la combinación de difusión. Para qué tablas pueden usar join, vaya a tablas de Resource Graph.
limit List all public IP addresses Sinónimo de take. No funciona con Skip.
mvexpand Operador heredado, use mv-expand en su lugar. Máximo de RowLimit de 400. El valor predeterminado es 128.
mv-expand Enumeración de Azure Cosmos DB con ubicaciones de escritura concretas Máximo de RowLimit de 400. El valor predeterminado es 128. Límite de 2 mv-expand en una sola consulta.
order List resources sorted by name Sinónimo de sort
parse Obtención de redes virtuales y subredes de interfaces de red Es óptimo acceder directamente a las propiedades si existen en lugar de usar parse.
project List resources sorted by name
project-away Eliminación de columnas de los resultados
sort List resources sorted by name Sinónimo de order
summarize Count Azure resources Solo la primera página simplificada
take List all public IP addresses Sinónimo de limit. No funciona con Skip.
top Show first five virtual machines by name and their OS type
union Combinación de los resultados de dos consultas para formar un solo resultado Tabla única permitida: | union [kind= inner|outer] [withsource=ColumnName] Table. Límite de tres union piernas en una sola consulta. No se permite la resolución aproximada de tablas de segmento union. Se puede usar en una sola tabla o entre las tablas Resources y ResourceContainers.
where Show resources that contain storage

Hay un límite predeterminado de tres join y tres operadores mv-expand en una sola consulta del SDK de Resource Graph. Puede solicitar un aumento de estos límites para el inquilino en Ayuda y soporte técnico.

Para admitir la experiencia de portalOpen Query, Azure Resource Graph Explorer tiene un límite global mayor que el SDK de Resource Graph.

Nota:

No se puede hacer referencia a una tabla como tabla correcta más de una vez, lo que excede el límite de 1. Si lo hace, recibirá un error con el código DisallowedMaxNumberOfRemoteTables.

Ámbito de la consulta

El ámbito de las suscripciones o grupos de administración desde los que una consulta devuelve los recursos tiene como valor predeterminado una lista de suscripciones en función del contexto del usuario autorizado. Si no se define un grupo de administración o una lista de suscripciones, el ámbito de consulta es todos los recursos e incluye recursos delegados de Azure Lighthouse.

La lista de suscripciones o grupos de administración que se va a consultar se puede definir manualmente para cambiar el ámbito de los resultados. Por ejemplo, la propiedad managementGroups de la API de REST toma el id. del grupo de administración, que es diferente del nombre del grupo de administración. Cuando se especifica managementGroups, se incluyen los recursos de las primeras 10000 suscripciones de la jerarquía de grupos de administración especificada. managementGroups no se puede usar al mismo tiempo que subscriptions.

Ejemplo: Consulte todos los recursos de la jerarquía del grupo de administración denominado My Management Group con el identificador myMG.

  • URI DE LA API REST

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

  • Cuerpo de la solicitud

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

El parámetro AuthorizationScopeFilter permite enumerar las asignaciones de Azure Policy y las asignaciones de roles de control de acceso basado en rol (RBAC de Azure) en la tabla AuthorizationResources que se heredan de ámbitos superiores. El parámetro AuthorizationScopeFilter acepta los siguientes valores para las tablas PolicyResources y AuthorizationResources:

  • AtScopeAndBelow (valor predeterminado si no se especifica): devuelve asignaciones para el ámbito especificado y todos los ámbitos secundarios.
  • AtScopeAndAbove: Devuelve asignaciones para el ámbito especificado y todos los ámbitos primarios, pero no los ámbitos secundarios.
  • AtScopeAboveAndBelow: devuelve asignaciones para el ámbito especificado, todos los ámbitos primarios y todos los ámbitos secundarios.
  • AtScopeExact: Devuelve asignaciones solo para el ámbito especificado; no se incluyen los ámbitos primarios o secundarios.

Nota:

Para usar el parámetro AuthorizationScopeFilter, asegúrese de usar el 2021-06-01-preview o una versión posterior de la API en las solicitudes.

Ejemplo: obtener todas las asignaciones de directivas del grupo de administración myMG y los ámbitos raíz del inquilino (primario).

  • URI DE LA API REST

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

  • Ejemplo de cuerpo de la solicitud

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

Ejemplo: obtenga todas las asignaciones de directivas de la suscripción mySubscriptionId, el grupo de administración y los ámbitos raíz del inquilino.

  • URI DE LA API REST

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

  • Ejemplo de cuerpo de la solicitud

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

Carácter de escape

Algunos nombres de propiedad, como los que incluyen . o $, debe encapsularse o escapar en la consulta para que se interprete correctamente; de lo contrario, no proporcionan los resultados previstos.

  • Punto (.): ajuste el nombre de la propiedad ['propertyname.withaperiod'] mediante corchetes.

    Consulta de ejemplo que encapsula la propiedad odata.type:

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

  • Signo de dólar ($): escape el carácter en el nombre de la propiedad. El carácter de escape usado depende del shell que ejecuta Resource Graph.

    • Bash: use una barra diagonal inversa (\) como carácter de escape.

      Consulta de ejemplo con escape de la propiedad $type en Bash:

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

    • cmd: no escape el carácter de signo de dólar ($).

    • PowerShell: use una barra trasera (`) como carácter de escape.

      Consulta de ejemplo con escape de la propiedad $type en PowerShell:

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

Pasos siguientes