Informazioni sul linguaggio di query di Azure Resource Graph

  • Articolo

Il linguaggio di query per 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:

Tabelle di Resource Graph

Resource Graph fornisce diverse tabelle per i dati archiviati sui tipi di risorse di Azure Resource Manager e sulle 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 join versioni:

Tabella di Resource Graph È possibile join usare altre tabelle? Descrizione
AdvisorResources Sì Include le risorse relative a Microsoft.Advisor.
AlertsManagementResources Sì Include le risorse relative a Microsoft.AlertsManagement.
AppServiceResources Sì Include le risorse relative a Microsoft.Web.
AuthorizationResources Sì Include le risorse relative a Microsoft.Authorization.
AWSResources Sì Include le risorse relative a Microsoft.AwsConnector.
AzureBusinessContinuityResources Sì Include le risorse relative a Microsoft.AzureBusinessContinuity.
ChaosResources Sì Include le risorse relative a Microsoft.Chaos.
CommunityGalleryResources Sì Include le risorse relative a Microsoft.Compute.
ComputeResources Sì Include le risorse correlate alle Microsoft.Compute set di scalabilità di macchine virtuali.
DesktopVirtualizationResources Sì Include le risorse relative a Microsoft.DesktopVirtualization.
DnsResources Sì Include le risorse relative a Microsoft.Network.
EdgeOrderResources Sì Include le risorse relative a Microsoft.EdgeOrder.
ElasticsanResources Sì Include le risorse relative a Microsoft.ElasticSan.
ExtendedLocationResources Sì Include le risorse relative a Microsoft.ExtendedLocation.
FeatureResources Sì Include le risorse relative a Microsoft.Features.
GuestConfigurationResources Sì Include le risorse relative a Microsoft.GuestConfiguration.
HealthResourceChanges Sì Include le risorse relative a Microsoft.Resources.
HealthResources Sì Include le risorse relative a Microsoft.ResourceHealth.
InsightsResources Sì Include le risorse relative a Microsoft.Insights.
IoTSecurityResources Sì Include le risorse correlate a Microsoft.IoTSecurity e Microsoft.IoTFirmwareDefense.
KubernetesConfigurationResources Sì Include le risorse relative a Microsoft.KubernetesConfiguration.
KustoResources Sì Include le risorse relative a Microsoft.Kusto.
MaintenanceResources Sì Include le risorse relative a Microsoft.Maintenance.
ManagedServicesResources Sì Include le risorse relative a Microsoft.ManagedServices.
MigrateResources Sì Include le risorse relative a Microsoft.OffAzure.
NetworkResources Sì Include le risorse relative a Microsoft.Network.
OrbitalResources Sì Include le risorse relative a Microsoft.Orbital.
PatchAssessmentResources Sì Include risorse correlate alla valutazione Microsoft.Compute delle patch di Azure Macchine virtuali e Microsoft.HybridCompute.
PatchInstallationResources Sì Include le risorse correlate all'installazione Microsoft.Compute delle patch di Azure Macchine virtuali e Microsoft.HybridCompute.
PolicyResources Sì Include le risorse relative a Microsoft.PolicyInsights.
RecoveryServicesResources Sì Include le risorse correlate a Microsoft.DataProtection e Microsoft.RecoveryServices.
ResourceChanges Sì Include le risorse relative a Microsoft.Resources.
ResourceContainerChanges Sì Include le risorse relative a Microsoft.Resources.
ResourceContainers Sì Include i tipi di risorse e i dati del gruppo di risorse (), della sottoscrizione (Microsoft.Management/managementGroupsMicrosoft.Resources/subscriptions) e del gruppo di risorse (Microsoft.Resources/subscriptions/resourcegroups).
Risorse Sì Tabella predefinita se una tabella non è definita nella query. In questa tabella sono contenuti quasi tutti i tipi di risorsa di Resource Manager e le relative proprietà.
SecurityResources Sì Include le risorse relative a Microsoft.Security.
ServiceFabricResources Sì Include le risorse relative a Microsoft.ServiceFabric.
ServiceHealthResources Sì Include le risorse relative a Microsoft.ResourceHealth/events.
SpotResources Sì Include le risorse relative a Microsoft.Compute.
SupportResources Sì Include le risorse relative a Microsoft.Support.
TagsResources Sì Include le risorse relative a Microsoft.Resources/tagnamespaces.

Per un elenco di tabelle che includono i tipi di risorse, passare alla tabella di Azure Resource Graph e al riferimento al tipo di risorsa.

Nota

Resources è la tabella predefinita. Durante l'esecuzione di query sulla Resources tabella, non è necessario specificare il nome della tabella, a meno che join non venga usato o union . Tuttavia, la procedura consigliata consiste nell'includere sempre la tabella iniziale nella query.

Per individuare i tipi di risorse disponibili in ogni tabella, usare Resource Graph Explorer nel portale. 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 ha tipi sia per le sottoscrizioni che per i gruppi di risorse, entrambi i tipi possono essere usati per l'aggiunta alla risorsa dalla Resources tabella.

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 in una proprietà che si trova sia nella prima tabella project che nella tabella projectunita a join. La ridenominazione del campo evita join di aggiungerla come name1 perché 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

Nota

Quando si limitano i risultati di join con project, la proprietà usata da join per correlare le due tabelle, subscriptionId nell'esempio precedente, deve essere inclusa in project.

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 le proprietà 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 conteggio delle 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 {{shared-query-uri}} sintassi . 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 è identica a quella creata in Esercitazione: Creare e condividere una query.

Nota

Non è possibile salvare una query che fa riferimento a una query condivisa come query condivisa.

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 KQL, funzioni scalari, operatori scalari e funzioni di aggregazione. Resource Graph supporta operatori tabulari specifici, alcuni dei quali con comportamenti diversi.

Operatori tabulari/di livello superiore supportati

Ecco l'elenco degli operatori tabulari KQL supportati da Resource Graph con esempi specifici:

KQL Query di esempio di Resource Graph Note
count Contare gli insiemi di credenziali delle chiavi
distinct Mostrare le risorse che contengono archivi
extend Contare le macchine virtuali per tipo di sistema operativo
join Insieme di credenziali delle chiavi con il nome della sottoscrizione Tipi di join supportati: innerunique, inner, leftouter e fullouter. Limite di tre join in una singola query, uno dei quali potrebbe essere una tabella joinincrociata. Se l'uso tra più tabelle join è compreso tra Resource e ResourceContainers, sono consentite tre tabelle incrociatejoin. Strategie di join personalizzate, ad esempio il join di trasmissione, non sono consentite. Per le tabelle che possono usare join, passare a Tabelle di Resource Graph.
limit Elencare tutti gli indirizzi IP pubblici Sinonimo di take. Non funziona con Skip.
mvexpand Operatore legacy. In sostituzione usare mv-expand. RowLimit max 400. Il valore predefinito è 128.
mv-expand Elencare Azure Cosmos DB con posizioni di scrittura specifiche RowLimit max 400. Il valore predefinito è 128. Limite di 2 mv-expand in una singola query.
order Elencare le risorse ordinate per nome Sinonimo di sort
parse Ottenere reti virtuali e subnet delle interfacce di rete È consigliabile accedere direttamente alle proprietà se esistenti anziché usare parse.
project Elencare le risorse ordinate per nome
project-away Rimuovere colonne dai risultati
ordinamento Elencare le risorse ordinate per nome Sinonimo di order
summarize Contare le risorse di Azure Solo prima pagina semplificata
take Elencare tutti gli indirizzi IP pubblici Sinonimo di limit. Non funziona con Skip.
top Mostrare le prime cinque macchine virtuali per nome e tipo di sistema operativo
union Combinare i risultati di due query in un singolo risultato Tabella singola consentita: | union [kind= inner|outer] [withsource=ColumnName] Table. Limite di tre union gambe in una singola query. La risoluzione fuzzy di tabelle di code union non è consentita. Può essere usato all'interno di una singola tabella o tra le tabelle Resources e ResourceContainers .
where Mostrare le risorse che contengono archivi

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

Per supportare l'esperienza open query portal, Azure Resource Graph Explorer ha un limite globale superiore rispetto a Resource Graph SDK.

Nota

Non è possibile fare riferimento a una tabella come tabella corretta più volte, che supera il limite di 1. In questo caso, viene visualizzato un errore con codice DisallowedMaxNumberOfRemoteTables.

Ambito delle query

L'ambito delle sottoscrizioni o dei gruppi di gestione da cui le risorse vengono restituite per impostazione predefinita da una query è 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 è tutte le risorse e include 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 managementGroups REST accetta l'ID del gruppo di gestione, che è diverso dal nome del gruppo di gestione. Quando managementGroups viene specificato, vengono incluse le risorse delle prime 10.000 sottoscrizioni in o nella 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 AuthorizationScopeFilter parametro 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 AuthorizationResources tabella ereditate dagli ambiti superiori. Il AuthorizationScopeFilter parametro accetta i valori seguenti per le PolicyResources tabelle 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 per 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.

Nota

Per usare il AuthorizationScopeFilter parametro , assicurarsi di usare la versione 2021-06-01-preview o successiva dell'API nelle richieste.

Esempio: ottenere tutte le assegnazioni di criteri negli ambiti di gestione 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 nella sottoscrizione mySubscriptionId, nel gruppo di gestione e negli ambiti radice del 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 ['propertyname.withaperiod'] della proprietà 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 che esegue Resource Graph.

    • Bash: usare una barra rovesciata (\) come carattere di escape.

      Query di esempio che esegue l'escape della proprietà $type in Bash:

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

    • cmd: non sfuggire al simbolo del dollaro ($).

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

      Query di esempio che esegue l'escape della proprietà $type in PowerShell:

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

Passaggi successivi