Azure Resources Graph （ARG） GET/LIST API

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”，用于指示完整配额重置的时间点。您可以根据这些头信息了解您的配额消耗情况。

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

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

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

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

此请求用于通过提供资源 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 

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

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

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

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 列表。 此场景适用于处于灵活协调模式下的 VMSS VM。

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 列表。

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

对于此特定示例，请使用以下请求检索订阅中的存储帐户列表。

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”）。

以下示例是一个 .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 门户的“帮助 + 支持”下提交支持请求。