Office 365 レポート Web サービスのバージョン管理

  • [アーティクル]

既存の 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 では、サービス バージョン ID に 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 サービスからの応答を特定のサービス バージョンに従って処理するよう指定することが勧められています。アプリケーションが特定のサービス バージョンを指定しない場合、最新のサービス バージョンが想定されます。アプリケーションでは、サービスの更新時にも適切に機能するようにするため、どのサービス バージョンで動作するように設計されているかを常に要求することが勧められています。更新後のサービス バージョンに対してアプリケーションのテストが完了した時点で、アプリケーションが要求するバージョンを更新することができます。

特定のサービス バージョンを要求する

レポート Web サービスは、特定のサービス バージョンを要求するための方法を 2 つ提供しています。アプリケーションでは、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 サービスは、両方が指定された場合、その 2 つが同じサービス バージョンを指定していたとしても、次のエラーを返します。

<?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>

サービス バージョンの指定方法を決定するときは、コードのアーキテクチャを検討してください。アプリケーションでアクセスする必要のあるバージョンが 1 つだけの場合は、HTTP 要求ヘッダーを使用します。アプリケーションで使用するサービス バージョンがレポートごとに異なり、サービス バージョンとは無関係にすべてのレポートについて総称的に HttpRequest を作成している場合は、URI パラメーターを使用します。どちらを選択するにしても、両方は使用しないでください。

Web サービスによって返される X-RWS-Version ヘッダー

クライアント アプリケーションに返されるすべての成功した HTTP 応答と、大部分の成功しなかった応答には、X-RWS-Version ヘッダーが含まれています。このヘッダーは、結果に適用されたサービス バージョン レベルを指定します。アプリケーションが特定のバージョンを指定しなかった場合、レポート Web サービスは最新のサービス バージョンを返します。アプリケーションがバージョンを指定した場合に、そのバージョンが利用可能だったときは、要求されたバージョンでアプリケーションの要求を処理できたことを確認するため、レポートは要求されたサービス バージョンを返します。

ODATA データ サービスのバージョン

Office 365 レポート Web サービスの基礎となっている ODATA インフラストラクチャもバージョンが時々更新され、いずれかの時点でレポート Web サービスにその影響が表れることがあります。関連するヘッダーは、優先する ODATA バージョンを指定する DataServiceVersion と、サービスが対応可能な最大のバージョンを指定する MaxDataServiceVersion の 2 つです。これらのヘッダーも、前のサービス バージョンに対してテストされたシステムの信頼性を継続させるために役立ちます。詳細については、ODATA の「概要」 ページのプロトコル バージョン管理に関するセクション (セクション 7) をご覧ください。

DataServiceVersion HTTP ヘッダー

DataServiceVersion ヘッダーは、指定した DataServiceVersion を ODATA 要求ハンドラーおよびデータ書式設定で使用するように指示します。2012 年 2 月の時点で、該当するサービス バージョンは 2.0 です。DataServiceVersion ヘッダーはレポート応答と一緒に返されるため、使用されたバージョンに互換性があることをアプリケーションが確認できます。

MaxDataServiceVersion HTTP ヘッダー

MaxDataServiceVersion は、指定したものより高いバージョンを使用しないようにレポート Web サービスに指示します。たとえば、現在のバージョンが 2.0 で、次回のメジャー バージョン (3.0) の使用は許可しないことにする場合は、ヘッダーに MaxDataServiveVersion:2.99 と指定します。

Office 365 レポート Web サービスで優先される ODATA バージョン

ODATA クライアントの互換性を高めるため、レポート Web サービスでは要求された内容に応じて次の 2 つの異なる DataServiceVersion 値を使用します。

  • Reporting.svc サービス記述文書では ODATA DataServiceVersion 1.0 を使用します。

  • それ以外のすべてのレポートでは DataServiceVersion 2.0 を使用します。

例

次の例は、このトピックで説明したヘッダーを HttpWebRequest に追加する方法を示しています。ヘッダーは任意の順序で追加できますが、各ヘッダーのコピーを 2 回以上含めることはできません。

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