Información del lenguaje de consulta de Azure Resource GraphUnderstanding the Azure Resource Graph query language

El lenguaje de consulta de Azure Resource Graph admite numerosos operadores y funciones.The query language for the Azure Resource Graph supports a number of operators and functions. Cada uno funciona en función del lenguaje de consulta de Kusto (KQL).Each work and operate based on Kusto Query Language (KQL). Para información sobre el lenguaje de consulta usado por Resource Graph, comience con el tutorial para KQL.To learn about the query language used by Resource Graph, start with the tutorial for KQL.

En este artículo se tratan los componentes de idioma admitidos por Resource Graph:This article covers the language components supported by Resource Graph:

Tablas de Resource GraphResource Graph tables

Resource Graph proporciona varias tablas para los datos que almacena sobre los tipos de recursos de Azure Resource Manager y sus propiedades.Resource Graph provides several tables for the data it stores about Azure Resource Manager resource types and their properties. Algunas tablas se pueden utilizar con los operadores join o union para obtener propiedades de tipos de recursos relacionados.Some tables can be used with join or union operators to get properties from related resource types. Esta es la lista de tablas disponibles en Resource Graph:Here is the list of tables available in Resource Graph:

Tabla de Resource GraphResource Graph table ¿Se puede usar join con otras tablas?Can join other tables? DescripciónDescription
RecursosResources Yes La tabla predeterminada, si no se ha definido ninguna en la consulta.The default table if none defined in the query. La mayoría de los tipos de recursos y propiedades de Resource Manager están aquí.Most Resource Manager resource types and properties are here.
ResourceContainersResourceContainers Yes Incluye los datos y los tipos de recursos de suscripción (en versión preliminar: Microsoft.Resources/subscriptions) y grupo de recursos (Microsoft.Resources/subscriptions/resourcegroups).Includes subscription (in preview -- Microsoft.Resources/subscriptions) and resource group (Microsoft.Resources/subscriptions/resourcegroups) resource types and data.
AdvisorResourcesAdvisorResources Sí (versión preliminar)Yes (preview) Incluye recursos relacionados con Microsoft.Advisor.Includes resources related to Microsoft.Advisor.
AlertsManagementResourcesAlertsManagementResources Sí (versión preliminar)Yes (preview) Incluye recursos relacionados con Microsoft.AlertsManagement.Includes resources related to Microsoft.AlertsManagement.
GuestConfigurationResourcesGuestConfigurationResources NoNo Incluye recursos relacionados con Microsoft.GuestConfiguration.Includes resources related to Microsoft.GuestConfiguration.
MaintenanceResourcesMaintenanceResources Parcial, solo conectar con.Partial, join to only. (versión preliminar)(preview) Incluye recursos relacionados con Microsoft.Maintenance.Includes resources related to Microsoft.Maintenance.
PatchAssessmentResourcesPatchAssessmentResources NoNo Incluye los recursos relacionados con la evaluación de revisiones de Azure Virtual Machines.Includes resources related to Azure Virtual Machines patch assessment.
PatchInstallationResourcesPatchInstallationResources NoNo Incluye los recursos relacionados con la instalación de revisiones de Azure Virtual Machines.Includes resources related to Azure Virtual Machines patch installation.
PolicyResourcesPolicyResources NoNo Incluye recursos relacionados con Microsoft.PolicyInsights.Includes resources related to Microsoft.PolicyInsights. (Versión preliminar)(Preview)
RecoveryServicesResourcesRecoveryServicesResources Parcial, solo unirse con.Partial, join to only. (versión preliminar)(preview) Incluye recursos relacionados con Microsoft.DataProtection y Microsoft.RecoveryServices.Includes resources related to Microsoft.DataProtection and Microsoft.RecoveryServices.
SecurityResourcesSecurityResources Parcial, solo unirse con.Partial, join to only. (versión preliminar)(preview) Incluye recursos relacionados con Microsoft.Security.Includes resources related to Microsoft.Security.
ServiceHealthResourcesServiceHealthResources NoNo Incluye recursos relacionados con Microsoft.ResourceHealth.Includes resources related to Microsoft.ResourceHealth.

Para ver una lista completa, incluidos los tipos de recursos, consulte Referencia: tablas y tipos de recursos admitidos.For a complete list, including resource types, see Reference: Supported tables and resource types.

Nota

Recursos es la tabla predeterminada.Resources is the default table. Al consultar la tabla Recursos, no es necesario proporcionar el nombre de la tabla a menos que se utilicen join o union.While querying the Resources table, it isn't required to provide the table name unless join or union are used. Sin embargo, el procedimiento recomendado es incluir siempre la tabla inicial en la consulta.However, the recommended practice is to always include the initial table in the query.

Use Azure Resource Graph en el portal para detectar qué tipos de recursos están disponibles en cada tabla.Use Resource Graph Explorer in the portal to discover what resource types are available in each table. 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.As an alternative, use a query such as <tableName> | distinct type to get a list of resource types the given Resource Graph table supports that exist in your environment.

En la consulta siguiente se muestra un uso sencillo de join.The following query shows a simple 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.The query result blends the columns together and any duplicate column names from the joined table, ResourceContainers in this example, are appended with 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.As ResourceContainers table has types for both subscriptions and resource groups, either type might be used to join to the resource from Resources table.

Resources
| join ResourceContainers on subscriptionId
| limit 1

En la consulta siguiente se muestra un uso más complejo de join.The following query shows a more complex use of 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.First, the query uses project to get the fields from Resources for the Azure Key Vault vaults resource type. 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.The next step uses join to merge the results with ResourceContainers where the type is a subscription on a property that is both in the first table's project and the joined table's project. 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.The field rename avoids join adding it as name1 since the property already is projected from 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.The query result is a single key vault displaying type, the name, location, and resource group of the key vault, along with the name of the subscription it's in.

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.When limiting the join results with project, the property used by join to relate the two tables, subscriptionId in the above example, must be included in project.

Propiedades extendidas (versión preliminar)Extended properties (preview)

Como característica en vista previa, algunos de los tipos de recursos de Resource Graph tienen propiedades adicionales relacionadas con el tipo que se pueden consultar de manera adicional a las propiedades proporcionadas por Azure Resource Manager.As a preview feature, some of the resource types in Resource Graph have additional type-related properties available to query beyond the properties provided by Azure Resource Manager. Este conjunto de valores, conocido como propiedades extendidas, existe en un tipo de recurso compatible con properties.extended.This set of values, known as extended properties, exists on a supported resource type in properties.extended. Para ver qué tipos de recursos tienen propiedades extendidas, use la siguiente consulta:To see which resource types have extended properties, use the following query:

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

Ejemplo: Obtenga el recuento de máquinas virtuales mediante instanceView.powerState.code:Example: Get count of virtual machines by instanceView.powerState.code:

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

Elementos del lenguaje personalizado de Resource GraphResource Graph custom language elements

Sintaxis de consulta compartida (versión preliminar)Shared query syntax (preview)

Como característica en vista previa, se puede acceder directamente a una consulta compartida en una consulta de Resource Graph.As a preview feature, a shared query can be accessed directly in a Resource Graph query. Este escenario permite crear consultas estándar como consultas compartidas, así como reutilizarlas.This scenario makes it possible to create standard queries as shared queries and reuse them. Para llamar a una consulta compartida dentro de una consulta de Resource Graph, use la sintaxis {{shared-query-uri}}.To call a shared query inside a Resource Graph query, use the {{shared-query-uri}} syntax. El URI de la consulta compartida es el identificador de recurso de la consulta compartida en la página Configuración de dicha consulta.The URI of the shared query is the Resource ID of the shared query on the Settings page for that query. 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.In this example, our shared query URI is /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.This URI points to the subscription, resource group, and full name of the shared query we want to reference in another query. Esta consulta es la misma que la creada en Tutorial: Creación y uso compartido de una consulta.This query is the same as the one created in Tutorial: Create and share a query.

Nota

No se puede guardar como consulta compartida una consulta que haga referencia a una consulta compartida.You can't save a query that references a shared query as a shared query.

Ejemplo 1: Solo de la consulta compartida únicamenteExample 1: Use only the shared query

Los resultados de esta consulta de Resource Graph son los mismos que los de la consulta almacenada en la consulta compartida.The results of this Resource Graph query are the same as the query stored in the shared query.

{{/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 mayorExample 2: Include the shared query as part of a larger query

En primer lugar, esta consulta usa la consulta compartida y, a continuación, usa limit para restringir aún más los resultados.This query first uses the shared query, and then uses limit to further restrict the results.

{{/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 admitidosSupported KQL language elements

Resource Graph admite un subconjunto de todos los tipos de datos, funciones escalares, operadores escalares y funciones de agregado de KQL.Resource Graph supports a subset of KQL data types, scalar functions, scalar operators, and aggregation functions. Resource Graph admite operadores tabulares específicos, algunos de los cuales tienen comportamientos distintos.Specific tabular operators are supported by Resource Graph, some of which have different behaviors.

Operadores de nivel superior o tabulares compatiblesSupported tabular/top level operators

Esta es la lista de operadores tabulares de KQL admitidos por Resource Graph con ejemplos específicos:Here is the list of KQL tabular operators supported by Resource Graph with specific samples:

KQLKQL Consulta de ejemplo de Resource GraphResource Graph sample query NotasNotes
countcount Contador de almacenes de clavesCount key vaults
distinctdistinct Mostrar los recursos que contienen almacenamientoShow resources that contain storage
extendextend Count virtual machines by OS typeCount virtual machines by OS type
joinjoin Almacén de claves con el nombre de la suscripciónKey vault with subscription name Tipos de combinación admitidos: innerunique, inner, leftouter.Join flavors supported: innerunique, inner, leftouter. Límite de 3 join en una sola consulta, 1 de los cuales puede ser un elemento join entre tablas.Limit of 3 join in a single query, 1 of which may be a cross-table join. Si todos los usos de join entre tablas se realiza entre Resources y ResourceContainers, se permiten tres join entre tablas.If all cross-table join use is between Resource and ResourceContainers, then 3 cross-table join are allowed. No se permiten las estrategias de combinación personalizadas, como la combinación de difusión.Custom join strategies, such as broadcast join, aren't allowed. Para conocer las tablas que pueden usar join, consulte Tablas de Resource Graph.For which tables can use join, see Resource Graph tables.
limitlimit List all public IP addressesList all public IP addresses Sinónimo de take.Synonym of take. No funciona con Skip.Doesn't work with Skip.
mvexpandmvexpand Operador heredado, use mv-expand en su lugar.Legacy operator, use mv-expand instead. Máximo de RowLimit de 400.RowLimit max of 400. El valor predeterminado es 128.The default is 128.
mv-expandmv-expand Enumeración de Cosmos DB con ubicaciones de escritura concretasList Cosmos DB with specific write locations Máximo de RowLimit de 400.RowLimit max of 400. El valor predeterminado es 128.The default is 128. Límite de 3 mv-expand en una sola consulta.Limit of 3 mv-expand in a single query.
orderorder List resources sorted by nameList resources sorted by name Sinónimo de sortSynonym of sort
projectproject List resources sorted by nameList resources sorted by name
project-awayproject-away Eliminación de columnas de los resultadosRemove columns from results
sortsort List resources sorted by nameList resources sorted by name Sinónimo de orderSynonym of order
summarizesummarize Count Azure resourcesCount Azure resources Solo la primera página simplificadaSimplified first page only
taketake List all public IP addressesList all public IP addresses Sinónimo de limit.Synonym of limit. No funciona con Skip.Doesn't work with Skip.
toptop Show first five virtual machines by name and their OS typeShow first five virtual machines by name and their OS type
unionunion Combinación de los resultados de dos consultas para formar un solo resultadoCombine results from two queries into a single result Tabla única permitida: T | union [kind= inner|outer] [withsource=nombreDeColumna] tabla.Single table allowed: T | union [kind= inner|outer] [withsource=ColumnName] Table. Límite de 3 partes de union en una sola consulta.Limit of 3 union legs in a single query. No se permite la resolución aproximada de tablas de segmento union.Fuzzy resolution of union leg tables isn't allowed. Se puede usar en una sola tabla o entre las tablas Resources y ResourceContainers.May be used within a single table or between the Resources and ResourceContainers tables.
wherewhere Show resources that contain storageShow 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.There is a default limit of 3 join and 3 mv-expand operators in a single Resource Graph SDK query. Puede solicitar un aumento de estos límites para el inquilino en Ayuda y soporte técnico.You can request an increase in these limits for your tenant through Help + support.

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.To support the "Open Query" portal experience, Azure Resource Graph Explorer has a higher global limit than Resource Graph SDK.

Ámbito de la consultaQuery scope

El ámbito de las suscripciones desde las que una consulta devuelve los recursos depende del método de acceso a Resource Graph.The scope of the subscriptions from which resources are returned by a query depend on the method of accessing Resource Graph. La CLI de Azure y Azure PowerShell rellenan la lista de suscripciones que se van a incluir en la solicitud, en función del contexto del usuario autorizado.Azure CLI and Azure PowerShell populate the list of subscriptions to include in the request based on the context of the authorized user. Cada lista de suscripciones se puede definir manualmente con las suscripciones y los parámetros de suscripción, respectivamente.The list of subscriptions can be manually defined for each with the subscriptions and Subscription parameters, respectively. En la API de REST y en todos los demás SDK, la lista de suscripciones en las que se incluyen los recursos debe definirse explícitamente como parte de la solicitud.In REST API and all other SDKs, the list of subscriptions to include resources from must be explicitly defined as part of the request.

Como versión preliminar, la versión de API de REST 2020-04-01-preview agrega una propiedad para limitar el ámbito de la consulta a un grupo de administración.As a preview, REST API version 2020-04-01-preview adds a property to scope the query to a management group. Esta API de versión preliminar también hace que la propiedad de suscripción sea opcional.This preview API also makes the subscription property optional. 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, a los que puede acceder el usuario autenticado.If a management group or a subscription list isn't defined, the query scope is all resources, which includes Azure Lighthouse delegated resources, that the authenticated user can access. La nueva propiedad managementGroupId toma el id. del grupo de administración, que es diferente del nombre del grupo de administración.The new managementGroupId property takes the management group ID, which is different from the name of the management group. Cuando se especifica managementGroupId, se incluyen los recursos de las primeras 5000 suscripciones de la jerarquía de grupos de administración especificada.When managementGroupId is specified, resources from the first 5000 subscriptions in or under the specified management group hierarchy are included. managementGroupId no se puede usar al mismo tiempo que subscriptions.managementGroupId can't be used at the same time as subscriptions.

Ejemplo: Consulte todos los recursos de la jerarquía del grupo de administración denominado "Mi grupo de administración" que cuenta con el id. "myMG".Example: Query all resources within the hierarchy of the management group named 'My Management Group' with ID 'myMG'.

  • URI DE LA API RESTREST API URI

    POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2020-04-01-preview
    
  • Cuerpo de la solicitudRequest Body

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

Carácter de escapeEscape characters

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.Some property names, such as those that include a . or $, must be wrapped or escaped in the query or the property name is interpreted incorrectly and doesn't provide the expected results.

  • . -Encapsule el nombre de propiedad como en: ['propertyname.withaperiod']. - Wrap the property name as such: ['propertyname.withaperiod']

    Consulta de ejemplo que encapsula la propiedad odata.type:Example query that wraps the property odata.type:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.['odata.type']
    
  • $ -Incluya un carácter de escape en el nombre de propiedad.$ - Escape the character in the property name. El carácter de escape utilizado depende el shell desde donde se ejecute Resource Graph.The escape character used depends on the shell Resource Graph is run from.

    • bash - \bash - \

      Consulta de ejemplo con escape de la propiedad $type en bash:Example query that escapes the property $type in bash:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.\$type
      
    • cmd -no escapa el carácter $.cmd - Don't escape the $ character.

    • PowerShell - `PowerShell - `

      Consulta de ejemplo con escape de la propiedad $type en PowerShell:Example query that escapes the property $type in PowerShell:

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

Pasos siguientesNext steps