Control de versiones en el servicio web de informes de Office 365
Para garantizar la compatibilidad futura con los clientes existentes de Servicio Web de informes de Office 365 , el servicio web acepta un encabezado HTTP de X-RWS-Version o un parámetro URI rws-version . El servicio ODATA también tiene encabezados de compatibilidad de la versión que debe utilizar la aplicación. En este momento (febrero de 2013) la versión de servicio sólo es válido para esta función es 2013-V1. Este tema describe cómo trabajar con las versiones de servicio de datos ODATA y servicio.
Última modificación: lunes, 07 de diciembre de 2015
Hace referencia a: Office 365
Versiones de Office 365 informes web service
Servicios en línea como Office 365 reciban actualizaciones frecuentes que agregan funcionalidad y solución de problemas. Office 365 utiliza identificadores de versión de servicio en el formulario YEAR-V#. YEAR es el año de calendario en el que la versión disponible generalmente a la mayoría de los suscriptores. La # indica el número de versión del año. A partir de marzo de 2013, la versión estándar de vehículos en circulación es 2013-V1. La versión anterior era 2012-V1; Sin embargo, la Servicio Web de informes de Office 365 no era generalmente disponibles en esa versión de servicio. Las solicitudes para utilizar la versión de 2012-V1 devolverá un error que contiene <Message>The version specified in the request is unsupported.</Message>.
Para garantizar la compatibilidad con versiones futuras del servicio del cliente, las aplicaciones deben especificar que las solicitudes y las respuestas de la Servicio Web de informes controlarse según una versión de servicio específico. Si la aplicación solicita una versión específica del servicio, se supone que la versión más reciente del servicio. La aplicación siempre debería solicitar la versión de servicio que se diseñó para trabajar con lo que puede continuar funcionando correctamente mientras se actualiza el servicio. Una vez que ha probado la aplicación con una versión actualizada del servicio, puede actualizar la versión que solicita la aplicación.
Solicitar una versión de servicio específico
El Servicio Web de informes proporciona dos formas de solicitar una versión de servicio específico. Las aplicaciones pueden utilizar el encabezado de X-RWS-Version en la solicitud HTTP, o puede proporcionar el parámetro URI rws-version .
El encabezado de solicitud X-RWS-Version HTTP este aspecto sobre el alambre: X-RWS-Version:2013-V1.
El parámetro URI rws-version este aspecto en la práctica: rws-version=2013-V1. En el ejemplo siguiente se solicita esa versión de servicio 2013-V1 se utiliza para procesar el informe StaleMailbox.
https://reports.office365.com/ecp/reportingwebservice/reporting.svc/StaleMailbox?rws-version=2013-V1&
$select=ActiveMailboxes,Date,InactiveMailboxes31To60Days,InactiveMailboxes61To90Days,InactiveMailboxes91To1460Days&
$top=1&
$format=Atom
Importante
No proporcionan el encabezado HTTP y el parámetro URI en la misma solicitud de informe. Cuando el Servicio Web de informes encuentra ambos, incluso si son de la misma versión de servicio, devolverá el error siguiente.
<?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>
Para decidir la forma de indicar la versión del servicio, tenga en cuenta la arquitectura del código. Si la aplicación sólo necesita tener acceso a una versión, utilice el encabezado de solicitud HTTP. Si la aplicación utiliza distintas versiones de service para diferentes informes y creación HttpRequest se realiza de forma genérica para todos los informes independientemente de la versión de servicio, utilice el parámetro URI. Independientemente del método que elija, no use ambos.
Encabezado X-RWS-versión devuelto por el servicio web
Todas las respuestas HTTP correctas y más respuestas sin éxito que se devuelven a la aplicación cliente incluyen el encabezado X-RWS-Version . Esa cabecera especificará el nivel de versión del servicio que se aplica a los resultados. Cuando la aplicación no especifica cualquier versión, el Servicio Web de informes devuelve la versión más reciente del servicio. Cuando la aplicación especifica una versión, si esa versión está disponible, el informe devuelve la versión de servicio solicitado para confirmar que puede ser atendida la solicitud de la aplicación en la versión solicitada.
Versiones de servicio de datos ODATA
La infraestructura ODATA en la que se basa el Servicio Web de informes de Office 365 también tiene las versiones que se actualizan periódicamente y es probable que se mostrarán en el Servicio Web de informes en algún momento. Hay dos encabezados: el DataServiceVersion que especifica la versión ODATA preferida y el MaxDataServiceVersion que especifica una versión que no deberá exceder el servicio. Estos encabezados también ayudan a garantizar la confiabilidad constante para los sistemas que se prueban con la versión anterior del servicio. Para obtener más información, vea control de versiones del protocolo ODATA.
Encabezado HTTP DataServiceVersion
El encabezado DataServiceVersion indica que el controlador de solicitudes ODATA y datos de formato para utilizar el DataServiceVersion indicado. A partir de febrero de 2012, la versión de servicio adecuado es 2.0. Un encabezado de DataServiceVersion se devuelve con la respuesta de informe, para que la aplicación puede confirmar que la versión en uso es compatible.
Encabezado de HTTP MaxDataServiceVersion
La MaxDataServiceVersion indica la Servicio Web de informes no se debe utilizar cualquier versión posterior a suministrado. Por ejemplo, si la versión actual es 2.0 y no desea permitir la siguiente versión principal (3.0) que se utilizará, especificar un encabezado con el MaxDataServiveVersion:2.99.
Versiones de Office 365 informes web servicio preferido ODATA
Para garantizar una mayor compatibilidad con clientes ODATA, el Servicio Web de informes utiliza dos valores de DataServiceVersion diferentes dependiendo de lo que se solicita:
Reporting.svc documento de descripción de servicio utiliza ODATA DataServiceVersion 1.0.
Todos los demás informes utilizan ODATA DataServiceVersion 2.0.
Ejemplos
En el siguiente ejemplo se muestra cómo agregar los encabezados que se describe en este tema para un HttpWebRequest. Los encabezados se pueden agregar en cualquier orden, pero no debe incluir más de una copia de cada encabezado. Consulte Accept-Language HTTP header and the Reporting web service para obtener información acerca de cómo especificar la referencia cultural y el idioma para los nombres de los encabezados.
//
// 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();