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
  • Personnages d’évasion
  • É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

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.

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 mélange les colonnes et tous les noms de colonnes dupliqués de la table jointe, ResourceContainers dans cet exemple, sont ajoutés à 1. Comme la table ResourceContainers comporte des types à la fois pour les abonnements et les groupes de ressources, l’un ou l’autre type peut être utilisé pour rejoindre la ressource depuis Resources la table.

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 consiste join à fusionner les résultats avec les ResourceContainers , où le type est une abonnement sur une propriété qui se trouve à la fois dans la project première table et dans la projecttable jointe. Le renommage évite join de l’ajouter comme 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

Propriétés étendues

En tant que fonction d’aperçu , certains types de ressources dans Resource Graph disposent de propriétés plus spécifiques aux types disponibles pour interroger au-delà des propriétés fournies par Azure Resource Manager. Cet ensemble de valeurs, appelé propriétés étendues, existe sur un type de ressource supporté dans properties.extended. Pour afficher 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)

En tant que fonction d’aperçu, une requête partagée peut être 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 est l’ID de ressource de la requête partagée sur la page Paramètres pour cette requête. 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.

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 chargement un sous-ensemble de types de données KQL, de fonctions scalaires, d’opérateurs scalaires et de fonctions d’agrégation. Des opérateurs tabulaires spécifiques sont pris en charge par Resource Graph, certains ayant des comportements différents.

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 :

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 du portail Open Query , Azure Resource Graph Explorer a une limite globale plus élevée que le SDK Resource Graph.

Étendue de requête

La portée des abonnements ou des groupes de gestion d’où les ressources sont renvoyées par requête se traduit par défaut en une liste d’abonnements basée sur le contexte de l’utilisateur autorisé. Si un groupe de gestion ou une liste d’abonnements n’est pas défini, le périmètre de requête comprend toutes les ressources, incluant les ressources déléguées par 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 (par défaut si non spécifié) : Retourne les assignations pour le champ donné et tous les champs enfants.
• AtScopeAndAbove : Renvoie les affectations pour le champ d’application donné et tous les champs parents, mais pas pour les champs enfants.
• AtScopeAboveAndBelow : Retourne les affectations pour le périmètre donné, tous les champs parents, et tous les champs enfants.
• AtScopeExact : Retourne les affectations uniquement pour le périmètre donné ; Aucun endoscope parent ou enfant n’est inclus.

Exemple : Obtenez toutes les assignations de politiques dans le groupe de gestion myMG et les champs de contrôle Tenant Root (parent).

• 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 assignations de politique dans les champs d’application mySubscriptionId , de groupe de gestion et de racines locataires.

• 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 enveloppe 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 inverse (\) comme personnage d’évasion.

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

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

  • cmd : Ne fuyez pas le personnage du signe dollar ().$

  • PowerShell : Utilisez un backtick (`) comme personnage d’évasion.

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

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

Étapes suivantes

• Azure Resource Graph Query Langues Requêtes Starter et requêtes avancées.
• Découvrez comment explorer les ressources Azure.