了解 SharePoint Online 中的限制以及如何避免受限制或被阻。其中包括可用于简化任务的示例客户端对象模型 (CSOM) 和 REST 代码。

• 什么是限制？
• SharePoint Online 中常见的限制场景
• 为什么不能告诉我确切的限制？
• 使用仅具有 Sites.Read.All 权限的仅应用身份验证时的搜索查询数量限制
• 处理限制的最佳做法
• 如何修饰流量以免受限？
• GitHub CSOM 代码示例：SharePoint Online 限制
• 如果我在 SharePoint Online 中被阻止，该怎么办？
• 其他资源

这听起来是不是很熟悉？举例来说，你正在运行 CSOM 过程以迁移 SharePoint Online 中的文件，但一直受限制，甚至更糟糕的是，你被阻止了。接下来会发生什么？应怎样做才能阻止这一切？

什么是限制？

SharePoint Online 使用限制来维护 SharePoint Online 服务的最佳性能和可靠性。限制会限制用户操作或并发调用数量（通过脚本或代码），以防止资源的过度使用。

也就是说，很少有用户会在 SharePoint Online 中受到限制。 该服务非常强大，其设计旨在处理高容量信息。 如果你被限制，99% 都是因为自定义代码。 这并不意味着没有其他限制方式，只是它们不太常见。 例如，你启动了 10 台计算机，并在这 10 台计算机上运行一个同步客户端。 每台计算机同步 1 TB 的内容。 这可能会使您被限制。

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

当用户超过使用限制时，SharePoint Online 会限制该用户帐户发出的任何进一步请求，但通常只是短时间内。在用户限制的有效期内，将限制该用户的所有用户操作。

• 对于用户直接在浏览器中执行的请求，SharePoint Online 会将您重定向到限制信息页面，请求将失败。
• 对于所有其他请求（包括 CSOM 或 REST 调用），SharePoint Online 将返回 HTTP 状态代码 429（“请求过多”）或 503（“服务器太忙”），且请求将失败。

如果有问题的进程仍然超过使用限制，SharePoint Online 可能会完全阻止该进程；在这种情况下，你将看不到任何成功的请求，Microsoft 会在 Office 365 消息中心向你提供有关此阻止的通知。

应用程序限制

除了按用户帐户限制外，还会对租户中的每个应用程序实施限制。 SharePoint Online 中的每个应用程序都有租户自己的可用资源，但针对同一租户运行的多个应用程序最终会共享同一资源存储桶，并且在极少数情况下会导致速率受限。 在这些情况下，SharePoint Online 将尝试通过后台活动确定交互式用户请求的优先级。

SharePoint Online 中常见的限制场景

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

• 突发通信

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

  例如，将文件迁移到 SharePoint Online 之后，您运行自定义 CSOM 或 REST 脚本以更新文件上的元数据。CSOM/REST 脚本以高频率更新大量文件，这将触发限制。与此类似，使用 REST 服务的自动完成 UI 小部件在每个最终用户操作中向列表发出太多的调用，也可能导致限制，具体取决于哪些其他操作也在同时消耗资源。

  

• 无比拥挤的通信

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

  • 您使用 Web 服务构建同步用户配置文件属性的工具。该工具将根据您的业务线 (LOB) 人力资源 (HR) 系统中的信息更新用户配置文件属性。该工具以太高的频率发出调用。

  • 您在 SharePoint Online 上运行负载测试脚本但受到限制。SharePoint Online 上不允许进行负载测试。

  • 例如，您在 SharePoint Online 上对您的工作组网站进行了自定义设置，方法是在主页上添加了一个状态指示器。此状态指示器频繁更新，这会导致页面向 SharePoint Online 服务发出太多调用，从而触发限制。

  • 运行 OneDrive 同步客户端的同时运行迁移应用程序或爬网和回写数据的应用程序，可能导致高请求量而触发限制。

    

• 不支持的用例

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

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

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

为什么不能告诉我确切的限制？

设置和发布确切的限制上限听起来很简单，但事实上它会导致更严格的限制。 我们会持续监控 SharePoint Online 上的资源使用情况。 根据使用情况，我们会对阈值进行微调，以便用户可以使用最大数量的资源，而不会降低 SharePoint Online 的可靠性和性能，并会根据租户的整体用户流量、使用情况，以及其他一些因素，设定应用程序限制。

这就是代码需遵循 Retry-After HTTP 标头值的重要原因所在；这使得你的代码在任何给定的日期都能尽可能快地运行，并且如果它达到限制上限，它可以使代码“恰量”回退。 本文稍后部分的代码示例将向你展示如何使用 Retry-After HTTP 标头。

使用仅具有 Sites.Read.All 权限的仅应用身份验证时的搜索查询数量限制

在 SharePoint 和 OneDrive 中，我们处理数十亿个文档，并使客户能够每秒发出大量查询。 当你使用具有仅应用身份验证的 SharePoint Online 搜索 API 且该应用具有 Sites.Read.All 权限（或更高权限）时，该应用将被注册具有完全权限，并被允许查询你的所有 SharePoint Online 内容（包括用户的私有 ODB 内容）。

我们希望告知客户，使用此类权限的 SharePoint Online 搜索查询将被限制为 25 个查询 (QPS)。 搜索查询将以 429 响应返回，你可以在 2 分钟后重试该查询。 等待 429 恢复时，你应确保使用相似的“仅应用”权限暂停对服务提出的所有搜索查询请求。 在收到限制响应的同时拨打其他电话会延长你的应用限制的时间。

在扩展系统规模时，我们意识到加强系统的效率以使其高效运行并保护系统的重要性，因此也需要进行这种更改。 预计这一变化将于 8 月到 2020 年秋季推广到租户。

处理限制的最佳实践

• 减少每个请求的操作数
• 减少调用频率
• 如果可能，优先选择 Microsoft Graph API，其次是 CSOM 和 REST API
• 修饰流量以体现自己是谁（有关详细信息，请参阅下面有关流量修饰最佳做法的部分）
• 利用 Retry-After HTTP 标头

Microsoft Graph 是诞生在云端的 API，拥有最新的改进和优化功能。 通常，Microsoft Graph 可以比 CSOM 和 REST 使用更少资料，即可实时相同的功能。 采用 Microsoft Graph 可以提高应用程序性能并减少限制。

如果你遇到限制，我们需要利用 Retry-After HTTP 标头来确保最小延迟，直到限制被移除。

Retry-After HTTP 是处理受限制最快速的方法，因为 SharePoint Online 会动态确定重试的正确时间。 换句话说，主动重试将对你不利，因为即使调用失败，它们仍会计入你的使用限制。 遵循 Retry-After HTTP 标头将确保最短的延迟。

有关 SharePoint Online 活动监视方式的详细信息，请参阅诊断 SharePoint Online 的性能问题。

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

如何修饰 http 流量以免受限？

为了确保和保持高可用性，一些流量可能会受到限制。 当系统健康受到威胁时，就会出现限制。一种适用于限制的条件是流量修饰，这可直接影响流量的优先级。 良好修饰的流量优先于未正确修饰的流量。

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

• 如果对 SharePoint Online 执行的 CSOM 或 REST API 调用中没有 AppID/AppTitle 和用户代理字符串，那么流量就未经修饰。 用户代理字符串应采用如下所述的特定格式。

有哪些建议？

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

   备注

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

• 务必使用以下命名约定，在对 SharePoint 执行的 API 调用中添加用户代理字符串

• 若要生成自己的 JavaScript 库来调用 SharePoint Online API，请务必将用户代理信息添加到 http 请求中，并在合适、可能的情况下将 Web 应用程序还是注册为应用程序。

使用客户端对象模型 (CSOM) 时通过用户代理修饰流量的示例

// Get access to source site
using (var ctx = new ClientContext("https://contoso.sharepoint.com/sites/team"))
{
  //Provide account and pwd for connecting to SharePoint Online
  var passWord = new SecureString();
  foreach (char c in pwd.ToCharArray()) passWord.AppendChar(c);
  ctx.Credentials = new SharePointOnlineCredentials("contoso@contoso.onmicrosoft.com", passWord);

  // Add our User Agent information
  ctx.ExecutingWebRequest += delegate (object sender, WebRequestEventArgs e)
  {
      e.WebRequestExecutor.WebRequest.UserAgent = "NONISV|Contoso|GovernanceCheck/1.0";
  };

  // Normal CSOM Call with custom User-Agent information
  Web site = ctx.Web;
  ctx.Load(site);
  ctx.ExecuteQuery();
}

使用 REST API 时通过用户代理修饰流量的示例

下面的示例采用 C# 格式，但建议也对 SharePoint Online 页面中使用的 JavaScript 库使用类似的用户代理信息。

{retryCount}, has be attempted.");
}

[Serializable]
public class MaximumRetryAttemptedException : Exception
{
  public MaximumRetryAttemptedException(string message) : base(message) { }
}

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

阻止是限制最极端的形式。我们极少阻止租户，除非我们检测到可能会影响 SharePoint Online 服务整体运行状况的长期高通信量。我们将进行阻止，以防超高通信量使 SharePoint Online 的性能和可靠性降级。阻止发生在应用或用户级别，它会阻止有问题的进程在特定时间段内或者在您解决问题之前运行。如果我们阻止了您的订阅，您必须执行操作修改有问题的进程，然后才能移除阻止。

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