Présentation du langage de requête Azure Resource Graph

Le langage de requête pour Azure Resource Graph prend en charge plusieurs opérateurs et fonctions. Leur fonctionnement et leur utilisation s’appuient sur le langage de requête Kusto (KQL, Kusto Query Language). Pour en savoir plus sur le langage de requête utilisé par Resource Graph, commencez par suivre le tutoriel KQL.

Cet article traite des composants de langage pris en charge par Resource Graph :

• Présentation du langage de requête Azure Resource Graph
  • Tables Resource Graph
  • Propriétés étendues
  • Éléments de langage personnalisés Resource Graph
    • Syntaxe des requêtes partagées (préversion)
  • Éléments du langage KQL pris en charge
    • Opérateurs tabulaires/de niveau supérieur pris en charge
  • Étendue de requête
  • Caractères d’échappement
  • Étapes suivantes

Tables Resource Graph

Resource Graph fournit plusieurs tables contenant les données qu’il stocke sur les types de ressources Azure Resource Manager et leurs propriétés. Les tables Resource Graph peuvent être utilisées avec l'opérateur join pour obtenir des propriétés à partir de types de ressources associés.

Les tables Resource Graph prennent en charge les options join :

• innerunique
• inner
• leftouter
• fullouter

Table Resource Graph	Peut join d’autres tables ?	Description
AdvisorResources	Oui	Inclut les ressources associées à Microsoft.Advisor.
AlertsManagementResources	Oui	Inclut les ressources associées à Microsoft.AlertsManagement.
AppServiceResources	Oui	Inclut les ressources associées à Microsoft.Web.
AuthorizationResources	Oui	Inclut les ressources associées à Microsoft.Authorization.
AWSResources	Oui	Inclut les ressources associées à Microsoft.AwsConnector.
AzureBusinessContinuityResources	Oui	Inclut les ressources associées à Microsoft.AzureBusinessContinuity.
ChaosResources	Oui	Inclut les ressources associées à Microsoft.Chaos.
CommunityGalleryResources	Oui	Inclut les ressources associées à Microsoft.Compute.
ComputeResources	Oui	Inclut les ressources liées à Microsoft.Compute Virtual Machine Scale Sets.
DesktopVirtualizationResources	Oui	Inclut les ressources associées à Microsoft.DesktopVirtualization.
DnsResources	Oui	Inclut les ressources associées à Microsoft.Network.
EdgeOrderResources	Oui	Inclut les ressources associées à Microsoft.EdgeOrder.
ElasticsanResources	Oui	Inclut les ressources associées à Microsoft.ElasticSan.
ExtendedLocationResources	Oui	Inclut les ressources associées à Microsoft.ExtendedLocation.
FeatureResources	Oui	Inclut les ressources associées à Microsoft.Features.
GuestConfigurationResources	Oui	Inclut les ressources associées à Microsoft.GuestConfiguration.
HealthResourceChanges	Oui	Inclut les ressources associées à Microsoft.Resources.
HealthResources	Oui	Inclut les ressources associées à Microsoft.ResourceHealth.
InsightsResources	Oui	Inclut les ressources associées à Microsoft.Insights.
IoTSecurityResources	Oui	Comprend des ressources associées à Microsoft.IoTSecurity et Microsoft.IoTFirmwareDefense.
KubernetesConfigurationResources	Oui	Inclut les ressources associées à Microsoft.KubernetesConfiguration.
KustoResources	Oui	Inclut les ressources associées à Microsoft.Kusto.
MaintenanceResources	Oui	Inclut les ressources associées à Microsoft.Maintenance.
ManagedServicesResources	Oui	Inclut les ressources associées à Microsoft.ManagedServices.
MigrateResources	Oui	Inclut les ressources associées à Microsoft.OffAzure.
NetworkResources	Oui	Inclut les ressources associées à Microsoft.Network.
OrbitalResources	Oui	Inclut les ressources associées à Microsoft.Orbital.
PatchAssessmentResources	Oui	Comprend les ressources associées au patch d'évaluation des machines virtuelles Azure Microsoft.Compute et Microsoft.HybridCompute.
PatchInstallationResources	Oui	Comprend les ressources associées au patch d'installation des machines virtuelles Azure Microsoft.Compute et Microsoft.HybridCompute.
PolicyResources	Oui	Inclut les ressources associées à Microsoft.PolicyInsights.
RecoveryServicesResources	Oui	Comprend des ressources associées à Microsoft.DataProtection et Microsoft.RecoveryServices.
ResourceChanges	Oui	Inclut les ressources associées à Microsoft.Resources.
ResourceContainerChanges	Oui	Inclut les ressources associées à Microsoft.Resources.
ResourceContainers	Oui	Inclut les données et les types de ressources du groupe d’administration (Microsoft.Management/managementGroups), de l’abonnement (Microsoft.Resources/subscriptions) et du groupe de ressources (Microsoft.Resources/subscriptions/resourcegroups).
Ressources	Oui	La table par défaut s'applique si une table n'est pas définie dans la requête. Elle contient la plupart des types de ressources et propriétés Resource Manager.
SecurityResources	Oui	Inclut les ressources associées à Microsoft.Security.
ServiceFabricResources	Oui	Inclut les ressources associées à Microsoft.ServiceFabric.
ServiceHealthResources	Oui	Inclut les ressources associées à Microsoft.ResourceHealth/events.
SpotResources	Oui	Inclut les ressources associées à Microsoft.Compute.
SupportResources	Oui	Inclut les ressources associées à Microsoft.Support.
TagsResources	Oui	Inclut les ressources associées à Microsoft.Resources/tagnamespaces.

Pour obtenir la liste des tables qui incluent des types de ressources, accédez à la table Azure Resource Graph et à la référence de type de ressource.

Remarque

Resources est la table par défaut. Lorsque vous interrogez la table Resources, il n’est pas nécessaire d’indiquer le nom de la table, sauf si vous utilisez join ou union. Toutefois, la pratique recommandée consiste à toujours inclure la table initiale dans la requête.

Utilisez l’Explorateur Resource Graph dans le portail pour découvrir les types de ressources disponibles dans chaque table. Vous pouvez également utiliser une requête telle que <tableName> | distinct type pour obtenir la liste des types de ressources existant dans votre environnement, pris en charge par la table Resource Graph concernée.

La requête suivante illustre un opérateur join simple. Le résultat de la requête fusionne les colonnes, et le suffixe 1 est ajouté à tous les noms de colonnes dupliqués de la table jointe (ResourceContainers dans cet exemple). Comme la table ResourceContainers possède des types tant pour les abonnements que pour les groupes de ressources, les deux types peuvent être utilisés pour la jointure à la ressource à partir de la table Resources.

Resources
| join ResourceContainers on subscriptionId
| limit 1

La requête suivante illustre une utilisation plus complexe de l’opérateur join. Tout d’abord, la requête utilise project pour obtenir les champs de Resources pour le type de ressource coffre Azure Key Vault. L’étape suivante utilise join pour fusionner les résultats avec ResourceContainers, où le type est un abonnement sur une propriété qui se trouve à la fois dans le project de la première table et dans le project de la table jointe. Le renommage de champ évite que join l’ajoute en tant que name1, puisque la propriété est déjà projetée à partir de Resources. Le résultat de la requête est un coffre de clés unique affichant le type, le nom, l’emplacement et le groupe de ressources du coffre de clés, ainsi que le nom de l’abonnement dans lequel il se trouve.

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

Notes

Quand vous limitez les résultats de join avec project, la propriété utilisée par join pour associer les deux tables (subscriptionId dans l’exemple ci-dessus) doit être incluse dans project.

Propriétés étendues

En tant que fonctionnalité d'évaluation, certains types de ressources dans Resource Graph ont des propriétés supplémentaires liées au type, disponibles pour effectuer une requête au-delà des propriétés fournies par Azure Resource Manager. Cet ensemble de valeurs, connu sous le nom de propriétés étendues, existe sur un type de ressource pris en charge dans properties.extended. Pour montrer les types de ressources avec des propriétés étendues, utilisez la requête suivante :

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

Exemple : Obtenir le nombre total de machines virtuelles à l’aide de instanceView.powerState.code :

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

Éléments de langage personnalisés Resource Graph

Syntaxe des requêtes partagées (préversion)

La fonctionnalité d’évaluation requête partagée est accessible directement dans une requête Resource Graph. Ce scénario permet de créer des requêtes standard comme requêtes partagées et de les réutiliser. Pour appeler une requête partagée à l’intérieur d’une requête Resource Graph, utilisez la syntaxe {{shared-query-uri}}. L’URI de la requête partagée correspond à son ID de ressource sur la page Paramètres correspondante. Dans cet exemple, l’URI de la requête partagée est /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS. Il pointe vers l’abonnement, le groupe de ressources et le nom complet de la requête partagée à laquelle nous souhaitons faire référence dans une autre requête. Cette requête est identique à celle créée dans Tutoriel : Création et partage d’une requête.

Notes

Il n’est pas possible d’enregistrer comme requête partagée une requête qui fait référence à une requête partagée.

Exemple 1 : utilisez uniquement la requête partagée :

Les résultats de cette requête Resource Graph sont les mêmes que ceux de la requête stockée dans la requête partagée.

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

Exemple 2 : incluez la requête partagée dans une requête plus large :

Cette requête utilise d’abord la requête partagée, puis se sert de limit pour limiter encore les résultats.

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

Éléments du langage KQL pris en charge

Resource Graph prend en charge un sous-ensemble des types de données, fonctions scalaires, opérateurs scalaires et fonctions d’agrégation du langage KQL. Des opérateurs tabulaires spécifiques sont pris en charge par Resource Graph, dont certains présentent différents comportements.

Opérateurs tabulaires/de niveau supérieur pris en charge

voici la liste des opérateurs tabulaires KQL pris en charge par Resource Graph avec des exemples spécifiques :

KQL	Exemple de requête Resource Graph	Notes
count	Compter les coffres de clés
distinct	Afficher les ressources contenant storage
extend	Compter les machines virtuelles par type de système d’exploitation
join	Coffre de clés avec nom d’abonnement	variantes de jointure prises en charge : innerunique, inner, leftouter et fullouter. Limite de trois join dans une seule requête, dont l'une peut être une table croisée join. Si toutes les tables croisées join sont utilisées entre Resource et ResourceContainers, alors trois tables croisées join sont autorisées. Les stratégies de jointure personnalisées comme la jointure de diffusion ne sont pas autorisées. Pour savoir quelles tables peuvent utiliser join, consultez Tables Ressource Graph.
limit	Lister toutes les adresses IP publiques	Identique à take. Ne fonctionne pas avec Ignorer.
mvexpand		Opérateur hérité, utilisez mv-expand à la place. Valeur RowLimit maximale de 400. La valeur par défaut est 128.
mv-expand	Lister Azure Cosmos DB avec des emplacements d’écriture spécifiques	Valeur RowLimit maximale de 400. La valeur par défaut est 128. Limite de 2 mv-expand dans une requête unique.
order	Lister les ressources triées par nom	Identique à sort
parse	Obtenir les réseaux virtuels et les sous-réseaux des interfaces réseau	Il est préférable d’accéder directement aux propriétés, le cas échéant, au lieu d’utiliser parse.
project	Lister les ressources triées par nom
project-away	Supprimer des colonnes des résultats
sort	Lister les ressources triées par nom	Identique à order
summarize	Compter les ressources Azure	Première page simplifiée uniquement
take	Lister toutes les adresses IP publiques	Identique à limit. Ne fonctionne pas avec Ignorer.
top	Afficher les cinq premières machines virtuelles par nom et leur type de système d’exploitation
union	Combiner les résultats de deux requêtes en un résultat unique	Table unique autorisée : | union [kind= inner|outer] [withsource=ColumnName] Table. Limite de trois sections union dans une seule requête. La résolution approximative des tables avec sections union n’est pas autorisée. Peut être utilisé dans une table unique ou entre les tables Ressources et ResourceContainers.
where	Afficher les ressources contenant storage

Il existe une limite par défaut de trois opérateurs join et de trois opérateurs mv-expand dans une seule requête du Kit de développement logiciel (SDK) Resource Graph. Vous pouvez demander une augmentation de ces limites pour votre locataire via Aide + support.

Pour prendre en charge l'expérience de portail Ouvrir une requête, l'explorateur d'Azure Resource Graph a une limite globale supérieure à celle du Kit de développement logiciel (SDK) Resource Graph.

Remarque

Vous ne pouvez pas référencer une table comme table appropriée plusieurs fois, ce qui dépasse la limite de 1. Si vous le faites, vous recevrez une erreur avec le code DisallowedMaxNumberOfRemoteTables.

Étendue de requête

La portée des abonnements ou des groupes d’administration à partir desquels les ressources sont retournées par une requête est définie par défaut sur une liste d’abonnements en fonction du contexte de l’utilisateur autorisé. Si aucun groupe d’administration ou aucune liste d’abonnements n’est défini, l’étendue de requête correspond à l’ensemble des ressources et inclut les ressources déléguées Azure Lighthouse.

La liste des abonnements ou des groupes d’administration à interroger peut être définie manuellement pour changer l’étendue des résultats. Par exemple, la propriété managementGroups de l’API REST prend l’ID du groupe d’administration, qui est différent du nom du groupe d’administration. Quand managementGroups est spécifié, les ressources des 10 000 premiers abonnements dans ou sous la hiérarchie du groupe d’administration spécifié sont incluses. managementGroups ne peut pas être utilisé en même temps que subscriptions.

Exemple : Interroger toutes les ressources dans la hiérarchie du groupe d'administration nommé My Management Group avec l'ID myMG.

• URI de l’API REST

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

• Corps de la requête

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

Le paramètre AuthorizationScopeFilter vous permet de répertorier les affectations de stratégies Azure et les attributions de rôles de contrôle d'accès en fonction du rôle Azure (Azure RBAC) dans la table AuthorizationResources qui sont héritées des étendues supérieures. Le paramètre AuthorizationScopeFilter accepte les valeurs suivantes pour les tables PolicyResources et AuthorizationResources :

• AtScopeAndBelow (valeur par défaut si elle n'est pas spécifiée) : retourne les affectations pour l'étendue donnée et toutes les étendues enfants.
• AtScopeAndAbove : retourne les affectations pour l'étendue donnée et toutes les étendues parents, sauf les étendues enfants.
• AtScopeAboveAndBelow : retourne les affectations pour l’étendue donnée, toutes les étendues parents et toutes les étendues enfants.
• AtScopeExact : retourne les affectations uniquement pour l'étendue donnée, aucune étendue parent ou enfant n'est incluse.

Remarque

Pour utiliser le paramètre AuthorizationScopeFilter, veillez à utiliser la version de l'API 2021-06-01-preview ou ultérieure dans vos requêtes.

Exemple : Obtenez toutes les affectations de stratégie dans le groupe d’administration myMG et les étendues (parents) racines de locataire.

• URI de l’API REST

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

• Exemple de corps d’une demande

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

Exemple : Obtenez toutes les affectations de stratégie dans l’abonnement mySubscriptionId, le groupe d’administration et les étendues racines de locataire.

• URI de l’API REST

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

• Exemple de corps d’une demande

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

Caractères d'échappement

Certains noms propres, tels que ceux qui incluent un . ou $, doivent être inclus dans un wrapper ou échappés dans la requête, sinon le nom de la propriété est interprété de façon incorrecte et les résultats attendus ne sont pas obtenus.

• Point (.) : enveloppez le nom de la propriété ['propertyname.withaperiod'] à l’aide de crochets.

  Exemple de requête qui encapsule la propriété odata.type :

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

• Signe dollar ($) : échappez le caractère dans le nom de la propriété. Le caractère d'échappement utilisé dépend de l'interpréteur de commandes qui exécute Resource Graph.

  • Bash : utilisez une barre oblique inversée (\) comme caractère d’échappement.

    Exemple de requête qui échappe la propriété $type dans Bash :

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

  • cmd : ne pas échapper le caractère du signe dollar ($).

  • PowerShell : utilisez un guillemet inversé (`) comme caractère d’échappement.

    Exemple de requête qui échappe la propriété $type dans PowerShell :

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

Étapes suivantes

• Requêtes de démarrage et Requêtes avancées du langage de requête Azure Resource Graph.
• Découvrez comment explorer les ressources Azure.