Office 365 报告 Web 服务中的版本控制

项目
12/20/2016

为了确保与现有 Office 365 报告 Web 服务客户端未来的兼容性，Web 服务接受一个 X-RWS-Version HTTP 标头或一个rws-version URI 参数。ODATA 服务也具有您的应用程序应使用的版本兼容性标头。此时（2013 年 2 月），唯一适用于此功能的有效服务版本是 2013-V1。本主题介绍如何使用服务和 ODATA 数据服务版本。

上次修改时间： 2015年12月7日

适用范围： Office 365

Office 365 报告 Web 服务版本

诸如 Office 365 的在线服务收到添加功能及修复问题的频繁更新。Office 365 使用 YEAR-V# 形式的服务版本标识符。YEAR 是版本普遍向大多数订阅者提供的日历年。# 表示该年份的版本号。截至 2013 年 3 月，主流有效的版本是 2013-V1。前一版本是 2012-V1；但是，该服务版本中一般不提供 Office 365 报告 Web 服务服务。对使用 2012-V1 版本的请求将返回一个包含 <Message>The version specified in the request is unsupported.</Message> 消息的错误。

为了帮助确保客户端与未来服务版本相兼容，应用程序应当根据特定服务版本指定对要处理的报告 Web 服务的请求的去向和响应的来向。如果应用程序不要求特定的服务版本，则采用最新的服务版本。您的应用程序应始终要求使用它适用的服务版本，以便该应用程序在服务更新时还能够继续正常工作。当针对更新的服务版本完成应用程序测试后，就可以对该应用程序所要求的版本进行更新。

请求特定的服务版本

报告 Web 服务提供两种请求特定服务版本的方法。应用程序可以在 HTTP 请求中使用 X-RWS-Version 标头，或者它也可以提供 rws-version URI 参数。

X-RWS-Version HTTP 请求标头整体外观如：X-RWS-Version:2013-V1。

rws-version URI 参数实际外观如：rws-version=2013-V1。以下示例请求能用来处理 StaleMailbox 报告的服务版本 2013-V1。

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/StaleMailbox?rws-version=2013-V1&
  $select=ActiveMailboxes,Date,InactiveMailboxes31To60Days,InactiveMailboxes61To90Days,InactiveMailboxes91To1460Days&
  $top=1&
  $format=Atom

重要

不要在同一个报告请求中提供 HTTP 标头和 URI 参数。当报告 Web 服务遇到它们两个同时出现时，即使它们请求的是同一个服务版本，也会返回以下错误。

<?xml version="1.0" encoding="utf-8"?>
<ServiceFault xmlns="http://schemas.datacontract.org/2004/07/Microsoft.Exchange.Management.ReportingWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorCode />
  <Message>The API version is specified in both request URL and header.</Message>
</ServiceFault>

要确定如何显示服务版本，需考虑代码架构。如果您的应用程序只需要访问一个版本，就使用 HTTP 请求标头。如果您的应用程序对不同报告使用不同的服务版本，并且在无论服务版本如何通常均为所有报告创建了 HttpRequest 的情况下，就使用 URI 参数。无论采用哪种方式，都不要二者同时使用。

Web 服务返回的 X-RWS-Version 标头

所有返回到客户端应用程序的成功 HTTP 响应，以及大多数不成功的响应，均包含 X-RWS-Version 标头。该标头将指定适用于结果的服务版本级别。当应用程序没有指定任何特定版本时，报告 Web 服务会返回最新的服务版本。当应用程序指定了一个版本时，如果该版本可用，报告将返回所请求的服务版本，以确认该应用程序的请求可在请求的版本中使用。

ODATA 数据服务版本

基于 Office 365 报告 Web 服务构建的 ODATA 基础架构也有时时更新的版本，并可能在某种情况下会显示在报告 Web 服务中。有两个标头：一个是指定首选 ODATA 版本的 DataServiceVersion，另一个是指定服务不能超出的版本的 MaxDataServiceVersion。这些标头也可以帮助确保针对前一个服务版本对系统的持续可靠性进行测试。有关详细信息，请参阅 ODATA 概述页面中关于协议版本控制的一节（第 7 节）。

DataServiceVersion HTTP 标头

DataServiceVersion 标头指示 ODATA 请求处理程序和数据格式化使用显示的 DataServiceVersion。截至 2012 年 2 月，相应的服务版本是 2.0。在报告响应中返回一个 DataServiceVersion 标头，以便应用程序可以确认所使用的版本是兼容的。

MaxDataServiceVersion HTTP 标头

MaxDataServiceVersion 指示报告 Web 服务不使用任何比所提供版本更高的版本。例如，如果当前版本是 2.0，并且您希望不允许使用下一个主要版本 (3.0)，就使用 MaxDataServiveVersion:2.99 来指定标头。

Office 365 报告 Web 服务首选的 ODATA 版本

为了确保与 ODATA 客户端更加兼容，报告 Web 服务根据请求内容使用两个不同的 DataServiceVersion 值：

Reporting.svc 服务描述文档使用 ODATA DataServiceVersion 1.0。
其他所有报告使用 ODATA DataServiceVersion 2.0。

示例

以下示例演示如何将本主题中所描述的标头添加到 HttpWebRequest。可以按照任何顺序添加标头，但其中包含的每一标头副本都不能超过一个。

  //
  // First, create the web request object to add the versioning information and other headers to.  
  HttpWebRequest request = 
    (HttpWebRequest)HttpWebRequest.Create("https://reports.office365.com/ecp/reportingwebservice/reporting.svc");
  request.Method = "GET";
  //
  // This header specifies the ODATA provider's minimum version. Because we use $select in later queries,
  // we need to have at least ODATA2. And since we don't (yet) support anything higher than 2.0, we'll give
  // that as a maximum also.
  request.Headers.Add("DataServiceVersion", "2.0");
  request.Headers.Add("MaxDataServiceVersion", "2.0");
  //
  // Add the RWS language header.
  request.Headers.Add("Accept-Language","EN-US");
  //
  // Add the RWS service version section header.
  request.Headers.Add("X-RWS-Version","2013-V1");
  //
  // For authentication reasons, avoid redirecting the HTTPS request.
  request.AllowAutoRedirect = false;
  //
  // The "simple" way to get the Basic-authentication credentials: 
  request.Credentials = new NetworkCredential(userNameEntered, passwordEntered);
  //
  // Make the Web call here. This is normally done using asynchronous methods so that the application
  // interface is not blocked waiting for the service to respond.
  HttpWebResponse response = (HttpWebResponse)request.GetResponse();

通过