通过

避免在 SharePoint Online 中受限或遭屏蔽

  • 项目

了解 SharePoint Online 中的限制，并了解如何避免受到限制或阻止。

这听起来是不是很熟悉？ 你正在运行应用程序（例如，在 SharePoint Online 中扫描文件），但会受到限制。 甚至更糟糕的是，你被阻止了。 您应该怎么阻止这一切？

什么是限制？

SharePoint Online 使用限制来保持 SharePoint Online 服务的最佳性能和可靠性。 限制会限制一个时间范围内 API 调用或操作的数量，以防止过度使用资源。

在 SharePoint Online 中被限制时会发生什么？

超过使用限制后，SharePoint Online 会在短时间内限制来自该客户端的任何进一步请求。

对于用户直接在浏览器中执行的请求，SharePoint Online 会将您重定向到限制信息页面，请求将失败。

对于应用程序发出的请求（包括 Microsoft Graph、CSOM 或 REST 调用），SharePoint Online 返回 HTTP 状态代码 429 (“请求过多”) 或 503 (“服务器太忙”) ，请求将失败。

  • HTTP 429 表示调用应用程序在时间范围中发送的请求过多，超出了预先确定的限制。
  • HTTP 503 表示服务尚未准备好处理请求。 常见原因是服务遇到比预期更多的临时负载峰值。

在这两种情况下，Retry-After 标头都包含在响应中，指示调用应用程序在重试或发出新请求之前应等待多长时间。 限制的请求数计入使用限制，因此，如果无法遵循Retry-After可能会导致更多限制。

如果有问题的应用程序继续超过使用限制，SharePoint Online 可能会完全阻止应用程序或应用程序中的特定请求模式;在这种情况下，应用程序将继续获取 HTTP 状态代码 503，Microsoft 将通知 Office 365 消息中心中块的租户。

用户限制

限制限制应用程序代表用户共同进行的调用和操作数，以防止过度使用资源。

也就是说，用户很少会在 SharePoint Online 中受到限制。 该服务非常可靠，旨在处理高容量。 如果确实受到限制，则 99% 的时间是由于自定义代码（如自定义 Web 部件、复杂列表视图和查询）或用户运行的自定义应用。 这并不意味着没有其他限制方式，只是它们不太常见。 例如，一个用户同时在 10 台计算机之间同步大量数据可能会触发限制。

应用程序限制

除了按用户帐户限制外，限制还适用于租户中的应用程序。

每个应用程序在租户中都有自己的限制，这些限制基于每个组织购买的许可证数（请参阅 SharePoint 限制 中列出的计划，了解包含的许可证）。 应用程序跨所有 API 终结点（包括 Microsoft Graph、CSOM 和 REST）发出的每个请求都会计入应用程序的使用情况。

SharePoint 提供各种 API。 不同的 API 具有不同的成本，具体取决于 API 的复杂性。 API 的成本由 SharePoint 规范化，并由资源单位表示。 应用程序的限制也是使用资源单元定义的。

下表定义了租户中应用程序的资源单元限制：

许可证计数 0 – 1k 1k – 5k 5k - 15k 15k - 50k 50k+
应用 1 分钟 1,200 2,400 3,600 4,800 6,000
每日应用 1,200,000 2,400,000 3,600,000 4,800,000 6,000,000

注意

Microsoft保留更改资源单位限制的权利。

对于多租户应用程序：

  1. 托管应用程序的每个租户被视为不同租户，独立于其他租户运行。 因此，每个应用程序在上面定义的每个租户中都受其自己的使用限制的约束。
  2. 应用程序的资源单位消耗量将基于每个租户、每个应用程序进行测量。 这可确保每个租户-应用程序对保持在为该特定租户指定的允许资源限制内。
  3. 如果应用程序在一个租户内达到其资源限制，则此事件不会影响在不同租户中运行的应用程序的其他实例。 每个租户的资源利用率是隔离的，可防止跨租户影响。

在 API 成本方面， Microsoft Graph API 具有每个请求的预定资源单位成本：

每个请求的资源单位数 运营
1
  • 单个项目查询，例如获取项
  • 带令牌的增量
  • 从驱动器项下载文件
    		•
    2
  • 包含令牌的增量除外，多项查询（如列表子项）
  • 创建、更新、删除和上传
    		•
    5
  • 所有权限资源操作，包括$expand=权限
    		•

    注意

    我们保留更改 API 资源单位成本的权利。

    使用令牌的 Delta 是扫描 SharePoint 中内容的最有效方法，我们将更详细地介绍 扫描应用程序的最佳做法。 为了帮助遵循指南的应用程序，我们使用令牌将增量请求的资源单位成本降低到 1 个资源单元，尽管它是一个多项查询。 不带令牌的增量请求被视为多项目查询，每个请求的成本为 2 个资源单位。

    在 批处理中，批处理中的请求按资源单元单独计算。

    CSOM 和 REST 没有预先确定的资源单位成本，它们通常消耗的资源单位比 Microsoft Graph API 更多的资源单位来实现相同的功能。 除了资源单位限制外，CSOM 和 REST 还受其他内部资源限制的约束，因此，如果应用程序调用 CSOM 和 REST，它们可能会遇到比本文档中所述的限制更多的限制。 强烈建议尽可能 选择Microsoft Graph API ，而不要选择 CSOM 和 REST API。

    由于应用程序限制以资源单位为单位，因此实际请求速率（例如每分钟请求数）取决于应用程序的 API 选择和相应的 API 资源单位成本。 一般情况下，可以使用每个请求的平均 2 个资源单位来估计请求速率，并将资源单元限制除以 2，以获取估计的请求速率。

    尽管每个应用程序在一个租户中都有其限制，并且我们允许租户运行多个应用程序，但针对同一租户运行的多个应用程序共享同一个资源桶，在极少数情况下，当过多的应用程序同时发送请求时，可能会导致速率限制。

    如何处理限制？

    下面是处理限制的最佳做法的快速摘要：

    • 减少并发请求数
    • 避免请求高峰
    • 在可能的情况下，选择 Microsoft Graph API ，而选择 CSOM 和 REST API
    • 使用 Retry-After 和 RateLimit HTTP 标头
    • 修饰流量以体现自己是谁（有关详细信息，请参阅下面有关流量修饰最佳做法的部分）

    如前所述， Microsoft Graph 是云原生 API，具有最新的改进和优化。 通常， Microsoft Graph 消耗的资源比 CSOM 和 REST 少，以实现相同的功能。 因此，采用 Microsoft Graph 可以提高应用程序的性能并减少限制。

    如果遇到限制，则需要使用 Retry-After HTTP 标头来确保删除限制之前的最小延迟。 RateLimit HTTP 标头在接近限制时向你发送早期信号，你可以主动减少请求以避免达到限制。

    重试后标头

    当应用程序遇到限制时，SharePoint Online 会在请求中返回Retry-After HTTP 标头，指示调用应用程序在重试或发出新请求之前应等待多长时间（以秒为单位）。

    接受 Retry-After HTTP 标头是处理受限制的最快方法，因为 SharePoint Online 动态确定重试的合适时间。

    限制的请求数计入使用限制，因此，如果无法遵循Retry-After可能会导致更多限制。 换句话说，主动重试适用于调用应用程序，因为即使调用失败，它们仍计入使用限制。 遵循 Retry-After HTTP 标头可确保最短延迟并减少受限制请求中的浪费配额。

    RateLimit 标头 - 预览

    除了 Retry-After 响应受限制的请求中的 标头外，SharePoint Online 还返回某些条件下所选限制的 IETF RateLimit 标头 ，以帮助应用程序管理速率限制。 建议应用程序利用这些标头以避免受到限制。

    • RateLimit-Limit包含当前时间范围中的限制。
    • RateLimit-Remaining指示当前窗口中的剩余配额。
    • RateLimit-Reset指示重新填充配额之前的秒数。

    注意

    这些标头当前处于 beta 版本 中，可能会发生更改。 在采用标头时，IETF 规范在草稿中。 当前实现基于 IETF 规范的 draft-03。 当规范为最终规范时，可能会发生更改，我们将在将来适应这些更改。

    RateLimit 标头将以 最佳方式 返回，因此应用程序可能不会在所有条件下接收标头。 此外， RateLimit 标头中未显示其他限制，因此，甚至在达到 RateLimit 标头中所述的限制之前，应用程序仍可以受到限制。 下面是我们支持 RateLimit 标头的限制列表。 策略和值可能会发生更改：

    limit 条件 限制值 说明
    应用 1 分钟资源单位 使用情况 >= 限制的 80% 资源单位 当应用程序使用其应用 1 分钟限制的 80% 或更多时，将返回限制、剩余和重置。

    下面是一些示例，可帮助你了解 RateLimit标头：

    • 应用程序已消耗其 90% 的资源单位配额（1，080 个，共 1，200 个），其使用量在应用到它的所有限制范围内。 请求成功，并返回RateLimit标头。
    HTTP/1.1 200 Ok
RateLimit-Limit: 1200
RateLimit-Remaining: 120
RateLimit-Reset: 5
    • 应用程序已消耗其 100% 的资源单位配额，因此由于此策略，应用程序会受到限制。 请求受到限制，并返回RateLimit标头。 Retry-After匹配RateLimit-Reset。
    HTTP/1.1 429 Too Many Requests
Retry-After: 31
RateLimit-Limit: 1200
RateLimit-Remaining: 0
RateLimit-Reset: 31
    • 应用程序已消耗 90% 的资源单位配额，但其消耗已达到 RateLimit标头不支持的其他限制。 在这种情况下，请求受到限制，并且RateLimit标头不会返回以避免混淆，尽管满足返回标头的条件。
    HTTP/1.1 429 Too Many Requests
Retry-After: 9

    可以在 SharePoint Online 中使用 RateLimit 标头在应用程序中防止限制中找到其他信息

    如何修饰 HTTP 流量？

    修饰良好的流量优先于未正确修饰的流量。

    未修饰流量的定义是什么？

    • 如果对 SharePoint Online 的 API 调用中没有 AppID/AppTitle 和用户代理字符串，则不会对流量进行修饰。 User-Agent 字符串应采用特定格式，如下所述。
    • 如果要开发在浏览器中执行的 Web 应用程序，大多数新式浏览器不允许覆盖用户代理字符串，也不需要实现它。

    有哪些建议？

    • 如果已创建应用，建议注册并使用 AppID 和 AppTitle。这样，可确保为今后解决任何问题提供最佳总体体验和最佳途径。 还包括以下步骤中定义的用户代理字符串信息。

      注意

      有关创建 Azure AD 应用程序的信息，请参考 Microsoft 标识文档，例如快速入门：向 Microsoft 标识平台注册应用程序页面。

    • 确保使用以下命名约定在对 SharePoint 的 API 调用中包含 User-Agent 字符串

    类型 用户代理 说明
    ISV 应用 ISV |CompanyName |AppName/Version 标识为 ISV，并包括公司名称、由管道字符分隔的应用名称，然后添加用斜杠字符分隔的版本号
    企业应用 NONISV |CompanyName |AppName/Version 标识为 NONISV，并添加公司名称、应用名称（用竖线符隔开），再添加版本号（用斜线符隔开）
    • 如果要构建自己的 JavaScript 库（这些库用于调用 SharePoint Online API），请确保将 User-Agent 信息包含在 HTTP 请求中，并在适用的情况下将 Web 应用程序注册为应用程序。

    注意

    用户代理字符串的格式应遵循 RFC2616，因此请在右侧分隔符上遵循上述指南。 还可以使用请求的信息追加现有用户代理字符串。

    SharePoint Online 中常见的限制场景

    导致 SharePoint Online 中出现用户限制最常见的原因是以太高的频率执行太多操作的客户端对象模型 (CSOM) 或代表性状态传输 (REST) 代码。

    • 突发通信

      必须优化针对 SharePoint Online 的恒定负载或重复的复杂查询，以降低影响。 对于批量处理文件的应用程序，如果未能遵循扫描该类应用程序的最佳做法，则可能会导致限制。 这些应用包括同步引擎、备份提供程序、搜索索引器、分类引擎、数据丢失防护工具以及任何其他工具，这些工具尝试对整个数据进行推理并对其应用更改。

    • 无比拥挤的通信

      单个进程在很长一段时间内会持续显著超出限制。

      • 您使用 Web 服务构建同步用户配置文件属性的工具。 该工具将根据您的业务线 (LOB) 人力资源 (HR) 系统中的信息更新用户配置文件属性。 该工具以太高的频率发出调用。
      • 在 SharePoint Online 上运行负载测试脚本但受到限制。 SharePoint Online 上不允许进行负载测试。
      • 例如，您在 SharePoint Online 上对您的工作组网站进行了自定义设置，方法是在主页上添加了一个状态指示器。 此状态指示器频繁更新，这会导致页面向 SharePoint Online 服务发出太多调用，从而触发限制。
      • 运行 OneDrive 同步客户端的同时运行迁移应用程序或爬网和回写数据的应用程序，可能导致高请求量而触发限制。

    • 不支持的用例

      不支持的 SharePoint Online 使用可能会受到限制。 将 SharePoint 和 OneDrive 用作 Microsoft 365 与其他存储库之间的中介服务是不受支持的用例示例。

    • 为同一应用程序创建多个 AppID

      不要在应用程序实质上执行相同操作（如备份或数据丢失防护）的情况下创建单独的 AppID。 针对同一租户运行的应用程序最终与租户共享相同的资源。 过去，一些应用程序已尝试使用此方法来绕过应用程序限制，但最终耗尽了租户的资源，并导致租户中多个应用程序受到限制。

    方案特定的限制

    对 Sites.Read.All 权限使用仅限应用的身份验证时

    当您将 SharePoint Online 搜索 API 与仅应用身份验证配合使用，并且应用程序具有 Sites.Read.All 权限 (或更强) 时，该应用程序将注册完全权限，并允许查询您的所有 SharePoint Online 内容 (包括用户的专用 OneDrive for Business 内容) 。

    为了确保服务保持快速且可靠，使用此类权限的查询将限制为每秒 25 个请求。 搜索查询将返回 HTTP 429 响应。 在等待限制恢复时，应确保暂停可能使用类似仅限应用的权限对服务发出的所有搜索查询请求。 在接收限制响应时进行更多调用将延长应用不受限制所需的时间。

    使用委派的用户权限进行搜索时

    当应用程序提交具有已登录用户权限的搜索查询请求时，会使用委派的用户权限进行搜索。 委托请求的示例如下：SharePoint 页面上的搜索框、SharePoint 页面上嵌入的基于搜索的 Web 部件或自定义应用程序，以及查询项信息的 Power Automate 工作流。

    为了确保服务稳定性，该服务将限制每个用户每秒超过 10 个请求的委托用户请求。 此每用户限制将跨来自所有应用的所有请求进行聚合。 如果单个用户每秒发送超过 10 个搜索查询请求，则返回 HTTP 429。 请求应用程序应在发送后续请求之前等待响应标头中指定的超时持续时间。 在设计基于搜索的应用程序、SharePoint 页面和工作流时，实施者应确保页面和应用程序每秒的总请求数不超过 10 个，并处理 429 个限制响应。 有关页面设计和搜索优化的详细信息和指南，请参阅 优化 SharePoint Online 新式网站页面中的搜索请求 和使用 SharePoint Online 的页面诊断工具。

    搜索人员搜索结果时

    使用请求人员结果的结果源进行搜索时，我们可能会限制超过组织范围内每秒 25 个请求数限制的任何请求。 此限制适用于使用现成的“本地人员结果”结果源或自定义人员搜索结果源的所有 SharePoint 搜索 CSOM 和 REST 请求。

    如果你有导致人员搜索请求受到限制的应用程序或组件，我们建议你：

    1. 考虑应用程序是否需要请求。 例如，如果使用的是同时进行许多查询的自定义搜索网站，请检查是否可以删除其中一些请求，而不会对组织的搜索体验产生任何重大影响。 或者，考虑通过从 SharePoint 起始页搜索来尝试 Microsoft 搜索 中的新式人员搜索体验。 Microsoft 搜索中的人员搜索已进行了优化，以获得更好的性能和更相关的结果。
    2. 避免发出并发请求。 例如，不是一次发出 10 个请求，而是连续发出它们 - 仅在上一个查询完成后发出下一个查询。 如果需要快速缓存这些结果（例如页面加载），则可能需要考虑缓存这些结果。
    3. 尝试将请求合并到单个查询中。 例如，尝试使用单个查询，而不是同时对 WorkEmail:user1@constoso.com,..., WorkEmail:user2@constoso.comWorkEmail:user10@contoso.com进行 10 个查询WorkEmail:user1@constoso.com WorkEmail:user2@constoso.com ... WorkEmail:user10@contoso.com。
    4. 如果确实需要高请求量方案（每秒超过 25 个请求），请考虑使用 Microsoft Graph API。

    如果我在 SharePoint Online 中被阻止，该怎么办？

    阻止是限制最极端的形式。 除非我们检测到可能威胁 SharePoint Online 服务整体运行状况的长期过多流量，否则我们很少阻止租户。 我们应用阻止的目的是，防止因过多的流量降低 SharePoint Online 的性能和可靠性。 阻止发生在应用程序或用户级别，它会阻止有问题的进程运行，直到你解决问题为止。 如果我们阻止了你的订阅，你必须采取操作修改有问题的进程，然后才能将阻止移除。

    如果我们阻止你的订阅，我们将在 Office 365 消息中心中通知你该块。 该消息将描述导致阻止的原因，提供有关如何解决违规问题的指南，并告诉你应该联系谁以移除阻止。

    另请参阅