Azure Resources Graph (ARG) GET/LIST API (プレビュー)

ARG GET/LIST API は、GET 要求と LIST 要求を代替 ARG プラットフォームにオフロードすることで、READ 調整を大幅に削減するように設計されています。 このアクションは、特定のパラメーターが存在する場合に代替プラットフォームに要求を送信するインテリジェントなコントロール プレーン ルーティングによって実現されます。 パラメーターがない場合、要求は元のリソース プロバイダーにシームレスにルーティングされ、柔軟性が確保されます。

ARG GET/LIST では、移動ウィンドウで 1 分、1 ユーザー、1 サブスクリプションあたり 4k の既定のクォータが提供されます。つまり、既定の 1 分あたり 4k のクォータで、これらの API を使用して 1 分あたり最大 4,000 要求を作成できます。 このクォータは、サブスクリプションごとにユーザーごとに適用されます。 これは、以下のようなことを意味します。

• ユーザー A がサブスクリプション X にアクセスしている場合、1 分あたり最大 4,000 件の要求を受け取ります。
• ユーザー A がサブスクリプション Y にアクセスする場合、これは別のクォータです。
• ユーザー B がサブスクリプション X にアクセスする場合、これは別のクォータでもあります。
• この API には、残りのクォータを示す応答ヘッダー "x-ms-user-quota-remaining" と、クォータの使用量を把握できる完全なクォータリセットの時間を示す "x-ms-user-quota-resets-after" が用意されています。

ARG GET/LIST API の使用

ARG GET/LIST API を使用するには、まず、制限されたリクエストに関するガイダンスで説明されている条件にシナリオが一致するかどうかを確認します。 その後、該当する GET/LIST API 呼び出しにフラグ &useResourceGraph=true を追加して、応答のためにこの ARG バックエンドに要求をルーティングできます。

useResourceGraph フラグは期待どおりに機能しますが、Azure Resource Graph チームに電子メールでシナリオの概要を共有することをお勧めします。 これは、Azure Resource Graph (ARG) チームがユース ケースをより深く理解し、適切なガイダンスを提供するのに役立ちます。

このオプトイン モデルは、Azure Resource Graph チームが顧客の使用パターンをよりよく理解し、必要に応じて改善できるように意図的に選択されました。

ここでは、いくつかの既知の制限事項とよく寄せられる質問を参照してください。

ARG GET/LIST API コントラクト

リソース ポイントの取得

この要求は、リソース D を指定して 1 つのリソースを検索するために使用されます。

従来のポイント取得要求:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion} 

ARG ポイント取得要求:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion}&useResourceGraph=true 

サブスクリプション コレクションの取得

この要求は、サブスクリプション内の単一のリソースの種類のすべてのリソースを一覧表示するために使用されます。

従来のサブスクリプション コレクションの取得要求:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

ARG サブスクリプション コレクションの取得要求:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

リソースグループコレクションを取得

この要求は、リソース グループ内の単一のリソースの種類ですべてのリソースを一覧表示するために使用されます。

従来のポイント取得要求:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

ARG GET/LISTポイント取得リクエスト:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

よく使用される例

シナリオ: InstanceView を使用して仮想マシン (VM) を取得する

この特定の例では、次の要求を使用して、InstanceView を使用して仮想マシンを取得します。

ARG GET/LIST 要求

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines/{vm}?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

ResourceGroup の下に VM を一覧表示する

この特定の例では、次の要求を使用して、リソース グループの下にある仮想マシンの一覧を取得します。

ARG GET/LIST 要求

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

InstanceView を使用して VMSS VM (Uniform) を一覧表示する

この特定の例では、次の要求を使用して、InstanceView を使用して VMSS VM の一覧を取得します。 このシナリオは、フレキシブル オーケストレーション モードの VMSS VM 用です。

ARG GET/LIST 要求

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

InstanceView を使用して VMSS VM (Flex) を一覧表示する

この特定の例では、次の要求を使用して、InstanceView を使用して VMSS VM の一覧を取得します。

ARG GET/LIST 要求

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$filter='virtualMachineScaleSet/id' eq '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}'&$expand=instanceView&useResourceGraph=true

サブスクリプション内のストレージ アカウントを一覧表示する

この特定の例では、次の要求を使用して、サブスクリプション内のストレージ アカウントの一覧を取得します。

ARG GET/LIST 要求

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.storage/storageAccounts?api-version=2024-01-01&useResourceGraph=true 

既知の制限事項

• VMSS VM の正常性状態 は現在サポートされていません。 このデータが必要な場合は、シナリオを共有し、 フィードバック フォーラムで機能の追加を提案できます。
• VM と VMSS VM 拡張機能 - VM と VMSS VM 拡張機能の実行中の状態はサポートされていません。 このデータが必要な場合は、シナリオを共有し、 フィードバック フォーラムで機能の追加を提案できます。
• サポートされているリソース - ARG GET/LIST API では、 resources テーブルと computeresources テーブルの一部として、すべてのリソースの種類がサポートされます。 これらのテーブルに含まれていないリソースの種類が必要な場合は、シナリオを共有し、 フィードバック フォーラムで機能の追加を提案できます。
• 単一の API バージョンのサポート - 現在、ARG GET/LIST では、リソースの種類ごとに 1 つの API バージョンのみがサポートされています。これは、通常、Azure REST API 仕様に存在する最新の非プレビュー バージョンです。ARG GET/LIST 機能は、リソースの詳細を取得するときに使用されたリソースの種類のバージョンを示す応答のリソース ペイロードの apiVersion フィールドを返します。 呼び出し元は、このフィールドを適用して、使用する API のバージョン (シナリオに関連する場合) を理解できます。
• クライアントのサポート
  • Azure REST API: サポートされています
  • Azure SDK: サポートされている サンプル .NET コード
  • PowerShell: 現在サポートされていません
  • Azure CLI: 現在サポートされていません
  • Azure portal: 現在サポートされていません
• クライアントの逆シリアル化に関する問題
  • クライアントが REST API を使用して GET 呼び出しを発行する場合、通常、API のバージョンの違いによる逆シリアル化に関する懸念はありません。
  • クライアントが Azure SDK を使用して GET 呼び出しを発行する場合、すべての言語で逆シリアル化設定が緩和されているため、ターゲット リソースの種類に対して異なるバージョン間でコントラクトの破壊的変更がない限り、逆シリアル化の問題は問題になりません。
• 未処理のリソース要求
  • リソースの存在以外に、ARG GET/LIST でリソースのインデックスを正しく作成できないというまれなシナリオがあります。 データ品質を犠牲にしないように、ARG GET/LIST はこれらのリソースの GET 呼び出しを拒否し、HTTP 422 のエラー コードを返します。
  • ARG GET/LIST のクライアントは、HTTP 422 を永続的なエラーとして扱う必要があります。 クライアントは、( useResourceGraph=true フラグを削除して) リソース プロバイダーにフォールバックして再試行する必要があります。 このエラーは特に ARG GET/LIST に適用されるため、リソース プロバイダーにフォールバックすると E2E が成功します。
• サポートされている整合性レベル
  • ARG GET または LIST を使用する場合、受信したデータには、リアルタイムの更新ではなく、わずかな遅延 (通常は数秒) の最近の変更が反映されます。 これは "有界整合性制約" と呼ばれ、高速でスケーラブルなクエリを確保しつつ、なお Azure リソースの一貫性のある最新のビューを提供するものです。 リアルタイムの精度 (強力な整合性) を保証するリソース プロバイダーへの直接呼び出しとは異なり、ARG は予測可能なほぼリアルタイムのデータを使用してパフォーマンスに最適化されています。
  • resource Point Get 応答では、ARG GET/LIST は、返されたリソース スナップショットのインデックスが作成されたときのタイムスタンプを示す応答ヘッダー x-ms-arg-snapshot-timestamp を提供します。 ヘッダーの値は、ISO8601形式の UTC 時刻です。 (例: "x-ms-arg-snapshot-timestamp" : "2023-01-20T18:55:59.5610084Z")。

サンプル SDK コード

次の例は、各呼び出しにフラグ useResourceGraph=true を追加するポリシーを使用して ARMClient を作成して ARG GET/LIST API を呼び出す .NET Code サンプルです。

まず、呼び出しごとに useResourceGraph=True フラグを追加するポリシーを使用して、カスタム ArmClientOption を作成します。

var armClientOptions = new ArmClientOptions(); armClientOptions.AddPolicy(new ArgGetListHttpPipelinePolicy(), HttpPipelinePosition.PerCall); 

次に、カスタム ArmClientOptions を使用して ArmClient を作成します。

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), null, armClientOptions); 

既定のサブスクリプションを使用して ARMClient を作成する場合はどうなりますか? ArmClient クライアントの値を次のように設定します。

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), defaultSubId, armClientOptions);

必要に応じて、 useResourceGraph フラグを追加しない既定のクライアントを作成するために、クライアント コードは、特定のシナリオとニーズに基づいて使用するクライアントを選択します。 これを行うには、次のコード ブロックを使用します。

ArmClient defaultClient = new ArmClient(new DefaultAzureCredential(), null, new ArmClientOptions()); 

次に、このポリシーを使用して、クライアントを通じてすべての要求のクエリ パラメーターを追加します。

internal class ArgGetListHttpPipelinePolicy : HttpPipelineSynchronousPolicy 

{ 
    private static const string UseResourceGraph = "useResourceGraph"; 
    public override void OnSendingRequest(HttpMessage message) 

    { 
        // Adds the required query parameter to explicitly query ARG GET/LIST if the flag is not already present 
        if (!message.Request.Uri.ContainsQuery(UseResourceGraph)) 
        { 
          message.Request.Uri.AppendQuery(UseResourceGraph, bool.TrueString); 
        } 
    } 
} 

よく寄せられる質問

• ARG GET/LIST API によって応答が返されるようにするにはどうすればよいですか?

  ARG GET/LIST を要求するときに識別できる方法はいくつかあります。

  • 応答本文では、ARG GET/LIST によって提供される場合、リソースのapiVersionフィールドが入力されます。 
  • ARG GET/LIST/ARG は、いくつかのより多くの応答ヘッダーを返します。その一部は次のとおりです。
    • x-ms-arg-snapshot
    • x-ms-user-quota-remaining
    • x-ms-user-quota-resets-after
    • x-ms-resource-graph-request-duration

• ARG GET/LIST でどの API バージョンが使用されたかを知るにはどうすればよいですか?

  この値は、今日のリソース応答 apiVersion フィールドに返されます。 

• 呼び出し元が ARG GET/LIST でサポートされていないリソースに対して useResourceGraph=true フラグを指定して ARG GET/LIST API を呼び出すとどうなりますか?  

  サポートされていない要求またはルーティング不可能な要求 useResourceGraph=true 無視され、呼び出しはリソース プロバイダーに自動的にルーティングされます。 ユーザーがアクションを実行する必要はありません。  

• ARG GET/LIST API のクエリに必要なアクセス許可は何ですか?

  ARG GET/LIST API には特別なアクセス許可は必要ありません。ARG GET/LIST API はネイティブ リソース プロバイダー ベースの GET API と同等であるため、標準 RBAC が適用されます。 呼び出し元は、アクセスしようとしているリソース/スコープに対する少なくとも READ アクセス許可を持っている必要があります。 

• ARG GET/LIST API の使用中に問題が見つかると、ロールバック戦略は何ですか?  

  フラグ useResourceGraph=trueを使用してオンボードした場合、呼び出し元はフラグを削除するか、値を useResourceGraph=false に設定し、呼び出しはリソース プロバイダーに自動的にルーティングされます。 

• 最近作成された ARG GET/LIST からリソースを取得しようとしたときに 404 Not Found を取得する場合はどうしますか?

  これは、顧客がリソースを作成し、別の WRITE ワークフローの 1 ~ 2 秒の部分ですぐに GET を発行する多くのサービスで一般的なシナリオです。 たとえば、顧客が新しいリソースを作成し、その直後にそれを監視するためのメトリックアラートを作成しようとすることがあります。 リソースがまだ ARG GET/LIST によってインデックス付けされていない可能性があります。 この状況を回避するには、次の 2 つの方法があります。

  • ARG GET/LIST で、状態コード 200 が返されるまで数回再試行してください。 
  • ARG GET/LIST フラグを指定せずに再試行して、リソース プロバイダーにフォールバックします。 Azure Resource Manager がエラーを直接返すのに対し、実際のデータを取得するにはリソース プロバイダーが false 404 を処理する必要があるため、True 状態コード 404 はリソース プロバイダーにヒットしません。

• ARG GET/LIST API でサポートされている URI パラメーターは何ですか?

  ARG GET/LIST API では、クエリ結果の調整と改ページに役立つ URI パラメーターの範囲がサポートされています。 次のものが含まれます。標準の OData 改ページ調整パラメーター:

  • $top: 返すレコードの数を指定します。
  • $skip: 指定した数のレコードをスキップします。
  • $skipToken: ページ分割されたクエリで結果の次のページを取得するために使用されます。

  仮想マシンと VMSS VM のクエリ パラメーター -

  • statusOnly: statusOnly=true を指定すると、サブスクリプション内のすべての仮想マシンの実行時状態をフェッチできます。
  • $expand=instanceView: 操作に適用する展開式。 'instanceView' を使用すると、すべての Azure 仮想マシンの実行時の状態をフェッチできます。有効な$filter オプションが指定されている場合にのみ指定できます
  • $filter: 応答で返された VM をフィルター処理するためのシステム クエリ オプション。 使用できる値は、eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName} virtualMachineScaleSet/id です。

• Azure Resource Graph を呼び出すときに useResourceGraph パラメーターの使用中に問題が発生した場合はどうすればよいですか?

  ARG で useResourceGraph パラメーターを使用しているときに問題が発生した場合は、Azure portal の Azure Resource Graph サービスの [ヘルプとサポート] でサポート チケットを作成します。