Informazioni sul linguaggio di query di Azure Resource Graph

Il linguaggio di query di Azure Resource Graph supporta molti operatori e funzioni. ognuno dei quali opera in base al linguaggio di query Kusto (KQL). Per informazioni sul linguaggio di query usato da Resource Graph, iniziare con l'esercitazione per KQL.

Questo articolo illustra i componenti del linguaggio supportati da Resource Graph:

• Comprendere il linguaggio di query di Azure Resource Graph
  • Tabelle di Resource Graph
  • Extended properties
  • Elementi del linguaggio personalizzato di Resource Graph
    • Sintassi di query condivise (anteprima)
  • Elementi supportati del linguaggio KQL
    • Operatori tabulari/di livello superiore supportati
  • Query scope
  • Escape characters
  • Next steps

Tabelle di Resource Graph

Resource Graph offre diverse tabelle per i dati archiviati relative ai tipi di risorsa di Azure Resource Manager e alle relative proprietà. Le tabelle di Resource Graph possono essere usate con l'operatore join per ottenere proprietà dai tipi di risorse correlati.

Le tabelle di Resource Graph supportano le versioni join:

• innerunique
• inner
• leftouter
• fullouter

Per un elenco di tabelle che includono tipi di risorse, passare a Tabella di Azure Resource Graph e informazioni di riferimento sul tipo di risorsa.

Usare Resource Graph Explorer nel portale per individuare i tipi di risorsa disponibili in ogni tabella. In alternativa, usare una query, ad esempio <tableName> | distinct type, per ottenere un elenco dei tipi di risorsa supportati dalla tabella di Resource Graph specificata che sono presenti nell'ambiente in uso.

La query seguente include un operatore join semplice. The query result blends the columns together and any duplicate column names from the joined table, ResourceContainers in this example, are appended with 1. 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

La query seguente illustra un uso più complesso di join. Prima di tutto, la query usa project per ottenere i campi da Resources per il tipo di risorsa insiemi di credenziali di Azure Key Vault. 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. The field rename avoids join adding it as name1 since the property already is projected from Resources. Il risultato della query è un singolo insieme di credenziali delle chiavi che visualizza il tipo, il nome, la posizione e il gruppo di risorse dell'insieme di credenziali delle chiavi, insieme al nome della sottoscrizione in cui si trova.

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

Extended properties

As a preview feature, some of the resource types in Resource Graph have more type-related properties available to query beyond the properties provided by Azure Resource Manager. This set of values, known as extended properties, exists on a supported resource type in properties.extended. To show resource types with extended properties, use the following query:

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

Esempio: Ottenere il numero di macchine virtuali per instanceView.powerState.code:

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

Elementi del linguaggio personalizzato di Resource Graph

Sintassi di query condivise (anteprima)

As a preview feature, a shared query can be accessed directly in a Resource Graph query. Questo scenario consente di creare query standard come query condivise e riutilizzarle. Per chiamare una query condivisa all'interno di una query di Resource Graph, usare la sintassi {{shared-query-uri}}. The URI of the shared query is the Resource ID of the shared query on the Settings page for that query. In questo esempio l'URI della query condivisa è /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS. Questo URI punta alla sottoscrizione, al gruppo di risorse e al nome completo della query condivisa a cui si vuole fare riferimento in un'altra query. Questa query corrisponde a quella creata in Esercitazione: Creare e condividere una query.

Esempio 1: usare solo la query condivisa:

I risultati di questa query di Resource Graph corrispondono alla query archiviata nella query condivisa.

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

Esempio 2: includere la query condivisa come parte di una query più grande:

Questa query usa prima la query condivisa e quindi usa limit per limitare ulteriormente i risultati.

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

Elementi supportati del linguaggio KQL

Resource Graph supports a subset of KQL data types, scalar functions, scalar operators, and aggregation functions. Specific tabular operators are supported by Resource Graph, some of which have different behaviors.

Operatori tabulari/di livello superiore supportati

Di seguito è riportato l'elenco degli operatori tabulari di KQL supportati da Resource Graph con esempi specifici:

Esiste un limite predefinito di tre join e tre operatori mv-expand in una singola query di Resource Graph SDK. È possibile richiedere un aumento di questi limiti per il tenant tramite Guida e supporto.

To support the Open Query portal experience, Azure Resource Graph Explorer has a higher global limit than Resource Graph SDK.

Query scope

The scope of the subscriptions or management groups from which resources are returned by a query defaults to a list of subscriptions based on the context of the authorized user. If a management group or a subscription list isn't defined, the query scope is all resources, and includes Azure Lighthouse delegated resources.

L'elenco di sottoscrizioni o gruppi di gestione su cui eseguire una query può essere definito manualmente per modificare l'ambito dei risultati. Ad esempio, la proprietà dell'API REST managementGroups accetta l'ID del gruppo di gestione, che è diverso dal nome del gruppo di gestione. Quando si specifica managementGroups, vengono incluse le risorse delle prime 10.000 sottoscrizioni all'interno o al di sotto della gerarchia del gruppo di gestione specificata. managementGroups non può essere usato contemporaneamente a subscriptions.

Esempio: eseguire una query su tutte le risorse all'interno della gerarchia del gruppo di gestione denominato My Management Group con ID myMG.

• URI DELL'API REST

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

• Request Body

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

Il parametro AuthorizationScopeFilter consente di elencare le assegnazioni di Criteri di Azure e le assegnazioni di ruolo di Controllo degli accessi in base al ruolo di Azure nella tabella AuthorizationResources, ereditate dagli ambiti superiori. Il parametro AuthorizationScopeFilter accetta i valori seguenti per le tabelle PolicyResources e AuthorizationResources:

• AtScopeAndBelow (default if not specified): Returns assignments for the given scope and all child scopes.
• AtScopeAndAbove: Returns assignments for the given scope and all parent scopes, but not child scopes.
• AtScopeAboveAndBelow: Returns assignments for the given scope, all parent scopes, and all child scopes.
• AtScopeExact: Returns assignments only for the given scope; no parent or child scopes are included.

Example: Get all policy assignments at the myMG management group and Tenant Root (parent) scopes.

• URI DELL'API REST

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

• Esempio di corpo della richiesta

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

Example: Get all policy assignments at the mySubscriptionId subscription, management group, and Tenant Root scopes.

• URI DELL'API REST

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

• Esempio di corpo della richiesta

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

Escape characters

Alcuni nomi di proprietà, ad esempio quelli che includono . o $, devono essere sottoposti a wrapping o preceduti da caratteri di escape nella query, altrimenti il nome della proprietà viene interpretato in modo errato e non vengono generati i risultati previsti.

• Punto (.): eseguire il wrapping del nome della proprietà ['propertyname.withaperiod'] usando parentesi quadre.

  Example query that wraps the property odata.type:

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

• Segno di dollaro ($): escape del carattere nel nome della proprietà. Il carattere di escape usato dipende dalla shell da cui viene eseguito Resource Graph.

  • Bash: Use a backslash (\) as the escape character.

    Example query that escapes the property $type in Bash:

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

  • cmd: Don't escape the dollar sign ($) character.

  • PowerShell: Use a backtick (`) as the escape character.

    Example query that escapes the property $type in PowerShell:

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

Next steps

• Azure Resource Graph query language Starter queries and Advanced queries.
• Altre informazioni su come esplorare le risorse di Azure.