Versionsverwaltung in den Webdienst Office 365 Reporting

Artikel
11/14/2016

Um zukünftige Kompatibilität mit vorhandenen Office 365-Berichterstattungswebdienst Clients sicherzustellen, akzeptiert der Webdienst einen HTTP-Header X-RWS-Version oder rws-version -URI-Parameter. Der ODATA-Dienst hat auch die Versionskompatibilität Header, die die Anwendung verwenden soll. Zu diesem Zeitpunkt (Februar 2013) ist die einzige gültige Service-Version für dieses Feature 2013-V1. Dieses Thema beschreibt, wie mit Service und ODATA Data Service-Versionen arbeiten.

Letzte Änderung: Montag, 7. Dezember 2015

Gilt für: Office 365

Office 365 Reporting Web Service-Versionen

Online-Dienste wie Office 365 erhalten regelmäßige Updates, die zusätzliche Funktionen und Probleme zu beheben. Office 365 wird in der Form YEAR-V#Service-Versions-Identifier verwendet. YEAR ist das Kalenderjahr, in dem die Veröffentlichung in der Regel für die meisten Abonnenten verfügbar wird. Die # gibt die Versionsnummer für das Jahr an. Ab März 2013 ist die mainstream in Betrieb befindlichen Version 2013-V1. Die Vorgängerversion war 2012-V1; die Office 365-Berichterstattungswebdienst war jedoch nicht in diesem Service-Version erhältlich. Anforderungen an die 2012-V1 -Version verwenden, werden einen Fehler mit der <Message>The version specified in the request is unsupported.</Message>zurück.

Zum Clientkompatibilität mit künftigen Versionen zu gewährleisten, sollten Anwendungen angeben, der Anforderungen an, und Antworten aus den Berichterstattungswebdienst nach einem bestimmten Dienstversion behandelt werden. Wenn die Anwendung eine bestimmte Version keine anfordert, wird die neueste Version des Service angenommen. Die Anwendung sollte immer Service-Version anfordern, die es entwickelt wurde, um mit zu arbeiten, damit es ordnungsgemäß weiterarbeiten kann während der Service aktualisiert wird. Nachdem Sie Ihre Anwendung mit einer aktualisierten Service-Version getestet haben, können Sie die Version aktualisieren, die die Anwendung anfordert.

Eine bestimmte Version anfordern

Die Berichterstattungswebdienst bietet zwei Möglichkeiten, eine bestimmten Dienstversion anfordern. Anwendungen können den X-RWS-Version -Header in der HTTP-Anforderung verwenden, oder sie erhalten rws-version -URI-Parameter.

X-RWS-Version HTTP-Anfrage-Header sieht wie folgt über die Leitung: X-RWS-Version:2013-V1.

Der URI-Parameter rws-version sieht in der Praxis: rws-version=2013-V1. Im folgenden Beispiel fordert dieser Service Version 2013-V1 verwendet werden, um den Bericht StaleMailbox nicht verarbeiten.

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

Wichtig

Bieten Sie nicht-HTTP-Header und der URI-Parameter in der gleichen Berichtsanforderung. Stößt der Berichterstattungswebdienst , auch wenn sie für die gleiche Version des Service sind, wird den folgenden Fehler zurückgegeben.

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

Wenn Sie entscheiden, wie Sie die Service-Version angeben, sollten Sie Ihre Code-Architektur. Wenn Ihre Anwendung nur eine Version zugreifen muss, verwenden Sie den HTTP-Anfrage-Header. Wenn Ihre Anwendung verschiedene Service-Versionen für verschiedene Berichte verwendet und ganz allgemein für alle Berichte unabhängig davon Dienstversion HttpRequest erstellen erfolgt, verwenden Sie den URI-Parameter. Welche Methode Sie sich entscheiden, verwenden Sie nicht beide.

X-RWS-Version-Header durch den Webdienst zurückgegeben wird.

Alle erfolgreichen HTTP-Antworten und am häufigsten fehlgeschlagenen Antworten, die an die Clientanwendung zurückgegeben werden enthalten den X-RWS-Version -Header. Diesen Header wird die Service-Level-Version angeben, die auf die Ergebnisse angewendet wird. Wenn die Anwendung eine bestimmte Version angibt, gibt die Berichterstattungswebdienst die aktuellste Version des Service. Wenn die Anwendung eine Version angegeben wird, wenn diese Version verfügbar ist, gibt der Bericht die angeforderten Dienst-Version um sicherzustellen, dass die Anwendung eine Anforderung der gewünschten Ausführung verarbeitet werden kann.

ODATA Data Service-Versionen

Die Grundlage für die Office 365-Berichterstattungswebdienst ist ODATA-Infrastruktur hat auch Versionen, die von Zeit zu Zeit aktualisiert werden und werden wahrscheinlich in die Berichterstattungswebdienst zu einem bestimmten Zeitpunkt angezeigt. Es gibt zwei Header: der DataServiceVersion , der die bevorzugte ODATA-Version angibt und die MaxDataServiceVersion , die der Dienst nicht mehr als eine Version angibt. Diese Header helfen auch sicherstellen kontinuierlichen Zuverlässigkeit für Systeme mit Vorgängerversion Service getestet. Weitere Informationen finden Sie unter Versionskontrolle von Protokollen ODATA.

DataServiceVersion-HTTP-header

Der DataServiceVersion -Header weist die Anforderungshandler ODATA und Formatierungen, um die angezeigte DataServiceVersion zu verwenden. Ab Februar 2012 ist die entsprechende Service-Version 2.0. Ein Header DataServiceVersion wird mit der Antwort Bericht zurückgegeben, sodass die Anwendung, ob die Version kompatibel ist.

MaxDataServiceVersion-HTTP-Header

Die MaxDataServiceVersion weist die Berichterstattungswebdienst nicht auf eine Version höher als die angegebene verwenden. Wenn die aktuelle Version 2.0 ist und Sie nicht die nächste größere Version (3.0) zu verwendenden zulassen möchten, geben Sie einen Header mit MaxDataServiveVersion:2.99.

Office 365 Reporting Web Service bevorzugt ODATA-Versionen

Um größere Kompatibilität mit ODATA-Clients zu gewährleisten, verwendet der Berichterstattungswebdienst zwei unterschiedliche DataServiceVersion-Werte, je nachdem, was angefordert werden:

Reporting.svc Service-Beschreibungsdokument verwendet ODATA- DataServiceVersion 1.0.
Alle anderen Berichte verwenden ODATA- DataServiceVersion 2.0.

Beispiel

Im folgende Beispiel wird veranschaulicht, wie Sie die in diesem Thema, um eine HttpWebRequestbeschriebenen Header hinzufügen. Die Header können in beliebiger Reihenfolge hinzugefügt werden, aber Sie sollten nicht mehr als ein Exemplar der einzelnen Header einschließen. Accept-Language HTTP header and the Reporting web service Informationen zum Festlegen der Kultur und Sprache für die Namen der Spaltenüberschriften angezeigt.

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