Microsoft Graph 限制指南Microsoft Graph throttling guidance

限制可调节并发调用服务的数量,以防止资源的过度使用。Microsoft Graph 旨在用于处理大量的请求。如果出现过多请求,限制将有助于保持 Microsoft Graph 的最佳性能和服务的可靠性。Throttling limits the number of concurrent calls to a service to prevent overuse of resources. Microsoft Graph is designed to handle a high volume of requests. If an overwhelming number of requests occurs, throttling helps maintain optimal performance and reliability of the Microsoft Graph service.

根据该方案,执行的限制会有所不同。例如,如果你正在执行大量的写入操作,限制的可能性会比仅执行读取时要高。Throttling limits vary based on the scenario. For example, if you are performing a large volume of writes, the possibility for throttling is higher than if you are only performing reads.

在限制时,会发生什么情况?What happens when throttling occurs?

超出限制阈值后,Microsoft Graph 会在一段时间内限制来自该客户端的任何进一步的请求。发生限制时,Microsoft Graph 将返回 HTTP 状态代码 429(请求过多),同时请求失败。在失败的请求的响应标头中返回建议的等待时间。限制行为取决于请求的类型和数量。例如,如果你有大量的请求,则所有请求类型受限。阈值限制根据请求类型而有所不同。因此,你可能会遇到这样一种场景,在场景中,写入被限制,但仍允许读取。When a throttling threshold is exceeded, Microsoft Graph limits any further requests from that client for a period of time. When throttling occurs, Microsoft Graph returns HTTP status code 429 (Too many requests), and the requests fail. A suggested wait time is returned in the response header of the failed request. Throttling behavior can depend on the type and number of requests. For example, if you have a high volume of requests, all requests types are throttled. Threshold limits vary based on the request type. Therefore, you could encounter a scenario where writes are throttled but reads are still permitted.

常见的限制场景Common throttling scenarios

客户端受限的最常见原因包括:The most common causes of throttling of clients include:

  • 来自租户中所有应用程序的请求太多。A large number of requests across all applications in a tenant.
  • 来自所有租户中特定应用程序的请求太多。A large number of requests from a particular application across all tenants.

处理限制的最佳实践Best practices to handle throttling

以下是处理限制的最佳做法:The following are best practices for handling throttling:

  • 减少每个请求的操作数量。Reduce the number of operations per request.
  • 减少调用频率。Reduce the frequency of calls.
  • 不要立即重试,因为所有请求都会计入使用限制。Avoid immediate retries, because all requests accrue against your usage limits.

进行错误处理时,使用 HTTP 错误代码 429 检测限制。失败的响应包括 Retry-After 响应标头。使用 Retry-After 延迟回退请求是从限制中恢复的最快速的方式,因为 Microsoft Graph 会在客户端受限时继续记录资源使用状况。When you implement error handling, use the HTTP error code 429 to detect throttling. The failed response includes the Retry-After field in the response header. Backing off requests using the Retry-After delay is the fastest way to recover from throttling because Microsoft Graph continues to log resource usage while a client is being throttled.

  1. 等待 Retry-After 标头中指定的秒数。Wait the number of seconds specified in the Retry-After field.
  2. 请重试请求。Retry the request.
  3. 如果请求再次失败,并显示 429 错误代码,则表示你仍然受限。继续使用建议的 Retry-After 延迟并重试请求直到成功。If the request fails again with a 429 error code, you are still being throttled. Continue to use the recommended Retry-After delay and retry the request until it succeeds.

下列资源目前提供 Retry-After 标头:The following resources currently provide a retry-after header:

有关 Microsoft 云限制的更广泛讨论,请参阅限制模式For a broader discussion of throttling on the Microsoft Cloud, see Throttling Pattern.

服务特定限制Service-specific limits

借助 Microsoft Graph,用户可访问多个服务中的数据,如 Outlook 或 Azure Active Directory。Microsoft Graph allows you to access data in multiple services, such as Outlook or Azure Active Directory. 这些服务实施自己的限制,这些限制会影响使用 Microsoft Graph 访问它们的应用程序。These services impose their own throttling limits that affect applications that use Microsoft Graph to access them.

备注

此处所述的具体限制可能会发生更改。The specific limits described here are subject to change.

Outlook 服务限制Outlook service limits

将评估每个应用 ID 和邮箱组合的 Outlook 服务限制。Outlook service limits are evaluated for each app ID and mailbox combination. 换言之,上述限制适用于访问特定邮箱(用户或组)的特定应用。In other words, the limits described apply to a specific app accessing a specific mailbox (user or group). 如果一个邮箱的应用程序超过限制,不会影响访问另一个邮箱的功能。If an application exceeds the limit in one mailbox, it does not affect the ability to access another mailbox.

限制Limit 适用对象Applies to
10 分钟内的 10,000 个 API 请求10,000 API requests in a 10 minute period v1.0 和 beta 终结点v1.0 and beta
4 个并发请求4 concurrent requests Beta 终结点Beta endpoint
30 秒内的 15 兆位上传(PATCH、POST、PUT)15 megabit upload (PATCH, POST, PUT) in a 30 second period Beta 终结点Beta endpoint

Outlook 服务资源Outlook service resources

Outlook 服务提供以下资源。The following resources are provided by the Outlook service.

日历 API 资源Calendar API resources
邮件 API 资源Mail API resources
个人联系人 API 资源Personal contacts API resources
社交和工作区智能资源Social and workplace intelligence resources
待办任务 API(预览)资源To-do tasks API (preview) resources