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サブスクリプションです。 フィールドリネームは、プロパティがすでにjoinから射影されているため、name1として追加するResourcesを避けています。 クエリの結果として、キー コンテナーが 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 クエリ内で共有クエリを呼び出すには、{{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 言語要素

リソースグラフはKQL のデータ型の一部、 スカラー関数、ス カラー演算子、 集計関数をサポートしています。 Resource Graphは特定の 表形式演算子 をサポートしており、その中には異なる挙動を持つものもあります。

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

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

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

Open Queryポータルの体験をサポートするために、Azure Resource Graph ExplorerはResource Graph SDKよりも高いグローバル制限を持っています。

検索範囲

クエリによってリソースが返されるサブスクリプションや 管理グループ の範囲は、認可ユーザーのコンテキストに基づくサブスクリプションのリストにデフォルト設定されます。 管理グループやサブスクリプションリストが定義されていない場合、クエリスコープはすべてリソースで、 Azure Lighthouse の委任リソースも含みます。

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

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

• 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のプロパティ $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の RBAC アクセス許可評価関数

Azure Resource Graph (ARG) には、現在のクエリ ID に個々のリソースに対する特定のアクセス許可があるかどうかを評価できる 2 つの関数が用意されています。

• hasPermission()
• hasDataPermission()

これらの関数は、リソースごとにブール値 (1 または 0) を返し、アクセスに基づくリソースのフィルター処理や集計などのシナリオを可能にします。

hasPermission()

hasPermission()関数は、クエリ ID にリソースに対する特定のコントロール プレーンアクセス許可があるかどうかを評価します。

hasPermission()には、次の形式を使用します。

hasPermission('<permission-string>')

hasPermission()関数は、クエリ ID に対して有効な RBAC 割り当てを使用し、リソース行ごとに評価します。 この関数は 、ID がリソースに対して指定されたアクセス許可を持ち、ID が指定されていない場合は 0 を返します。

例 Azure コンテナー レジストリへの書き込みアクセスの確認

resources
| where type =~ 'Microsoft.ContainerRegistry/registries'
| extend canPush = hasPermission('Microsoft.ContainerRegistry/registries/push/write')

この例では、各コンテナー レジストリ リソースが個別に評価され、 canPush は、クエリ ID がそのリソースに対して指定された書き込みアクションを実行できるかどうかを示します。 結果は、返された値に基づくフィルター処理、集計、集計に使用できます。

hasDataPermission()

hasDataPermission()は、クエリ ID にリソースに対する特定のデータ プレーンアクセス許可があるかどうかを評価します。

hasDataPermission()には、次の形式を使用します。

hasDataPermission('<permission-string>')

hasDataPermission()関数は、クエリ ID に対して有効なデータ プレーン アクセス評価を使用し、リソース行ごとに評価されます。 この関数は、ID がリソースに対して指定されたデータ プレーンアクセス許可を持っている場合は 1 を返し、そうでない場合は 0 を返します。

例: Azure Blob Storageへのデータ プレーン読み取りアクセスを確認する

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| extend canReadBlobs = hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read')

この例では、各ストレージ リソースが個別に評価されます。 hasDataPermissions()関数は、クエリ ID に指定された data-plne アクセス許可があるかどうかを確認します。 返される値は、フィルター処理、集計、またはレポートに使用できます。

例: フィルター処理を使用してAzure Blob Storageへのデータ プレーン読み取りアクセスを確認する

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| where hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read') == 1

この例では、クエリ ID に BLOB 読み取りアクセス権があるストレージ アカウントのみを返します。

重要な制限事項

これらの関数は、多くの場合、ロールまたはアクセス許可の検出シナリオと混同されます。 理解するには、次の制限事項が重要です。

• hasPermission()およびhasDataPermission()関数は、ロール定義が付与するアクセス許可を決定しません。
• microsoft.authorization/roledefinitions リソースのクエリやフィルター処理には使用できません。
• これらは、次のような質問に回答するためのものではありません。
  • "このアクセス許可を付与するロールはどれですか?
  • "このロール定義に含まれるアクションは何ですか?

次のステップ

• Azure Resource Graphクエリ言語 Starter クエリと Advanced queries。
• Azure リソースを探索する方法の詳細。