Office 365 报告 Web 服务返回的错误和状态

除了标准的 HTTP 响应代码，Office 365 报告 Web 服务还会在处理请求出现问题时返回错误。本主题将说明这些问题，提供避免可能出现问题的建议，并帮助开发人员对报告 Web 服务应用程序排除故障。

上次修改时间： 2015年9月17日

适用范围： Office 365

指示错误的位置

您将在四个主要位置收到错误：

HTTP 响应代码

与基于 HTTP 的 Web 服务一样，报告 Web 服务 可以返回 HTTP 响应代码。其定义的标准位置为 http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html。尤其要小心以下错误：

• HTTP 400 错误的请求：在查询出现语法错误，或给出冲突请求信息时返回此错误。您还会获取一个 Atom 或 JSON 响应的错误有效负载，其中包含了详细信息。

• HTTP 403：已禁止：如果传递的凭据有误、帐户管理权限不足或无权限访问请求的报告，则收到此错误。

• HTTP 404：未找到：如果报告名称有误，这在开发过程中是非常常见的错误。

<ServiceFault> XML 文档和 JSON 错误对象

在开发过程中发现的大多数错误来自格式错误的请求、 错误的列名称等。收到错误时，请仔细阅读，因为它们通常会准确告知问题所在。以下是以 JSON 格式返回的错误示例。第一个是错误地键入列名称的结果。

  {
    "error":
      {
        "code":"",
        "message":
          {
            "lang":"en-US",
            "value":"Type 'TenantReporting.MailFilterListReport' does not have a property named 'Organizations'; 
            there is no service action named 'Organizations' that is bindable to the type 
           'TenantReporting.MailFilterListReport'; and there is no type with the name 'Organizations'."
          } 
      }
  }

在 $filter 选项的语法有误时以 Atom 格式返回此错误，在本例中，日期时间字符串的格式错误。

<?xml version="1.0" encoding="utf-8"?>
<m:error xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <m:code />
  <m:message xml:lang="en-US">Unrecognized 'Edm.DateTime' literal 'datetime'2013010T00:00:00'' in '86'.</m:message>
</m:error>

您的应用程序还应注意，可能会收到特定于报告的错误，请适当地进行处理。幸运的是，一旦调试了 URI 构造逻辑，这些错误将很少发生。

空报告结果

某些情况下，报告结果为空是完全正确的。但在其他时候，类似于用户名拼写错误、传输规则大小写错误等小错误及其他小问题似乎不影响运行，但不会产生任何结果。如果具有此类特点的错误尝试调用 MailDetail 报告，则始终不会返回任何数据，因此无需费力尝试。

代码中引发的异常

始终在代码中捕获异常。但通常这些错误是 HTTP 协议处理过程中对正常错误的正常响应，并不是始终与报告 Web 服务相关。

预防问题

下表说明了有助于在开发和使用过程中避免有难度的故障排除任务的最佳做法：

• 不要长时间缓存服务文档或 MailFilterList 结果。您无需每十分钟获取一次，但在具有多个或若干个管理员的大型组织中，会发生命名策略和规则更改情况，这样系统就需要从容地处理这些频率不高的更改。

• 确保服务可用，然后再发起报告请求。请勿假定服务正常运行。通过定期请求服务文档进行检查，并确定呈现您要调用的报告。无需在每次请求时这样做，但在启动应用程序时应这样进行。

• 始终使用名称的 MailFilterList 输出。事项的名称（如数据泄露防护策略和规则名称）通常由管理员输入表单，经常会出现拼写错误。依靠 MailFilterList 结果，可以确保传递到 报告 Web 服务的名称是准确的。

• 使用并验证 $metadata。$metadata 文档包括每个报告的所有字段名称。请考虑使应用程序在启动时检索、验证并使用这些名称。或者，应谨慎地确认应用程序使用的列名称与 $metadata 文档中的列名称一致。

• 在请求中包括服务版本，并检查响应是否具有相同的版本。请注意，只能指定一次服务版本。您的应用程序可以在 HTTP 标头中指定，也可以在 REST URL 中作为一个参数指定。如果两者都提供了，则报告 Web 服务会返回一个错误，即使在两个位置指定相同的服务版本也是如此。

• 不允许在 HttpWebRequest 中重定向。将 AllowAutoRedirect 设置为 false。

• 确认 HTTP 内容长度响应标头与响应缓冲的长度匹配，然后再将数据传递到 XML 分析程序，以及在浏览器中处理 JSON 数据。如果您在其中一个中传递了部分响应，则可能同时导致主要问题和次要问题。

• 显式设置接受语言 HTTP 请求标头。目前，报告 Web 服务的信息还未进行本地化，但可以更改，如果您的客户使用的是不同的语言设置，应用程序可能显示信息有误。

• 在下一次请求中返回所有发送到应用程序的服务器 Cookie。

• 忽略"编辑"链接，某些报告会在 Atom 格式的结果中返回 <link rel="edit" title="" ... /> 条目。报告数据始终为仅读取，您的应用程序不应尝试使用链接修改数据。

• 不要在应用程序中将用户名和密码存储为文本常量，如果必须向用户请求用户名和密码，请将它们安全地存储在 .NET FrameworkSecureString 中。

• 提供日志记录设备。如果应用程序遇到运行时、网络和 Web 服务错误，应能够记录有关请求和响应的所有信息。这有助于您排除故障，而且在 Microsoft 客户支持需要对 Office 365 中的问题进行故障排除时也可能需要这样做。

• 不要调用 MailDetails 报告，因为它始终返回一个空报告。

简单的错误

以下是我们在编写和开发示例应用程序时遇到的一些问题。在熟悉发出报告请求之前，这些都是常见问题。

• 针对文档仔细检查列命名。

• 仔细检查报告命名。报告名称错误时，会返回 HTTP 404 错误。避免此错误的最好方法是仅使用来自 Reporting.svc 服务说明文档的报告名称。

• 包含匹配项时，仅使用来自 MailFilterList 报告的名称。应仅从该文档获取所有邮件处理事件、策略和规则名称，以确保拼写正确，且值确实存在。

• **如果使用 StartDate，必须包括 EndDate。**两者均标记为可选，但如果包括了其中之一，则必须还将另一个包括在内。

• 使用 StartDate、EndDate 或 Date 时，请使用正确的语法。指定日期时间值的 ODATA 语法比其他标准严格得多。ODATA 基元数据类型规范提供了详细信息。

• 请记住 datetime 和 guid 类型在 $filter 选项中的转换。如果没有转换筛选的字符串日期时间和 GUID 值，将收到数据类型不兼容错误。

• 并非所有报告都使用 StartDate 和 EndDate。有关详细信息，请参阅如何：指定报告时间跨度。

• 不要对服务版本请求两次。

• ODATA 仅允许每个查询选项之一。例如，请勿包括两个 $filter 选项。

看起来像问题的正常情况

开发人员和用户有时可能将以下条件看作问题，但可能在报告 Web 服务中为正常：

• **数据无法立即使用。**有关邮件处理、邮件跟踪等大多数类型的信息在几小时内可用于报告。但是，不会有数据显示"即时"。下个日历日之前通常无法创建用户帐户和更改邮箱，这意味着可能有差不多 48 小时的延迟。您的应用程序应考虑此因素，并相应地设置用户的预期。

• 空报告结果有时是正常的，这种情况可能由于严格的时间跨度或严格的匹配标准而产生。如果对您的应用程序来说是正常的，则应为用户提供一些方法，以知悉报告请求成功，但没有任何数据。

• 报告可能要花费数秒钟，具体取决于详细数据量。您的应用程序应对报告检索的时间长度进行计算，提供状态，并相应地设置用户预期。您还可以检索可重试数据市场超时错误。

• 2000 是所有报告可返回的最大行数。

• $top 和 $orderby 选项不受所有报告支持；请检查正在使用的报告的参考文档，以了解是否支持这些查询选项。某些报告会忽略这些选项，且不会指示任何错误。

• **报告数据最终将被删除。**大部分数据将保留一年，邮件跟踪数据仅保留 40 天。详细的邮件跟踪数据仅在最终邮件处理后的 48 小时内可用。在设置报告时间跨度并尝试跟踪邮件传递问题时请记住这一点。

• **Lync 用户必须登录到他们的组织帐户。**组织用户可以作为"访客"参加 Lync 会议，也可以登录到他们的用户帐户。报告中列出的会议资源仅累计参与者登录组织帐户出席的分钟数。此外，对于从移动设备出席的参与者不作累计。是的，您没有看错，如果通过移动设备出席，则视为未出席。

• **不包括通过移动设备的 Lync 参与。**所有 Lync 报告均不包括移动设备上的参与者使用的会话或时间。

• Lync 报告仅包括自行组织的会议 Lync 报告仅返回由组织用户组织的会议的时间和会话计数。由于不同的 Lync Online 计划可能不包括组织会议的功能，但可能仍具有参与会议的功能，因此这种租户中组织的会议数量可能始终返回零。

• MxRecordReport、OutboundConnectorReport 和 ServiceDeliveryReport 仅报告当前条件这三种报告返回有关 Office 365 系统的当前配置和条件的信息。不返回历史或摘要信息。

无法控制的事件

Office 365 报告 Web 服务是一种集成的服务，从各种来源和数据中心接收数据。下表介绍了一些应用程序可能会遇到的情况，这些情况几乎无法控制：

• 报告 Web 服务依赖于 Exchange Online 基础结构。因此，如果 Exchange Online 服务由于计划内或计划外停机时间无法使用，则报告 Web 服务也可能无法使用。

• **Exchange Server 限制策略可能会影响响应次数。**如果应用程序发出多个请求，或仪表板网站使用单个服务帐户收集所有报告数据，则可能会受到请求限制。在 Office 365 中，组织的管理员无法控制限制设置，也无法读取当前设置。请谨慎假定可用的 Office 365 资源量。

• 延迟或断开到数据市场的连接如果报告数据库超载，或已更新大量新信息，报告 Web 服务可能会暂时无法使用或超时。您收到的 ConnectionFailedException 错误将为 "Failed to connect to the datamart." 或类似错误。这对于您的应用程序几乎不是问题，但应重试请求，并最终通知用户，数据或服务可能无法使用。