Microsoft Graph 限制指南

  • 项目

限制可调节并发调用服务的数量，防止资源的过度使用。 Microsoft Graph 旨在用于处理大量的请求。 如果出现过多请求，限制将有助于保持 Microsoft Graph 的最佳性能和服务的可靠性。

根据场景，执行的限制会有所不同。 例如，如果执行大量写入，则限制的可能性高于仅执行读取的可能性。

注意

需要从 Microsoft Graph 提取大量数据的解决方案应使用 Microsoft Graph Data Connect 而不是 Microsoft Graph REST API。 Microsoft Graph Data Connect 允许组织批量提取 Microsoft 365 数据，不受限制。


在限制时，会发生什么情况？

超过限制阈值时，Microsoft Graph 会将来自该客户端的任何进一步请求限制在一段时间内。 发生限制时，Microsoft Graph 返回 HTTP 状态代码 429 () 请求过多，请求失败。 失败请求的响应标头中返回建议的等待时间。 限制行为可能取决于请求的类型和数量。 例如，如果请求量很大，则会限制所有请求类型。 阈值限制因请求类型而异。 因此，可能会遇到写入受到限制但仍允许读取的情况。

常见的限制场景

客户端受限的最常见原因包括：

  • 来自租户中所有应用程序的请求太多。
  • 来自所有租户中特定应用程序的请求太多。

示例响应

每当超出限制阈值时，Microsoft Graph 都会提供与此类似的响应。

HTTP/1.1 429 Too Many Requests
Content-Length: 312
Content-Type: application/json
Retry-After: 10

{
  "error": {
    "code": "TooManyRequests",
    "innerError": {
      "code": "429",
      "date": "2020-08-18T12:51:51",
      "message": "Please retry after",
      "request-id": "94fb3b52-452a-4535-a601-69e0a90e3aa2",
      "status": "429"
    },
    "message": "Please retry again later."
  }
}

处理限制的最佳实践

以下是处理限制的最佳做法：

  • 减少每个请求的操作数量。
  • 减少调用频率。
  • 不要立即重试，因为所有请求都会计入使用限制。

实现错误处理时，请使用 HTTP 错误代码 429 检测限制。 失败的响应包括 Retry-After 响应标头。 使用 Retry-After 延迟备份请求是从限制中恢复的最快方法，因为 Microsoft Graph 在客户端受到限制时会继续记录资源使用情况。

  1. 等待 Retry-After 标头中指定的秒数。
  2. 请重试请求。
  3. 如果请求再次失败并显示 429 错误代码，则仍会受到限制。 继续使用建议 Retry-After 的延迟并重试请求，直到成功。

除非另有说明，否则服务特定限制部分中所述的所有资源和 API 均提供 Retry-After 标头。

有关 Microsoft 云限制的更广泛讨论，请参阅限制模式。

注意

如果响应未提供 Retry-After 标头，我们建议实施指数退避重试策略。 构建大型应用程序时，还可以实现更高级的模式。

Microsoft Graph SDK 已实施依赖于 Retry-After 标头或默认为指数退避重试策略的处理程序。

避免限制的最佳做法

如持续轮询资源以检查更新以及定期扫描资源集合以检查新资源或已删除资源之类的编程模式，更有可能导致应用程序受到限制并降低整体性能。 如果可用，改为使用更改跟踪并更改通知。

注意

大规模发现文件和检测更改的最佳做法详细介绍最佳做法。

限制和批处理

JSON 批处理使你能够通过将多个请求合并为单个 JSON 对象来优化应用程序。 批次中的请求将根据限制进行单独评估，如果任何请求超出限制，则它将失败，并出现 status429 以及类似于上述内容的错误。 批次本身失败，状态代码为 424（失败的相关性）。 多个请求可能会在单个批次中受到限制。 应使用 JSON 内容的 retry-after 响应标头中提供的值，尝试批次中每个失败的请求。 你可以在最长 retry-after 值之后重试新批次中所有失败的请求。

如果在受限制请求未经批处理时，SDK 自动重试这些请求，则不会自动重试属于批次的受限制请求。

后续步骤