Instrumentando solicitações de cliente para EWS e REST Exchange
Saiba mais sobre os cabeçalhos HTTP em solicitações e respostas REST e EWS que podem ajudá-lo a monitorar e solucionar problemas de seu Exchange aplicativo.
Isso já aconteceu com você? Um usuário do aplicativo relata um erro inesperado. Você deseja investigar, mas não pode reproduzi-lo. O erro desapareceu para o usuário e você é deixado com muito pouco dados a ação. Frustrante, não é? Vamos ver como você pode se preparar proativamente para esse cenário e, com sorte, evitar frustração no futuro.
Adicionar instrumentação a solicitações
Recomendamos adicionar cabeçalhos HTTP adicionais às suas solicitações para facilitar a solução de problemas. Você deve manter um registro dessas informações em algum lugar (por exemplo, em um arquivo de log) para que possa recuperá-las mais tarde, se precisar. Isso é útil ao examinar o tráfego de rede e também é útil se você contatar o suporte da Microsoft para assistência.
Tabela 1. Solicitar headers para solução de problemas
| Cabeçalho HTTP (EWS) | Equivalente à API Gerenciada do EWS | Observações |
|---|---|---|
| User-Agent |
ExchangeService.UserAgent |
De definir isso como um valor exclusivo que identifique seu aplicativo cliente. Usar o mesmo valor para todas as solicitações que seu aplicativo envia permite que a Microsoft ajude a solucionar falhas de chamada, caso elas surjam. |
| client-request-id |
ExchangeService.ClientRequestId |
De definir isso como um valor exclusivo diferente para cada solicitação que seu aplicativo envia. Recomendamos que você use um GUID. Esse identificador exclusivo destina-se a ser usado para correlacionar atividades entre dois sistemas no caso de algo dar errado. |
| return-client-request-id |
ExchangeService.ReturnClientRequestId |
Dejuste isso como true para sinalizar para o servidor Exchange que ele deve retornar o valor do seu cliente-request-id na resposta correspondente. Você pode usar isso para correlacionar solicitações e respostas em rastreamentos de rede ou rastreamentos de API gerenciada do EWS. |
| X-ClientStatistics |
ExchangeService.SendClientLatencies |
Usado para relatar latências do EWS à Microsoft se seu aplicativo estiver acessando Exchange Online ou Exchange Online como parte do Office 365. |
Informações de log de respostas
Assim como seu cliente pode adicionar instrumentação adicional às solicitações que envia, Exchange adiciona instrumentação adicional às respostas na forma de cabeçalhos HTTP. Seu cliente deve capturar essas informações para acompanhar as informações de instrumentação de solicitação.
Observação
Se você estiver usando a API Gerenciada do EWS, não há equivalente direto para os cabeçalhos HTTP. No entanto, todos os cabeçalhos de resposta HTTP podem ser acessados por meio da propriedade ExchangeService.HttpResponseHeaders.
Tabela 2. Cabeçalhos de resposta HTTP
| Cabeçalho HTTP | Descrição |
|---|---|
| request-id |
Uma ID gerada pelo servidor para a solicitação que corresponde a essa resposta. |
| client-request-id |
O valor do header client-request-id na solicitação. Esse header só estará presente se a solicitação contiver o header return-client-request-id com um valor true. |
| X-FEServer |
O FQDN do servidor de Acesso para Cliente que processou a solicitação. |
| X-TargetBEServer |
O FQDN do servidor de caixa de correio que processou a solicitação. |
| X-DiagInfo |
Informações de diagnóstico adicionais, dependendo da solicitação. |
| x-ms-diagnostics |
Esse header só será aplicável se a autenticação OAuth for usada na solicitação. Ele contém um código de erro explícito que especifica por que uma autenticação OAuth falhou. Ele tem o seguinte formato: errorId;reason="reason"error_type="error type"O campo motivo é uma descrição aceitável para humanos do erro. O campo errorId é um inteiro e o campo de tipo _ de erro é a representação de cadeia de caracteres desse inteiro, da seguinte forma:
|
Relatar latência do EWS para a Microsoft
Se seu aplicativo usa a API Gerenciada do EWS ou o EWS para se conectar ao Exchange Online, você pode relatar latência em solicitações do EWS diretamente para a Microsoft. As informações são passadas por meio do header de solicitação X-ClientStatistics. Se você estiver usando a API Gerenciada do EWS, tudo o que você precisa fazer é definir a propriedade ExchangeService.SendClientLatencies como true. Se você estiver usando o EWS, precisará medir o tempo entre a emissão de uma solicitação e o recebimento de uma resposta, em seguida, adicione o header X-ClientStatistics à próxima solicitação do EWS que seu aplicativo enviar, usando o seguinte formato.
X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>
Mantemos relatórios para essas latências e os usamos para melhorar continuamente os serviços EWS Exchange Online.
Próximas etapas
Depois de adicionar instrumentação de cliente ao aplicativo, você está mais preparado se algo der errado. Se isso acontecer, você poderá usar seus dados de instrumentação para solucionar problemas com seu aplicativo.