Управление версиями в веб-службе отчетов Office 365

Статья
11/14/2016

Для обеспечения будущей совместимости с существующими клиентами, Веб-служба отчетов Office 365 , веб-служба принимает параметр URI rws-version или X-RWS-Version HTTP-заголовка. Служба ODATA также имеет заголовки совместимость версий, в приложении следует использовать. В настоящее время (февраль 2013) версию обновления допустим только для этой функции — 2013-V1. В этом разделе описывается работа со службой и версии службы данных ODATA.

Дата последнего изменения: 7 декабря 2015 г.

Область применения: Office 365

Веб-службы Office 365 отчетов версии

Службы, такие как Office 365 получать частые обновления, добавляющие функциональность и устранения проблем. Office 365 использует идентификаторы версий служб в форме YEAR-V#. YEAR является календарный год, в котором выпуска станет общедоступным для большинства подписчиков. # указывает номер года выпуска. По состоянию на март 2013 г основных обслуживаемых версии — 2013-V1. Предыдущая версия была 2012-V1; Однако Веб-служба отчетов Office 365 не обычно доступны в этой версии службы. Запросы на использование версии 2012-V1 возвратит сообщение об ошибке, содержащее <Message>The version specified in the request is unsupported.</Message>.

Для обеспечения совместимости клиента в будущих версиях приложения следует указывать по запросу и ответы от Веб-служба отчетов обрабатываются в соответствии с версией службы. Если приложение запрашивает версии службы, считается самую последнюю версию службы. Приложение всегда запрашивать версию обновления, она была разработана для работы с таким образом может продолжать работать правильно при обновлении службы. После проверки приложения обновленную версию, можно обновить версию, приложение запрашивает.

Запрос версии службы

Веб-служба отчетов предоставляет два способа запроса версии определенной службы. Приложения могут использовать заголовок X-RWS-Version в HTTP-запросе, или он может предоставлять параметр URI rws-version .

X-RWS-Version HTTP заголовка запроса выглядит следующим образом по сети: X-RWS-Version:2013-V1.

Параметр URI rws-version выглядит следующим образом, на практике: 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 в запросе отчета. Когда Веб-служба отчетов обнаруживает, даже если они предназначены для одной и той же версии службы, будет возвращено следующее сообщение об ошибке.

<?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. Независимо от выбранного метода, не используйте их вместе.

Заголовок X-RWS-версии, возвращаемых веб-службой

Все успешные HTTP-ответы и наиболее неудачных ответов, которые возвращаются в клиентском приложении включать заголовок X-RWS-Version . Заголовок, определить уровень версии службы, применяемое к результатам. Если приложение не указывает любой конкретной версии, Веб-служба отчетов возвращает самую последнюю версию обновления. Когда приложение указать версию, если эта версия является доступной, отчет возвращает версию запрошенную службу для подтверждения, что запрос приложения может обслуживаться в нужной версии.

Версии службы данных ODATA

Инфраструктура ODATA, на которой создано Веб-служба отчетов Office 365 также имеет версии, которые время от времени обновляются и скорее всего будет отображаться в Веб-служба отчетов в некоторой точке. Существуют два заголовка: DataServiceVersion , который задает предпочтительную версию ODATA и MaxDataServiceVersion , которое указывает версию, которая не должна превышать службы. Эти заголовки и обеспечить продолжение надежность систем, проверяемое на соответствие предыдущей версии службы. Дополнительные сведения содержатся в разделе Управление версиями протокола ODATA.

DataServiceVersion HTTP-заголовок

Заголовок DataServiceVersion указывает, что обработчик запросов ODATA и данные форматирования для использования указанного DataServiceVersion. По состоянию на февраль 2012 г. версия обновления равна 2.0. Заголовок DataServiceVersion возвращается с ответом отчета таким образом, приложение можно убедиться, что используется версия совместима.

MaxDataServiceVersion HTTP-заголовок

MaxDataServiceVersion указывает, что Веб-служба отчетов не будет использовать любой версии выше, чем предоставляется. Например если не хотите разрешить следующей основной версии (3.0) для использования является текущей версии 2.0, укажите заголовок с MaxDataServiveVersion:2.99.

Веб-служба отчетов Office 365 основной версии ODATA

Для обеспечения совместимости с клиентами ODATA, Веб-служба отчетов использует два 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();