Instrumentar solicitudes de cliente para EWS y REST en ExchangeInstrumenting client requests for EWS and REST in Exchange

Obtenga información sobre los encabezados HTTP en las solicitudes y respuestas REST de EWS y que pueden ayudarle a supervisar y solucionar problemas de su aplicación Exchange.Learn about the HTTP headers in EWS and REST requests and responses that can help you monitor and troubleshoot your Exchange application.

¿Le ha sucedido alguna vez?Has this ever happened to you? Un usuario de la aplicación informa de un error inesperado.A user of your application reports an unexpected error. Desea investigar, pero no puede reproducirlo.You want to investigate, but you can't reproduce it. El error ha desaparecido para el usuario y quedará con muy pocos datos que requieren acción.The error has disappeared for the user, and you're left with very little actionable data. Frustrante, ¿no?Frustrating, isn't it? Veamos cómo puede prepararse de forma proactiva para este escenario y, afortunadamente, evitar la frustración en el futuro.Let's look at how you can proactively prepare for this scenario and hopefully avoid frustration in the future.

Agregar instrumentación a las solicitudesAdd instrumentation to requests

Le recomendamos que agregue encabezados HTTP adicionales a sus solicitudes para facilitar la solución de problemas.We recommend that you add additional HTTP headers to your requests to facilitate troubleshooting. Debe mantener un registro de esta información en algún lugar (por ejemplo, en un archivo de registro) para poder recuperarla más adelante si es necesario.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. Esto es útil al examinar el tráfico de red y también es útil si se pone en contacto con el soporte técnico de Microsoft para obtener ayuda.This is helpful when examining network traffic, and is also helpful if you contact Microsoft support for assistance.

Tabla 1. Encabezados de solicitud para la solución de problemasTable 1. Request headers for troubleshooting

Encabezado HTTP (EWS)HTTP header (EWS) Equivalente de API administrada de EWSEWS Managed API equivalent NotasNotes
Agente de usuarioUser-Agent
ExchangeService. UserAgentExchangeService.UserAgent
Establézcalo en un valor único que identifique la aplicación cliente.Set this to a unique value that identifies your client application.

Usar el mismo valor para todas las solicitudes que envía la aplicación permite que Microsoft Ayude a solucionar los errores de llamada, en caso de que se produzcan.Using the same value for all requests that your application sends allows Microsoft to help troubleshoot call failures, should they arise.
identificador de solicitud de clienteclient-request-id
ExchangeService. ClientRequestIdExchangeService.ClientRequestId
Establézcalo en un valor único diferente para cada solicitud que envíe la aplicación.Set this to a different unique value for every request your application sends.

Le recomendamos que use un GUID.We recommend that you use a GUID. Este identificador único está pensado para usarse para correlacionar actividades entre dos sistemas en el caso de que algo vaya mal.This unique identifier is intended to be used to correlate activities between two systems in the event that something goes wrong.
Return-Client-request-IDreturn-client-request-id
ExchangeService. ReturnClientRequestIdExchangeService.ReturnClientRequestId
Establézcalo en true para indicar al servidor de Exchange que debe devolver el valor del identificador de solicitud de cliente en la respuesta correspondiente.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.

Puede usar esto para correlacionar las solicitudes y respuestas en los seguimientos de red o los seguimientos de API administrada de EWS.You can use this to correlate requests and responses in network traces or EWS Managed API traces.
X-ClientStatisticsX-ClientStatistics
ExchangeService. SendClientLatenciesExchangeService.SendClientLatencies
Se usa para informar de latencias de EWS a Microsoft si su aplicación tiene acceso a Exchange online o Exchange online como parte de Office 365.Used to report EWS latencies to Microsoft if your application is accessing Exchange Online or Exchange Online as part of Office 365.

Registrar información de respuestasLog information from responses

Al igual que el cliente puede Agregar instrumental adicional a las solicitudes que envía, Exchange agrega instrumental adicional a las respuestas en forma de encabezados 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. El cliente debe capturar esta información para ir junto con la información de instrumentación de la solicitud.Your client should capture this information to go along with the request instrumentation information.

Nota

Si usa la API administrada de EWS, no hay equivalente directo para los encabezados HTTP.If you are using the EWS Managed API, there is no direct equivalent for the HTTP headers. Sin embargo, se puede tener acceso a todos los encabezados de respuesta HTTP a través de la propiedad ExchangeService. HttpResponseHeaders .However, all HTTP response headers can be accessed via the ExchangeService.HttpResponseHeaders property.

Tabla 2. Encabezados de respuesta HTTPTable 2. HTTP response headers

Encabezado HTTPHTTP header DescripciónDescription
identificador de solicitudrequest-id
IDENTIFICADOR generado por el servidor para la solicitud que corresponde a esta respuesta.A server-generated ID for the request that corresponds to this response.
identificador de solicitud de clienteclient-request-id
El valor del encabezado de identificador de solicitud de cliente en la solicitud.The value of the client-request-id header in the request.

Este encabezado solo está presente si la solicitud contiene el encabezado Return-Client-request-ID con un 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
El FQDN del servidor de acceso de cliente que procesó la solicitud.The FQDN of the Client Access server that processed the request.
X-TargetBEServerX-TargetBEServer
El FQDN del servidor de buzones de correo que ha procesado la solicitud.The FQDN of the mailbox server that processed the request.
X-DiagInfoX-DiagInfo
Información de diagnóstico adicional, según la solicitud.Additional diagnostic information, depending on the request.
x-MS-Diagnosticsx-ms-diagnostics
Este encabezado solo se aplica si se usa la autenticación OAuth en la solicitud.This header is only applicable if OAuth authentication is used in the request.

Contiene un código de error explícito que especifica por qué se produjo un error en la autenticación OAuth.It contains an explicit error code that specifies why an OAuth authentication failed.

Tiene el siguiente formato:errorId;reason="reason"error_type="error type"It takes the following format: errorId;reason="reason"error_type="error type"

El campo motivo es una descripción legible del error por el usuario.The reason field is a human-readable description of the error.

El campo errorId es un número entero y el campo ** _ tipo de error** es la representación en forma de cadena de ese entero, de la siguiente manera:The errorId field is an integer, and the error_type field is the string representation of that integer, as follows:
  • 2 millones: firma no válida _2000000: invalid_signature
  • 2000001: token no válido _2000001: invalid_token
  • 2000002: token _ expirado2000002: token_expired
  • 2000003: recurso no válido _2000003: invalid_resource
  • 2000004: inquilino no válido _2000004: invalid_tenant
  • 2000005: usuario no válido _2000005: invalid_user
  • 2000006: cliente no válido _2000006: invalid_client
  • 2000007: _ error interno2000007: internal_error
  • 2000008: concesión no válida _2000008: invalid_grant

Informar de latencia de EWS a MicrosoftReport EWS latency to Microsoft

Si la aplicación usa la API administrada de EWS o EWS para conectarse a Exchange Online, puede notificar la latencia en las solicitudes de EWS directamente a 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. La información se pasa a través del encabezado de solicitud X-ClientStatistics.The information is passed via the X-ClientStatistics request header. Si usa la API administrada de EWS, todo lo que tiene que hacer es establecer la propiedad ExchangeService. SendClientLatencies en true.If you are using the EWS Managed API, all you have to do is set the ExchangeService.SendClientLatencies property to true. Si usa EWS, deberá medir el tiempo entre emitir una solicitud y recibir una respuesta y, a continuación, agregar el encabezado X-ClientStatistics a la siguiente solicitud de EWS que envíe la aplicación, con el siguiente formato.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>

Mantenemos informes para estas latencias y los usamos para mejorar de forma continua los servicios EWS en Exchange Online.We maintain reports for these latencies and use them to continuously improve EWS services in Exchange Online.

Siguientes pasosNext steps

Una vez que haya agregado la instrumentación del cliente a la aplicación, es mejor preparado si algo va mal.After you've added client instrumentation to your application, you're better prepared if something goes wrong. Si esto ocurre, puede usar los datos de instrumentación para solucionar los problemas de la aplicación.If that happens, you can use your instrumentation data to troubleshoot your application.

Vea tambiénSee also