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. Algunas tablas se pueden utilizar con los operadores join o union para obtener propiedades de tipos de recursos relacionados. Esta es la lista de tablas disponibles en Resource Graph:

Tabla de Resource Graph ¿Se puede usar join con otras tablas? Descripción
Recursos Sí La tabla predeterminada, si no se ha definido ninguna en la consulta. La mayoría de los tipos de recursos y propiedades de Resource Manager están aquí.
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.
AdvisorResources Sí (versión preliminar) Incluye recursos relacionados con Microsoft.Advisor.
AlertsManagementResources Sí (versión preliminar) Incluye recursos relacionados con Microsoft.AlertsManagement.
DesktopVirtualizationResources Sí Incluye recursos relacionados con Microsoft.DesktopVirtualization.
ExtendedLocationResources No Incluye recursos relacionados con Microsoft.ExtendedLocation.
GuestConfigurationResources No Incluye recursos relacionados con Microsoft.GuestConfiguration.
HealthResources Sí (versión preliminar) Incluye recursos relacionados con Microsoft.ResourceHealth/availabilitystatuses.
IoTSecurityResources No Incluye recursos relacionados con Microsoft.IoTSecurity.
KubernetesConfigurationResources No Incluye recursos relacionados con Microsoft.KubernetesConfiguration.
MaintenanceResources Parcial, solo conectar con. (versión preliminar) Incluye recursos relacionados con Microsoft.Maintenance.
PatchAssessmentResources No Incluye los recursos relacionados con la evaluación de revisiones de Azure Virtual Machines.
PatchInstallationResources No Incluye los recursos relacionados con la instalación de revisiones de Azure Virtual Machines.
PolicyResources Sí Incluye recursos relacionados con Microsoft.PolicyInsights.
RecoveryServicesResources Parcial, solo unirse con. (versión preliminar) Incluye recursos relacionados con Microsoft.DataProtection y Microsoft.RecoveryServices.
SecurityResources Sí (versión preliminar) Incluye recursos relacionados con Microsoft.Security.
ServiceHealthResources No (vista previa) Incluye recursos relacionados con Microsoft.ResourceHealth/events.
WorkloadMonitorResources No Incluye recursos relacionados con Microsoft.WorkloadMonitor.

Para ver una lista completa, incluidos los tipos de recursos, consulte Referencia: tablas y tipos de recursos admitidos.

Nota

Recursos es la tabla predeterminada. Al consultar la tabla Recursos, no es necesario proporcionar el nombre de la tabla a menos que se utilicen join o union. Sin embargo, el procedimiento recomendado es incluir siempre la tabla inicial en la consulta.

Use Azure Resource Graph en el portal para detectar qué tipos de recursos están disponibles en cada tabla. 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 la tabla ResourceContainers tiene tipos para suscripciones y grupos de recursos, se puede usar cualquier tipo para unirse al recurso desde la 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 de Resources para el tipo de recurso de los 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 que join lo agregue como name1, ya que el campo ya se encuentra en el elemento project de 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 en vista previa, algunos de los tipos de recursos de Resource Graph tienen más propiedades relacionadas con el tipo que se pueden consultar de manera adicional a 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 ver qué tipos de recursos tienen propiedades extendidas, use la siguiente consulta:

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: Solo de la consulta compartida únicamente

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: Inclusión de la consulta compartida como parte de una 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 de 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. Límite de 3 join en una sola consulta, 1 de los cuales puede ser un elemento join entre tablas. Si todos los usos de join entre tablas se realiza entre Resources 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 conocer las tablas que pueden usar join, consulte 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 Se permite una sola tabla: T| union [kind=inner|outer] [withsource=ColumnName] Table. Límite de 3 partes de union 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 3 operadores join y 3 operadores mv-expand en una única 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 del portal "Abrir consulta", el explorador de Azure Resource Graph tiene un límite global más alto que el SDK de Resource Graph.

Á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 la consulta comprenderá todos los recursos, incluidos los 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 que cuenta con el id. 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 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 ni secundarios

Nota

Para usar el parámetro AuthorizationScopeFilter, asegúrese de usar la versión 2021-06-01-preview o 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.

  • . -Encapsule el nombre de propiedad como en: ['propertyname.withaperiod']

    Consulta de ejemplo que encapsula la propiedad odata.type:

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

  • $ -Incluya un carácter de escape en el nombre de propiedad. El carácter de escape usado depende del shell que ejecuta Resource Graph.

    • bash - \

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

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

    • cmd -no escapa el carácter $.

    • PowerShell - `

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

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

Pasos siguientes