Instrumentação de solicitações de cliente para EWS e REST no ExchangeInstrumenting client requests for EWS and REST in Exchange

  • 3 minutos para o fim da leitura

Saiba mais sobre os cabeçalhos HTTP no EWS e as solicitações REST e respostas que podem ajudá-lo a monitorar e solucionar problemas do aplicativo Exchange.Learn about the HTTP headers in EWS and REST requests and responses that can help you monitor and troubleshoot your Exchange application.

Isso já aconteceu?Has this ever happened to you? Um usuário do seu aplicativo relata um erro inesperado.A user of your application reports an unexpected error. Você deseja investigar, mas não pode reproduzi-lo.You want to investigate, but you can't reproduce it. O erro desapareceu para o usuário e você é deixado com poucos dados acionáveis.The error has disappeared for the user, and you're left with very little actionable data. Frustrante, não é?Frustrating, isn't it? Vamos ver como você pode se preparar proativamente para este cenário e, espero, evitar frustração no futuro.Let's look at how you can proactively prepare for this scenario and hopefully avoid frustration in the future.

Adicionar instrumentação às solicitaçõesAdd instrumentation to requests

Recomendamos que você adicione outros cabeçalhos HTTP às suas solicitações para facilitar a solução de problemas.We recommend that you add additional HTTP headers to your requests to facilitate troubleshooting. Você deve manter um registro dessas informações em algum lugar (por exemplo, em um arquivo de log) para que possa recuperá-lo posteriormente, se necessário.You should keep a record of this information somewhere (for example, in a log file) so that you can retrieve it later if you need to. Isso é útil ao examinar o tráfego de rede e também é útil se você entrar em contato com o suporte da Microsoft para obter assistência.This is helpful when examining network traffic, and is also helpful if you contact Microsoft support for assistance.

Tabela 1. Cabeçalhos de solicitação para solução de problemasTable 1. Request headers for troubleshooting

Cabeçalho HTTP (EWS)HTTP header (EWS) Equivalente à API gerenciada do EWSEWS Managed API equivalent AnotaçõesNotes
Agente de usuárioUser-Agent
ExchangeService. UserAgentExchangeService.UserAgent
Defina isso como um valor exclusivo que identifique o aplicativo cliente.Set this to a unique value that identifies your client application.

Usar o mesmo valor para todas as solicitações que o seu aplicativo envia permite que a Microsoft ajude a solucionar problemas de falhas de chamada, caso ocorram.Using the same value for all requests that your application sends allows Microsoft to help troubleshoot call failures, should they arise.
Client-Request-IDclient-request-id
ExchangeService. ClientRequestIdExchangeService.ClientRequestId
Defina isso como um valor exclusivo diferente para cada solicitação que seu aplicativo envia.Set this to a different unique value for every request your application sends.

Recomendamos que você use um GUID.We recommend that you use a GUID. Esse identificador exclusivo deve ser usado para correlacionar atividades entre dois sistemas no caso de algo errado.This unique identifier is intended to be used to correlate activities between two systems in the event that something goes wrong.
retorno-Client-Request-IDreturn-client-request-id
ExchangeService. ReturnClientRequestIdExchangeService.ReturnClientRequestId
Defina como true para sinalizar para o servidor Exchange que deve retornar o valor de seu Client-Request-ID na resposta correspondente.Set this to true to signal to the Exchange server that it should return the value of your client-request-id in the corresponding response.

Você pode usar isso para correlacionar solicitações e respostas em rastreamentos de rede ou rastreamentos de API gerenciada do EWS.You can use this to correlate requests and responses in network traces or EWS Managed API traces.
X-ClientStatisticsX-ClientStatistics
ExchangeService. SendClientLatenciesExchangeService.SendClientLatencies
Usado para relatar latências de EWS para a Microsoft se seu aplicativo estiver acessando o Exchange Online ou o Exchange Online como parte do Office 365.Used to report EWS latencies to Microsoft if your application is accessing Exchange Online or Exchange Online as part of Office 365.

Informações de log de respostasLog information from responses

Assim que o cliente pode adicionar a instrumentação adicional às solicitações que envia, o Exchange adiciona instrumentação adicional às respostas na forma de cabeçalhos HTTP.Just as your client can add additional instrumentation to the requests it sends, Exchange adds additional instrumentation to the responses in the form of HTTP headers. O cliente deve capturar essas informações para acompanhar as informações de instrumentação de solicitação.Your client should capture this information to go along with the request instrumentation information.

Observação

Se você estiver usando a API gerenciada do EWS, não haverá equivalente direto aos cabeçalhos HTTP.If you are using the EWS Managed API, there is no direct equivalent for the HTTP headers. No entanto, todos os cabeçalhos de resposta HTTP podem ser acessados por meio da propriedade ExchangeService. HttpResponseHeaders .However, all HTTP response headers can be accessed via the ExchangeService.HttpResponseHeaders property.

Tabela 2. Cabeçalhos de resposta HTTPTable 2. HTTP response headers

Cabeçalho HTTPHTTP header DescriçãoDescription
ID da solicitaçãorequest-id
Uma ID gerada pelo servidor para a solicitação que corresponde a essa resposta.A server-generated ID for the request that corresponds to this response.
Client-Request-IDclient-request-id
O valor do cabeçalho Client-Request-ID na solicitação.The value of the client-request-id header in the request.

Este cabeçalho só estará presente se a solicitação contiver o cabeçalho Return-Client-Request-ID com um valor true.This header is only present if the request contains the return-client-request-id header with a value of true.
X-FEServerX-FEServer
O FQDN do servidor de acesso para cliente que processou a solicitação.The FQDN of the Client Access server that processed the request.
X-TargetBEServerX-TargetBEServer
O FQDN do servidor de caixa de correio que processou a solicitação.The FQDN of the mailbox server that processed the request.
X-DiagInfoX-DiagInfo
Informações adicionais de diagnóstico, dependendo da solicitação.Additional diagnostic information, depending on the request.
x-MS-Diagnosticsx-ms-diagnostics
Esse cabeçalho só será aplicável se a autenticação OAuth for usada na solicitação.This header is only applicable if OAuth authentication is used in the request.

Ele contém um código de erro explícito que especifica por que uma autenticação OAuth falhou.It contains an explicit error code that specifies why an OAuth authentication failed.

Ele tem o seguinte formato:errorId;reason="reason"error_type="error type"It takes the following format: errorId;reason="reason"error_type="error type"

O campo de motivo é uma descrição legível do erro.The reason field is a human-readable description of the error.

O campo errorID é um inteiro e o campo ** _ tipo de erro** é a representação de cadeia de caracteres desse inteiro, da seguinte maneira:The errorId field is an integer, and the error_type field is the string representation of that integer, as follows:
  • 2 milhões: assinatura inválida _2000000: invalid_signature
  • 2000001: _ token inválido2000001: invalid_token
  • 2000002: token _ expirado2000002: token_expired
  • 2000003: _ recurso inválido2000003: invalid_resource
  • 2000004: _ locatário inválido2000004: invalid_tenant
  • 2000005: _ usuário inválido2000005: invalid_user
  • 2000006: _ cliente inválido2000006: invalid_client
  • 2000007: _ erro interno2000007: internal_error
  • 2000008: concessão inválida _2000008: invalid_grant

Relatar a latência do EWS para a MicrosoftReport EWS latency to Microsoft

Se o aplicativo usar a API gerenciada do EWS ou o EWS para se conectar ao Exchange Online, você poderá relatar a latência em solicitações EWS diretamente à Microsoft.If your application uses the EWS Managed API or EWS to connect to Exchange Online, you can report latency in EWS requests directly to Microsoft. As informações são passadas pelo cabeçalho de solicitação X-ClientStatistics.The information is passed via the X-ClientStatistics request header. Se você estiver usando a API gerenciada do EWS, tudo o que você precisa fazer é definir a propriedade ExchangeService. SendClientLatencies como true.If you are using the EWS Managed API, all you have to do is set the ExchangeService.SendClientLatencies property to 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 e, em seguida, adicione o cabeçalho X-ClientStatistics à próxima solicitação do EWS que seu aplicativo envia, usando o formato a seguir.If you are using EWS, you'll need to measure the time between issuing a request and receiving a response, then add the X-ClientStatistics header to the next EWS request your application sends, using the following format.

X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>

Mantemos relatórios para essas latências e os usam para melhorar continuamente os serviços do EWS no Exchange Online.We maintain reports for these latencies and use them to continuously improve EWS services in Exchange Online.

Próximas etapasNext steps

Após ter adicionado a instrumentação do cliente ao seu aplicativo, você estará mais preparado se algo der errado.After you've added client instrumentation to your application, you're better prepared if something goes wrong. Se isso acontecer, você poderá usar seus dados de instrumentação para solucionar problemas com o aplicativo.If that happens, you can use your instrumentation data to troubleshoot your application.

Confira tambémSee also