Grundlegendes zur Azure Resource Graph-Abfragesprache

Die Abfragesprache für Azure Resource Graph unterstützt viele Operatoren und Funktionen. Diese arbeiten und funktionieren auf Grundlage der Abfragesprache Kusto (Kusto Query Language, KQL). Wenn Sie mehr über die von Resource Graph verwendete Abfragesprache erfahren möchten, beginnen Sie mit dem Tutorial für KQL.

In diesem Artikel werden die von Resource Graph unterstützten Sprachkomponenten behandelt:

• Grundlegendes zur Azure Resource Graph-Abfragesprache
  • Resource Graph-Tabellen
  • Extended properties
  • Benutzerdefinierte Sprachelemente in Resource Graph
    • Syntax für freigegebene Abfragen (Vorschauversion)
  • Unterstützte KQL-Sprachelemente
    • Unterstützte tabellarische Operatoren und Operatoren auf oberster Ebene
  • Query scope
  • Escape characters
  • Next steps

Resource Graph-Tabellen

Resource Graph umfasst mehrere Tabellen für die Daten, die in Bezug auf Azure Resource Manager-Ressourcentypen und deren Eigenschaften gespeichert werden. Resource Graph-Tabellen können mit dem join-Operator verwendet werden, um Eigenschaften aus verwandten Ressourcentypen abzurufen.

Resource Graph-Tabellen unterstützen die join-Varianten:

• innerunique
• inner
• leftouter
• fullouter

Eine Liste der Tabellen, die Ressourcentypen enthalten, finden Sie unter Referenz zu Azure Resource Graph-Tabellen und Ressourcentypen.

Verwenden Sie den Resource Graph-Explorer im Portal, um zu ermitteln, welche Ressourcentypen in den einzelnen Tabellen verfügbar sind. Sie können auch eine Abfrage verwenden (z.B. <tableName> | distinct type), um eine Liste von Ressourcentypen zu erhalten, die von der angegebenen Resource Graph-Tabelle unterstützt werden und in Ihrer Umgebung vorhanden sind.

Die folgende Abfrage zeigt eine einfache Verwendung von join. 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

Die folgende Abfrage zeigt eine komplexere Verwendung von join. Zuerst verwendet die Abfrage project, um die Felder aus Resources für den Ressourcentyp „Azure Key Vault-Tresore“ abzurufen. 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. Das Abfrageergebnis ist ein einzelner Schlüsseltresor, der den Typ, den Namen, den Speicherort und die Ressourcengruppe des Schlüsseltresors sowie den Namen des Abonnements anzeigt, in dem er sich befindet.

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

Beispiel: Abrufen der Anzahl virtueller Computer über instanceView.powerState.code:

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

Benutzerdefinierte Sprachelemente in Resource Graph

Syntax für freigegebene Abfragen (Vorschauversion)

As a preview feature, a shared query can be accessed directly in a Resource Graph query. Dieses Szenario ermöglicht es, Standardabfragen als freigegebene Abfragen zu erstellen und wiederzuverwenden. Verwenden Sie die Syntax {{shared-query-uri}}, um eine freigegebene Abfrage innerhalb einer Resource Graph-Abfrage aufzurufen. The URI of the shared query is the Resource ID of the shared query on the Settings page for that query. In diesem Beispiel ist /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS der URI für die freigegebene Abfrage. Dieser URI verweist auf das Abonnement, die Ressourcengruppe und den vollständigen Namen der freigegebenen Abfrage, auf die in einer anderen Abfrage verwiesen werden soll. Diese Abfrage ist identisch mit der Abfrage, die unter Tutorial: Erstellen und Freigeben einer Abfrage erstellt wird.

Beispiel 1: Alleiniges Verwenden der freigegebenen Abfrage

Die Ergebnisse dieser Resource Graph-Abfrage sind identisch mit denen der in der freigegebenen Abfrage gespeicherten.

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

Beispiel 2: Einfügen der freigegebenen Abfrage als Teil einer größeren Abfrage

Bei dieser Abfrage wird zunächst die freigegebene Abfrage und dann limit verwendet, um die Ergebnisse weiter einzugrenzen.

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

Unterstützte KQL-Sprachelemente

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.

Unterstützte tabellarische Operatoren und Operatoren auf oberster Ebene

Hier finden Sie die Liste der von Resource Graph unterstützten KQL-Tabellenoperatoren mit konkreten Beispielen:

Es gibt eine Standardgrenze von drei join- und drei mv-expand-Operatoren in einer einzelnen Resource Graph-SDK-Abfrage. Sie können eine Erhöhung dieser Grenzwerte für Ihren Mandanten über Hilfe und Support anfordern.

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.

Die Liste der abzufragenden Abonnements oder Verwaltungsgruppen kann manuell definiert werden, um den Bereich der Ergebnisse zu ändern. Die REST-API-Eigenschaft managementGroups übernimmt beispielsweise die Verwaltungsgruppen-ID, die sich von dem Namen der Verwaltungsgruppe unterscheidet. Wenn managementGroups angegeben ist, werden Ressourcen aus den ersten 10.000 Abonnements in oder unter der angegebenen Verwaltungsgruppenhierarchie eingeschlossen. managementGroups kann nicht gleichzeitig mit subscriptions verwendet werden.

Beispiel: Abfrage aller Ressourcen innerhalb der Hierarchie der Verwaltungsgruppe namens My Management Group mit der ID myMG.

• REST-API-URI

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

• Request Body

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

Mit dem Parameter AuthorizationScopeFilter können Sie in der Tabelle AuthorizationResources Azure Policy-Zuweisungen und Azure RBAC-Rollenzuweisungen (rollenbasierte Zugriffssteuerung in Azure) auflisten, die von oberen Bereichen geerbt werden. Der Parameter AuthorizationScopeFilter akzeptiert die folgenden Werte für die Tabellen PolicyResources und 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.

• REST-API-URI

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

• Exemplarischer Anforderungstext

  {
    "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.

• REST-API-URI

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

• Exemplarischer Anforderungstext

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

Escape characters

Einige Eigenschaftennamen, etwa diejenigen, die einen . oder ein $ enthalten, müssen in einer Abfrage umhüllt oder mit Escapezeichen versehen sein. Andernfalls wird der jeweilige Eigenschaftenname falsch interpretiert, sodass nicht die erwarteten Ergebnisse bereitgestellt werden.

• Punkt (.): Schließen Sie den Eigenschaftennamen ['propertyname.withaperiod'] in Klammern ein.

  Example query that wraps the property odata.type:

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

• Dollarzeichen ($): Versehen Sie das Zeichen im Eigenschaftennamen mit einem Escapezeichen. Welches Escapezeichen verwendet wird, hängt von der Shell ab, in der Resource Graph ausführt wird.

  • 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.
• Weitere Informationen über das Erkunden von Azure-Ressourcen