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:

• Informazioni sul linguaggio di query di Azure Resource Graph
  • Tabelle di Resource Graph
  • Proprietà estese
  • Elementi del linguaggio personalizzato di Resource Graph
    • Sintassi di query condivise (anteprima)
  • Elementi supportati del linguaggio KQL
    • Operatori tabulari/di livello superiore supportati
  • Ambito delle query
  • Caratteri di escape
  • Passaggi successivi

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. Il risultato della query combina insieme le colonne e a tutti i nomi di colonna duplicati della tabella unita in join, ResourceContainers in questo esempio, viene aggiunto 1. Poiché la tabella ResourceContainers contiene tipi sia per le sottoscrizioni sia per i gruppi di risorse, è possibile usare entrambi i tipi per creare un join con la risorsa dalla tabella Resources.

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. Il passaggio successivo usa join per unire i risultati con ResourceContainers in cui il tipo è una sottoscrizione su una proprietà che si trova sia in project della prima tabella che in project della tabella unità. La ridenominazione del campo evita join aggiungendolo come name1 poiché la proprietà è già proiettata da 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

Proprietà estese

Come funzionalità di anteprima, alcuni dei tipi di risorse in Resource Graph hanno più proprietà correlate ai tipi disponibili per eseguire query oltre a quelle fornite da Azure Resource Manager. Questo set di valori, noto come proprietà estese, esiste in un tipo di risorsa supportato in properties.extended. Per visualizzare i tipi di risorse con proprietà estese, usare la query seguente:

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)

Come funzionalità di anteprima, è possibile accedere a una query condivisa direttamente in una query di Resource Graph. 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}}. L'URI della query condivisa è l'ID risorsa della query condivisa nella pagina Impostazioni per tale 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 supporta un subset di tipi di dati, funzioni scalari, operatori scalari e funzioni di aggregazione di KQL. Resource Graph supporta operatori tabulari specifici, alcuni dei quali con comportamenti diversi.

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.

Per supportare l'esperienza del portale Open Query, Azure Resource Graph Explorer ha un limite globale superiore rispetto a Resource Graph SDK.

Ambito delle query

L'ambito delle sottoscrizioni o dei gruppi di gestione da cui le risorse vengono restituite per impostazione predefinita da una query a un elenco di sottoscrizioni in base al contesto dell'utente autorizzato. Se un gruppo di gestione o un elenco di sottoscrizioni non è definito, l'ambito della query include tutte le risorse così come le risorse delegate di Azure Lighthouse.

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
  

• Corpo della richiesta

  {
    "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 (impostazione predefinita, se non specificata): restituisce le assegnazioni per l'ambito specificato e tutti gli ambiti figlio.
• AtScopeAndAbove: restituisce le assegnazioni per l'ambito specificato e tutti gli ambiti padre, ma non gli ambiti figlio.
• AtScopeAboveAndBelow: restituisce le assegnazioni per l'ambito specificato, tutti gli ambiti padre e tutti gli ambiti figlio.
• AtScopeExact: restituisce le assegnazioni solo per l'ambito specificato; non sono inclusi ambiti padre o figlio.

Esempio: ottenere tutte le assegnazioni di criteri negli ambiti myMG e Radice tenant (padre).

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

Esempio: ottenere tutte le assegnazioni di criteri negli ambiti della sottoscrizione mySubscriptionId, del gruppo di gestione e della radice tenant.

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

Caratteri di escape

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.

  Query di esempio con wrapping della proprietà 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: usare una barra rovesciata (\) come carattere di escape.

    Query di esempio con carattere di escape per la proprietà $type in bash:

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

  • cmd: non inserire un escape con il carattere del simbolo del dollaro ($).

  • PowerShell: usare un backtick (`) come carattere di escape.

    Query di esempio con carattere di escape per la proprietà $type in PowerShell:

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

Passaggi successivi

• Query starter e query avanzate del linguaggio di query di Azure Resource Graph.
• Altre informazioni su come esplorare le risorse di Azure.