Azure Resource Graph クエリ言語の概要

Azure Resource Graph のクエリ言語では、さまざまな演算子と関数がサポートされています。 それぞれは、Kusto Query Language (KQL) に基づいて動作します。 Resource Graph で使用されるクエリ言語の詳細については、KQL のチュートリアルを参照してください。

この記事では、Resource Graph でサポートされる言語コンポーネントについて説明します。

• Azure Resource Graph クエリ言語の概要
  • Resource Graph テーブル
  • 拡張プロパティ
  • Resource Graph のカスタム言語要素
    • 共有クエリ構文 (プレビュー)
  • サポートされる KQL 言語要素
    • サポートされているテーブル演算子/上位レベルの演算子
  • クエリ スコープ
  • エスケープ文字
  • 次の手順

Resource Graph テーブル

Resource Graph には、Azure Resource Manager のリソースの種類とそのプロパティに関するデータ用のテーブルがいくつか用意されています。 join 演算子で Resource Graph テーブルを使用すると、関連するリソースの種類からプロパティを取得できます。

Resource Graph テーブルでは、次の join フレーバーがサポートされています。

• innerunique
• inner
• leftouter
• fullouter

リソースの種類を含むテーブルの一覧については、「Azure Resource Graph のテーブルとリソースの種類のリファレンス」を参照してください。

各テーブルで使用できるリソースの種類を検出するには、ポータルで Resource Graph Explorer を使用します。 別の方法として、<tableName> | distinct type などのクエリを使用して、指定した Resource Graph テーブルでサポートされている、環境内に存在するリソースの種類の一覧を取得することもできます。

次のクエリは、単純な join を示しています。 クエリ結果では、列が結合され、結合されたテーブルの重複する列名 (この例では ResourceContainers) が 1 と共に追加されます。 ResourceContainers テーブルには、サブスクリプションとリソース グループの両方の種類があるため、どちらかの種類を使用して、Resources テーブルからリソースに結合することができます。

Resources
| join ResourceContainers on subscriptionId
| limit 1

次のクエリは、join のより複雑な使用方法を示しています。 まず、このクエリは project を使用して、Azure Key Vault コンテナーのリソースの種類の Resources からフィールドを取得します。 次の手順では、join を使用して、ResourceContainers に結果を統合します。種類は、最初のテーブルの project と結合されたテーブルの project の両方にあるプロパティに対して ON されたサブスクリプションです。 プロパティは既に Resources から投影されているため、フィールドの名前を変更して、これが join によって name1 として追加されるのを回避しています。 クエリの結果として、キー コンテナーが 1 つ返され、その種類と名前、場所、キー コンテナーのリソース グループ、およびそれが存在するサブスクリプションの名前が表示されます。

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

拡張プロパティ

"プレビュー" 機能として、Resource Graph の一部のリソースの種類には、Azure Resource Manager によって提供されるプロパティ以外に、クエリで使用できる追加の種類関連のプロパティがあります。 この一連の値は拡張プロパティと呼ばれ、properties.extended でサポートされているリソースの種類に存在します。 "拡張プロパティ" があるリソースの種類を表示するには、次のクエリを使用します。

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

例:instanceView.powerState.code によって、仮想マシンの数を取得します。

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

Resource Graph のカスタム言語要素

共有クエリ構文 (プレビュー)

プレビュー機能として、共有クエリには、Resource Graph クエリで直接アクセスできます。 このシナリオにより、標準クエリを共有クエリとして作成し、再利用することができます。 Resource Graph クエリ内で共有クエリを呼び出すには、{{shared-query-uri}} 構文を使用します。 共有クエリの URI は、そのクエリの [設定] ページにある共有クエリの [リソース ID] です。 この例では、共有クエリ URI は /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS です。 この URI は、サブスクリプション、リソース グループ、および別のクエリで参照する共有クエリの完全な名前を指します。 このクエリは、チュートリアル:クエリの作成と共有で作成したものと同じです。

例 1: 共有クエリのみを使用する:

この Resource Graph クエリの結果は、共有クエリに格納されているクエリと同じです。

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

例 2: より大きいクエリの一部として共有クエリを含める:

このクエリでは、最初に共有クエリを使用し、次に limit を使用して結果をさらに制限します。

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

サポートされる KQL 言語要素

Resource Graph では、KQL データ型、スカラー関数、スカラー演算子、集計関数のサブセットがサポートされています。 Resource Graph では、特定のテーブル演算子がサポートされます。その中には、動作が異なるものもあります。

サポートされているテーブル演算子/上位レベルの演算子

次に示すのは、Resource Graph でサポートされる KQL のテーブル演算子の一覧と具体的なサンプルです。

1 つの Resource Graph SDK クエリには、3 つの join と 3 つの mv-expand 演算子という既定の制限があります。 テナントに対するこれらの制限の引き上げを要求するには、ヘルプとサポートを使用します。

"オープン クエリ" ポータル エクスペリエンスをサポートするために、Azure Resource Graph Explorer には、Resource Graph SDK よりも高い制限が設けられています。

クエリ スコープ

クエリによって返されるリソースの、サブスクリプションまたは管理グループのスコープは、既定では、承認されたユーザーのコンテキストに基づくサブスクリプションの一覧になります。 管理グループまたはサブスクリプションの一覧が定義されていない場合、クエリ スコープはすべてのリソースになり、Azure Lighthouse の委任されたリソースが含まれます。

クエリ対象のサブスクリプションまたは管理グループの一覧は、結果のスコープを変更するために、手動で定義できます。 たとえば、REST API の managementGroups プロパティは、管理グループ ID を受け取ります。これは、管理グループの名前とは異なります。 managementGroups を指定すると、指定した管理グループ階層内、またはその下にある最初の 10,000 件のサブスクリプションのリソースが含まれます。 managementGroups を subscriptions と同時に使用することはできません。

例: ID が myMG の My Management Group という管理グループの階層内のすべてのリソースのクエリを実行します。

• REST API URI

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

• 要求本文

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

AuthorizationScopeFilter パラメーターを使用すると、上位スコープから継承された AuthorizationResources テーブル内の Azure Policy の割り当てと Azure ロールベースのアクセス制御 (Azure RBAC) のロールの割り当てを一覧表示できます。 AuthorizationScopeFilter パラメーターには、PolicyResources テーブルと AuthorizationResources テーブルに対して次の値を使用できます。

• AtScopeAndBelow (指定されていない場合の既定): 指定されたスコープとすべての子スコープの割り当てを返します。
• AtScopeAndAbove: 指定されたスコープとすべての親スコープの割り当てを返しますが、子スコープの割り当ては返しません。
• AtScopeAboveAndBelow: 指定されたスコープ、すべての親スコープ、すべての子スコープの割り当てを返します。
• AtScopeExact: 指定されたスコープのみの割り当てを返します。親または子のスコープは含まれません。

例: myMG 管理グループとテナント ルート (親) スコープのすべてのポリシー割り当てを取得します。

• REST API URI

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

• 要求本文の例

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

例: mySubscriptionId サブスクリプション、管理グループ、テナント ルートのスコープのすべてのポリシー割り当てを取得します。

• REST API URI

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

• 要求本文の例

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

エスケープ文字

. や $ を含むものなど、一部のプロパティ名はクエリ内でラップまたはエスケープする必要があります。そうしないと、プロパティ名が正しく解釈されず、期待する結果が得られません。

• ドット (.): 角かっこを使用してプロパティ名 ['propertyname.withaperiod'] をラップします。

  プロパティ odata.type をラップするクエリ例:

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

• ドル記号 ($): プロパティ名の文字をエスケープします。 使うエスケープ文字は、Resource Graph を実行するシェルによって異なります。

  • Bash: エスケープ文字としてバックスラッシュ (\) を使用します。

    Bash でプロパティ $type をエスケープするクエリ例:

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

  • cmd: ドル記号 ($) 文字をエスケープしないでください。

  • PowerShell: エスケープ文字としてバックティック (`) を使用します。

    PowerShell でプロパティ $type をエスケープするクエリ例:

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

次のステップ

• Azure Resource Graph クエリ言語の初歩的なクエリと高度なクエリ。
• Azure リソースを探索する方法の詳細。