Handhaben von Clientanforderungen für EWS und REST in Exchange
Erfahren Sie mehr über die HTTP-Header in EWS- und REST-Anforderungen und -Antworten, die Ihnen bei der Überwachung und Problembehandlung ihrer Exchange-Anwendung helfen können.
Ist Ihnen dies jemals passiert? Ein Benutzer Ihrer Anwendung meldet einen unerwarteten Fehler. Sie möchten dies untersuchen, können sie jedoch nicht reproduzieren. Der Fehler ist für den Benutzer nicht mehr vorhanden, und Sie haben nur sehr wenige Aktionen erfordernde Daten. Frustrierend, oder? Sehen wir uns an, wie Sie sich proaktiv auf dieses Szenario vorbereiten und in Zukunft hoffentlich Frustration vermeiden können.
Hinzufügen von Instrumentierung zu Anforderungen
Es wird empfohlen, zusätzliche HTTP-Header zu Ihren Anforderungen hinzuzufügen, um die Problembehandlung zu vereinfachen. Sie sollten diese Informationen an einer bestimmten Stelle (z. B. in einer Protokolldatei) aufzeichnen, damit Sie sie später bei Bedarf abrufen können. Dies ist hilfreich, wenn Sie den Netzwerkdatenverkehr untersuchen, und ist auch hilfreich, wenn Sie sich an den Microsoft-Support wenden, um Unterstützung zu erhalten.
Tabelle 1. Anforderungsheader für die Problembehandlung
| HTTP-Header (EWS) | Entsprechung in der verwalteten EWS-API | Hinweise |
|---|---|---|
| User-Agent |
ExchangeService.UserAgent |
Legen Sie dies auf einen eindeutigen Wert fest, der Ihre Clientanwendung identifiziert. Wenn Sie denselben Wert für alle Anforderungen verwenden, die Ihre Anwendung sendet, kann Microsoft bei der Problembehandlung von Anruffehlern helfen, falls diese auftreten. |
| Clientanforderungs-ID |
ExchangeService.ClientRequestId |
Legen Sie für jede Anforderung, die Ihre Anwendung sendet, einen anderen eindeutigen Wert fest. Es wird empfohlen, eine GUID zu verwenden. Dieser eindeutige Bezeichner soll verwendet werden, um Aktivitäten zwischen zwei Systemen im Falle eines Fehlers zu korrelieren. |
| return-client-request-id |
ExchangeService.ReturnClientRequestId |
Legen Sie diesen Wert auf "true" fest, um dem Exchange Server zu signalisieren, dass er den Wert Ihrer Clientanforderungs-ID in der entsprechenden Antwort zurückgeben soll. Sie können dies verwenden, um Anforderungen und Antworten in Netzwerkablaufverfolgungen oder EWS Managed API-Ablaufverfolgungen zu korrelieren. |
| X-ClientStatistics |
ExchangeService.SendClientLatencies |
Wird verwendet, um EWS-Latenzen an Microsoft zu melden, wenn Ihre Anwendung im Rahmen Office 365 auf Exchange Online oder Exchange Online zugreift. |
Protokollieren von Informationen aus Antworten
Ebenso wie Ihr Client den gesendeten Anforderungen zusätzliche Instrumentierung hinzufügen kann, fügt Exchange den Antworten zusätzliche Instrumentierung in Form von HTTP-Headern hinzu. Ihr Client sollte diese Informationen erfassen, um die Informationen der Anforderungsinstrumentation zu erfassen.
Hinweis
Wenn Sie die verwaltete EWS-API verwenden, gibt es keine direkte Entsprechung für die HTTP-Header. Auf alle HTTP-Antwortheader kann jedoch über die ExchangeService.HttpResponseHeaders-Eigenschaft zugegriffen werden.
Tabelle 2. HTTP-Antwortheader
| HTTP-Header | Beschreibung |
|---|---|
| Anforderungs-ID |
Eine servergenerierte ID für die Anforderung, die dieser Antwort entspricht. |
| Clientanforderungs-ID |
Der Wert des Headers "client-request-id" in der Anforderung. Dieser Header ist nur vorhanden, wenn die Anforderung den Header "return-client-request-id" mit dem Wert "true" enthält. |
| X-FEServer |
Der FQDN des Clientzugriffsservers, der die Anforderung verarbeitet hat. |
| X-TargetBEServer |
Der FQDN des Postfachservers, der die Anforderung verarbeitet hat. |
| X-DiagInfo |
Zusätzliche Diagnoseinformationen, je nach Anforderung. |
| x-ms-diagnostics |
Dieser Header gilt nur, wenn die OAuth-Authentifizierung in der Anforderung verwendet wird. Es enthält einen expliziten Fehlercode, der angibt, warum eine OAuth-Authentifizierung fehlgeschlagen ist. Es hat das folgende Format: errorId;reason="reason"error_type="error type"Das Grundfeld ist eine lesbare Beschreibung des Fehlers. Das ErrorId-Feld ist eine ganze Zahl, und das _ Fehlertypfeld ist die Zeichenfolgendarstellung dieser ganzen Zahl, wie folgt:
|
Melden der EWS-Latenz an Microsoft
Wenn Ihre Anwendung die verwaltete EWS-API oder EWS zum Herstellen einer Verbindung mit Exchange Online verwendet, können Sie die Latenz in EWS-Anforderungen direkt an Microsoft melden. Die Informationen werden über den X-ClientStatistics-Anforderungsheader übergeben. Wenn Sie die verwaltete EWS-API verwenden, müssen Sie nur die ExchangeService.SendClientLatencies-Eigenschaft auf "true" festlegen. Wenn Sie EWS verwenden, müssen Sie die Zeit zwischen dem Ausgeben einer Anforderung und dem Empfangen einer Antwort messen und dann den X-ClientStatistics-Header zur nächsten EWS-Anforderung hinzufügen, die Ihre Anwendung mit dem folgenden Format sendet.
X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>
Wir verwalten Berichte für diese Latenzen und verwenden sie, um EWS-Dienste in Exchange Online kontinuierlich zu verbessern.
Nächste Schritte
Nachdem Sie Ihrer Anwendung die Client-Instrumentierung hinzugefügt haben, sind Sie besser vorbereitet, wenn ein Fehler auftritt. In diesem Fall können Sie ihre Instrumentierungsdaten verwenden, um Probleme mit der Anwendung zu beheben.