Azure Resources Graph （ARG） GET/LIST API

2025-07-07

ARG GET/LIST API 旨在通过将 GET 和 LIST 请求卸载到备用 ARG 平台来显著减少读取节流。此作是通过智能控制平面路由实现的，当存在特定参数时，该路由会将请求定向到备用平台。如果参数不存在，请求将无缝路由回原始资源提供程序，确保灵活性。

ARG GET/LIST 在移动窗口中提供的默认配额为每分钟 4k，用户和订阅，这意味着默认配额为每分钟 4k，允许你使用这些 API 每分钟最多发出 4,000 个请求。此配额是每个用户每个订阅强制实施的。这意味着：

如果用户 A 正在访问订阅 X，则每分钟最多收到 4,000 个请求。
如果用户 A 访问订阅 Y，那么这属于一个单独的配额。
如果用户 B 访问订阅 X，则这也是单独的配额。
API 提供响应头“x-ms-user-quota-remaining”，用于指示剩余配额，以及“x-ms-user-quota-resets-after”，用于指示完整配额重置的时间点。您可以根据这些头信息了解您的配额消耗情况。

注释

请记住，Azure 资源管理器配额适用于这些调用。了解 Azure 资源管理器限制。 

使用 ARG GET/LIST API

若要使用 ARG GET/LIST API，请首先确定你的方案是否与受限制请求指南中提到的条件匹配。然后，可以将标志 &useResourceGraph=true 追加到适用的 GET/LIST API 调用，该调用会将请求路由到此 ARG 后端进行响应。

需要通过向 Azure Resource Graph 团队发送电子邮件来联系 ARG 产品组，并简要概述你的方案，ARG 团队会通过后续步骤与你联系。

此选择加入模型是故意选择的，以允许 Azure Resource Graph 团队更好地了解客户使用模式，并根据需要进行改进。

请参阅此处的一些已知限制和常见问题。

ARG GET/LIST API 协定

资源点获取

此请求用于通过提供资源 D 查找单个资源。

传统点获取请求：

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

ARG 点获取请求：

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

订阅集合获取

此请求用于列出订阅中单个资源类型下的所有资源。

传统订阅集合获取请求：

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

ARG 订阅集合获取请求：

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

资源组集合获取

此请求用于列出资源组中单个资源类型下的所有资源。

传统点获取请求：

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

ARG GET/LIST 点获取请求：

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

注释

所有 Azure Resource Graph GET/LIST API 调用都必须使用 API 版本参数。但是，服务忽略此参数的值。无论指定的 API 版本如何，ARG 始终基于 API 的最新正式版（GA）非预览版返回结果。

一些常用示例

方案：使用 InstanceView 获取虚拟机（VM）

对于此特定示例，请使用以下请求获取具有 InstanceView 的虚拟机。

ARG GET/LIST 请求

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

列出 ResourceGroup 下的虚拟机

对于此特定示例，请使用以下请求检索资源组下的虚拟机列表。

ARG GET/LIST 请求

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

使用 InstanceView 列出 VMSS VM（统一）

对于此特定示例，请使用以下请求检索带有 InstanceView 的 VMSS VM 列表。此场景适用于处于灵活协调模式下的 VMSS VM。

ARG GET/LIST 请求

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

使用 InstanceView 列出 VMSS VM（弹性）

对于此特定示例，请使用以下请求检索带有 InstanceView 的 VMSS VM 列表。

ARG GET/LIST 请求

https://management.chinacloudapi.cn/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.chinacloudapi.cn/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 支持所有资源类型，作为resourcescomputeresources表的一部分。
单个 API 版本支持 - ARG GET/LIST 目前仅支持每个资源类型的单个 API 版本，该版本通常是 Azure REST API 规范中存在的类型的最新非预览版本。ARG GET/LIST 功能返回 apiVersion 响应的资源有效负载中的字段，该字段指示检索资源详细信息时使用的资源类型的版本。调用方可以应用此字段来了解要使用的 API 版本（如果它与其方案相关）。
客户端支持
- Azure REST API：支持
- Azure SDK：支持的示例 .NET 代码
- PowerShell：当前不支持
- Azure CLI：当前不支持
- Azure 门户：当前不支持
客户端反序列化问题
- 如果客户端使用 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 经过优化，以提供性能优异且数据可预测的准实时结果。
- 在资源点获取响应中，ARG GET/LIST 提供响应头 x-ms-arg-snapshot-timestamp，用于表示返回的资源快照被编制索引时的时间戳。标头的值是采用 ISO8601 格式的 UTC 时间。（例如，“x-ms-arg-snapshot-timestamp”： “2023-01-20T18：55：59.5610084Z”）。

示例 SDK 代码

以下示例是一个 .NET 代码示例，它通过创建一个 ARMClient 并将标志 useResourceGraph=true 添加到每个调用的策略来调用 ARG GET/LIST API：

首先，我们创建一个自定义的 ArmClientOption，其中包含一个在每次调用时添加 useResourceGraph=True 标志的策略。

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 字段中返回。 
如果调用方使用 useResourceGraph=true 标志调用 ARG GET/LIST API 来获取 ARG GET/LIST 不支持的资源，会发生什么情况？  

任何不受支持的或无法路由的请求都会导致 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 未找到”错误，该怎么办？

这是许多服务中的常见场景：客户创建资源后，作为另一个 WRITE 工作流的一部分，会在 1-2 秒内立即发起 GET 请求。例如，客户创建一个新资源后立即尝试创建一个监视该资源的指标警报。资源可能尚未由 ARG GET/LIST 编制索引。有两种方法可以解决这种情况：
- 在 ARG GET/LIST 上重试几次，直到返回状态代码 200。 
- 在不使用 ARG GET/LIST 标志的情况下重试，以回退至资源提供程序。真正的状态代码 404 不会命中资源提供程序，因为 Azure 资源管理器直接返回错误，而资源提供程序应提供 false 404 以获取实际数据。
ARG GET/LIST API 支持哪些 URI 参数？

ARG GET/LIST API 支持一系列 URI 参数，以帮助定制和分页查询结果。其中包括：标准 OData 分页参数：
- $top：指定要返回的记录数。
- $skip：跳过指定的记录数。
- $skipToken：用于检索分页查询中下一页的结果。
查询虚拟机和 VMSS VM 的参数 -
- statusOnly：statusOnly=true 启用获取订阅中所有虚拟机的运行时状态。
- $expand=instanceView: 适用于操作的展开表达式。 “instanceView”支持提取所有虚拟机的运行时状态，仅当指定了有效的$filter选项时，才能指定此选项
- $filter：用于筛选响应中返回的 VM 的系统查询选项。允许的值为 virtualMachineScaleSet/id eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}
如果在调用 Azure Resource Graph 时使用 useResourceGraph 参数时遇到问题，该怎么办？

如果在使用 useResourceGraph 参数与 ARG 时遇到任何问题，请在 Azure 门户的“帮助 + 支持”下提交支持请求。

通过

Azure Resources Graph （ARG） GET/LIST API

使用 ARG GET/LIST API

ARG GET/LIST API 协定

资源点获取

订阅集合获取

资源组集合获取

一些常用示例

方案：使用 InstanceView 获取虚拟机（VM）

ARG GET/LIST 请求

列出 ResourceGroup 下的虚拟机

ARG GET/LIST 请求

使用 InstanceView 列出 VMSS VM（统一）

ARG GET/LIST 请求

使用 InstanceView 列出 VMSS VM（弹性）

ARG GET/LIST 请求

列出订阅中的存储帐户

ARG GET/LIST 请求

已知限制

示例 SDK 代码

常见问题

其他资源