Controle de versão no serviço da web de relatório do Office 365

Artigo
11/14/2016

Para garantir a compatibilidade futura com os clientes existentes do Office 365 Reporting web service , o serviço da web aceita um cabeçalho HTTP de X-RWS-Version ou um parâmetro URI rws-version . O serviço ODATA também tem cabeçalhos de compatibilidade de versão que o aplicativo deve usar. Neste momento (fevereiro de 2013) a versão de serviço só é válida para este recurso é 2013-V1. Este tópico descreve como trabalhar com os serviços e as versões de serviço de dados ODATA.

Última alteração: segunda-feira, 7 de dezembro de 2015

Aplica-se a: Office 365

Versões do Office 365 relatórios web service

Serviços on-line, como o Office 365 recebem atualizações freqüentes que adicionam funcionalidade e corrigem problemas. Office 365 usa identificadores de versão de serviço do formulário YEAR-V#. YEAR é o ano do calendário em que o lançamento fique disponível para a maioria dos assinantes. A # indica o número da versão do ano. A partir de março de 2013, a versão em funcionamento predominante é 2013-V1. A versão anterior foi 2012-V1; No entanto, o Office 365 Reporting web service não estava disponível nessa versão do serviço. Solicitações para usar a versão de 2012-V1 retornará um erro que contém <Message>The version specified in the request is unsupported.</Message>.

Para ajudar a garantir a compatibilidade com versões futuras do serviço com o cliente, aplicativos devem especificar que as solicitações e as respostas do, a Reporting web service ser tratado de acordo com uma versão de serviço específico. Se o aplicativo não solicitar uma versão de serviço específico, presume-se a versão mais recente do serviço. Seu aplicativo deve sempre solicitar a versão de serviço que foi projetado para trabalhar com para que ele continue funcionando corretamente, o serviço é atualizado. Depois que você testou seu aplicativo contra uma versão atualizada do serviço, você pode atualizar a versão do aplicativo solicita.

Solicitar uma versão de serviço específico

O Reporting web service fornece duas maneiras para solicitar uma versão de serviço específico. Os aplicativos podem usar o cabeçalho X-RWS-Version na solicitação HTTP, ou ele pode fornecer o parâmetro URI de rws-version .

O cabeçalho de solicitação de X-RWS-Version HTTP se parece com isso durante a transmissão: X-RWS-Version:2013-V1.

O parâmetro URI rws-version se parece com isso na prática: rws-version=2013-V1. O exemplo a seguir solicita que versão de serviço 2013-V1 ser usado para processar o relatório de 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

Não fornecem o cabeçalho HTTP e o parâmetro URI na mesma solicitação de relatório. Quando o Reporting web service encontrar ambos, mesmo que eles são para a mesma versão de serviço, ela retornará o erro a seguir.

<?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 como indicar a versão do serviço, considere a arquitetura de seu código. Se seu aplicativo só precisa acessar uma versão, use o cabeçalho de solicitação HTTP. Se o aplicativo usa as versões de serviço diferentes para diferentes relatórios e criar o HttpRequest é feito genericamente para todos os relatórios, independentemente da versão do serviço, use o parâmetro URI. Qualquer método que você escolher, não use ambos.

Cabeçalho X-RWS-versão retornado pelo serviço da web

Todas as respostas HTTP bem-sucedida e mais respostas sem êxito, que são retornadas para o aplicativo cliente incluam o cabeçalho de X-RWS-Version . Esse cabeçalho, especifique o nível de versão de serviço aplica-se aos resultados. Quando o aplicativo não especifica qualquer versão específica, o Reporting web service retorna a versão mais atual do serviço. Quando o aplicativo especifica uma versão, se essa versão estiver disponível, o relatório retorna a versão de serviço solicitado para confirmar que a solicitação do aplicativo pode ser atendida na versão solicitada.

Versões de serviço de dados ODATA

A infra-estrutura ODATA no qual se baseia o Office 365 Reporting web service também tem versões que são atualizadas periodicamente e provavelmente aparecerão no Reporting web service em algum momento. Existem dois cabeçalhos: DataServiceVersion que especifica a versão preferencial do ODATA e MaxDataServiceVersion que especifica uma versão que o serviço não deve exceder. Esses cabeçalhos também ajudam a garantir a confiabilidade contínua para sistemas testados em relação a versão anterior do serviço. Para obter mais informações, consulte controle de versão de protocolo ODATA.

Cabeçalho HTTP DataServiceVersion

O cabeçalho DataServiceVersion instrui o manipulador de solicitações do ODATA e dados de formatação para usar o DataServiceVersion indicado. A partir de fevereiro de 2012, a versão de serviço apropriado é 2.0. Um cabeçalho de DataServiceVersion será retornado com a resposta do relatório, para que o aplicativo possa confirmar se a versão em uso é compatível.

Cabeçalho HTTP de MaxDataServiceVersion

O MaxDataServiceVersion instrui o Reporting web service para não usar qualquer versão maior do que aquele fornecido. Por exemplo, se a versão atual é 2.0, e você não deseja permitir a próxima versão principal (3.0) a ser usado, especifica um cabeçalho com MaxDataServiveVersion:2.99.

Versões do Office 365 relatórios web serviço preferido ODATA

Para garantir maior compatibilidade com clientes do ODATA, o Reporting web service utiliza dois diferentes valores de DataServiceVersion dependendo do que está sendo solicitada:

documento de descrição de serviço Reporting.svc usa ODATA DataServiceVersion 1.0.
Todos os outros relatórios usam ODATA DataServiceVersion 2.0.

Exemplo

O exemplo a seguir demonstra como adicionar os cabeçalhos descritos neste tópico para um HttpWebRequest. Os cabeçalhos podem ser adicionados em qualquer ordem, mas você não deve incluir mais de uma cópia de cada cabeçalho. Consulte Accept-Language HTTP header and the Reporting web service para obter informações sobre como especificar a cultura e o idioma para o nome do título.

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

Compartilhar via