共用方式為

在 「 Office 365 報告 」 web 服務的版本控制

  • 發行項

若要確保未來的相容性與現有的Office 365 Reporting web service用戶端，web 服務會接受X-RWS-Version HTTP 標頭或rws-version URI 參數。ODATA 服務也會有您的應用程式應該使用的版本相容性標頭。這一次 (年 2 月，2013) 這項功能的唯一有效的服務版本會是2013-V1。本主題說明如何使用服務和 ODATA 資料服務版本。

前次修改時間: 2015年12月7日

適用於: Office 365

Office 365 報告 web 服務版本

線上服務，例如Office 365收到頻繁的更新，加入功能，並修正問題。Office 365會使用表單YEAR-V#中的服務版本識別項。YEAR是在發行成為通常用於大多數的 「 訂閱者 」 的行事曆年份。#會指示年的版本號碼。年 3 月 2013年主流服務中的版本會是2013-V1。先前的版本是2012-V1。不過， Office 365 Reporting web service不是通常可以在該服務版本。若要使用2012-V1版的要求會傳回包含<Message>The version specified in the request is unsupported.</Message>錯誤。

若要協助確保與未來的服務版本的用戶端相容性，應用程式應該指定的要求，並依照特定的服務版本處理來自Reporting web service回應。如果應用程式不要求特定的服務版本時，會假設最新的服務版本。您的應用程式應該只是要求其用意是要讓它可以繼續運作正確更新服務時使用的服務版本。測試過您的應用程式針對更新的服務版本之後，您可以更新應用程式要求的版本。

要求特定的服務版本

Reporting web service提供兩種方式可以要求特定的服務版本。應用程式可以使用X-RWS-Version標頭中的 HTTP 要求，或者它可以提供rws-version URI 參數。

透過網路X-RWS-Version HTTP 要求標頭看起來像這樣： X-RWS-Version:2013-V1。

在練習中rws-version URI 參數看起來像這樣： rws-version=2013-V1。下列範例會要求該服務版本2013-V1用來處理 StaleMailbox 報表。

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 參數在同一個報表要求。當Reporting web service遇到兩者皆是，即使它們是相同的服務版本時，它會傳回下列錯誤。

<?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 版本標頭

所有成功的 HTTP 回應和最成功回應，會傳回至用戶端應用程式包含X-RWS-Version標頭。該標頭會指定適用於結果的服務版本層級。當應用程式並未指定任何特定的版本時， Reporting web service會傳回最新的服務版本。當應用程式不會指定一個版本，如果使用該版本時，報表就會傳回要求的服務版本，以確認可以在要求的版本中提供服務應用程式的要求。

ODATA 資料服務版本

Office 365 Reporting web service內建的 ODATA 基礎結構也有隨時更新，並可能出現在Reporting web service在某個時間點的版本。有兩個標頭: 指定慣用的 ODATA 版本， DataServiceVersion和MaxDataServiceVersion所指定的服務不應超過的版本。這些標頭也協助您確保持續維持的可靠性，為測試對服務上的舊版的系統。如需詳細資訊，請參閱ODATA 通訊協定版本。

DataServiceVersion HTTP 標頭

DataServiceVersion標頭會指示資料格式要使用指定的 DataServiceVersion 與 ODATA 要求處理常式。年 2 月，2012 年的適當的服務版本為 2.0。DataServiceVersion標頭傳回報表的回應，以便應用程式可以確認使用的版本相容。

MaxDataServiceVersion HTTP 標頭

MaxDataServiceVersion會指示Reporting web service不想使用任何高於提供一個版本。例如，如果目前的版本 2.0 中，則您不想允許要使用的下一個主要版本 (3.0)，請使用MaxDataServiveVersion:2.99指定標頭。

Office 365 報告 web 服務慣用 ODATA 版本

若要確保更高的相容性與 ODATA 用戶端， Reporting web service會使用兩個不同 DataServiceVersion 值，根據要求的項目：

  • Reporting.svc服務描述文件會使用 ODATA DataServiceVersion 1.0。

  • 所有其他報表使用 ODATA DataServiceVersion 2.0。

範例

下列範例示範如何將HttpWebRequest本主題所述的標頭。可以以任何順序加入標頭，但您不應該包含一份以上的每個標頭。請參閱Accept-Language HTTP header and the Reporting web service如需有關指定的文化特性和語言的標題名稱資訊。

  //
  // 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();