Contrôle de version dans le service web de création de rapports Office 365

Article
11/14/2016

Pour garantir une compatibilité future avec les clients existants de Service web de création de rapports Office 365 , le service web accepte un en-tête HTTP de X-RWS-Version ou d'un paramètre d'URI rws-version . Le service ODATA comporte également des en-têtes de compatibilité de version que votre application doit utiliser. À ce stade (février 2013) la version du service n'est valide que pour cette fonction est 2013-V1. Cette rubrique décrit l'utilisation des services et des versions de service de données ODATA.

Dernière modification : lundi 7 décembre 2015

S’applique à : Office 365

Versions du service web Reporting Office 365

Services en ligne tels que les Office 365 reçoivent des mises à jour fréquentes qui ajoutent des fonctionnalités et résolvent les problèmes. Office 365 utilise les identificateurs de version de service dans le formulaire YEAR-V#. YEAR est l'année de calendrier dans lequel la version devient disponible dans la plupart des abonnés. La # indique le numéro de version de l'année. Depuis mars 2013, la version grand public de véhicules en service est 2013-V1. La version précédente a été 2012-V1; Toutefois, le Service web de création de rapports Office 365 n'était pas disponible dans cette version de service. Demandes d'utilisation de la version 2012-V1 retournera une erreur contenant <Message>The version specified in the request is unsupported.</Message>.

Pour aider à garantir la compatibilité avec les versions futures de service client, les applications doivent spécifier que les demandes et les réponses à partir de la Service web de création de rapports être traité conformément à une version de service spécifique. Si l'application ne demande pas une version de service spécifiques, la version la plus récente du service est supposée. Votre application doit toujours en demander la version du service qu'il a été conçu pour fonctionner avec afin qu'il peut continuer à fonctionner correctement lorsque le service est mis à jour. Une fois que vous avez testé votre application avec une version mise à jour du service, vous pouvez mettre à jour la version de la demande.

Demande d'une version de service spécifique

Le Service web de création de rapports offre deux méthodes pour demander une version de service spécifique. Les applications peuvent utiliser l'en-tête de X-RWS-Version dans la demande HTTP, ou il peut fournir le paramètre d'URI rws-version .

L'en-tête de demande de X-RWS-Version HTTP ressemble à ceci sur le réseau : X-RWS-Version:2013-V1.

Le paramètre d'URI rws-version ressemble à ceci dans la pratique : rws-version=2013-V1. L'exemple suivant demande à cette version de service 2013-V1 utilisée pour traiter le rapport StaleMailbox.

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

Important

Ne fournissez pas l'en-tête HTTP et le paramètre URI dans la même demande de rapport. Lorsque la Service web de création de rapports rencontre les deux, même si elles sont de la même version de service, elle retournera l'erreur suivante.

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

Pour décider comment indiquer la version du service, envisagez de l'architecture de votre code. Si votre application doit uniquement pour accéder à une version, utilisez l'en-tête de demande HTTP. Si votre application utilise différentes versions de service pour les différents États et créer le HttpRequest est fait générique pour tous les États, quelle que soit la version du service, utilisez le paramètre URI. Quelle que soit la méthode choisie, n'utilisez pas les deux.

En-tête X-RW-Version retourné par le service web

Toutes les réponses HTTP réussies et plus réponses ayant échouées, qui sont retournés à l'application cliente incluent l'en-tête X-RWS-Version . Cet en-tête spécifie le niveau de version de service qui s'applique aux résultats. Lorsque l'application ne spécifie pas une version particulière, la Service web de création de rapports retourne la dernière version de service. Lorsque l'application spécifie une version, si cette version est disponible, le rapport renvoie la version du service demandé pour confirmer que la demande de l'application peut être entretenue dans la version demandée.

Versions de service de données ODATA

L'infrastructure ODATA sur laquelle s'appuie la Service web de création de rapports Office 365 a également des versions qui sont mis à jour à tout moment et seront affichera probablement dans la Service web de création de rapports à un moment donné. Il existe deux en-têtes : le DataServiceVersion qui spécifie la version ODATA préférée et les MaxDataServiceVersion qui spécifie une version dans laquelle le service ne doit pas dépasser. Ces en-têtes également aident à garantir la fiabilité continue des systèmes testés par rapport à la précédente version du service. Pour plus d'informations, consultez Gestion des versions du protocole ODATA.

En-tête HTTP DataServiceVersion

L'en-tête DataServiceVersion ordonne le Gestionnaire de requête ODATA et les données de mise en forme pour utiliser la DataServiceVersion indiquée. Depuis février 2012, la version du service approprié est 2.0. Un en-tête DataServiceVersion est retourné avec la réponse du rapport, afin que l'application peut confirmer que la version en cours d'utilisation est compatible.

En-tête HTTP de MaxDataServiceVersion

La MaxDataServiceVersion indique à l' Service web de création de rapports ne doit ne pas utiliser n'importe quelle version plus élevée que celui fourni. Par exemple, si la version actuelle est 2.0 et que vous ne souhaitez pas autoriser la version majeure suivante (3.0) à utiliser, vous pouvez spécifier un en-tête avec MaxDataServiveVersion:2.99.

Versions de Office 365 Reporting web service privilégié ODATA

Pour garantir une plus grande compatibilité avec les clients ODATA, le Service web de création de rapports utilise deux valeurs DataServiceVersion différentes en fonction de ce qui est demandé :

document de description du service Reporting.svc utilise ODATA DataServiceVersion 1.0.
Tous les autres utilisent ODATA DataServiceVersion 2.0.

Exemple

L'exemple suivant montre comment ajouter les en-têtes décrites dans cette rubrique pour une HttpWebRequest. Les en-têtes peuvent être ajoutés dans n'importe quel ordre, mais vous ne devez pas inclure plus d'une copie de chaque en-tête. Consultez Accept-Language HTTP header and the Reporting web service pour plus d'informations sur la spécification de la culture et langue pour les noms de titre.

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

Partager via