Instrumentation des demandes de client pour EWS et REST dans Exchange
Découvrez les en-têtes HTTP dans les requêtes et réponses EWS et REST qui peuvent vous aider à surveiller et résoudre les problèmes de votre application Exchange web.
Cela vous est-il déjà arrivé ? Un utilisateur de votre application signale une erreur inattendue. Vous souhaitez examiner, mais vous ne pouvez pas le reproduire. L’erreur a disparu pour l’utilisateur et vous ne disposez que de très peu de données actionnables. Frustrant, n’est-ce pas ? Examinons comment vous pouvez préparer ce scénario de manière proactive et, espérons-le, éviter toute frustration à l’avenir.
Ajouter de l’instrumentation aux demandes
Nous vous recommandons d’ajouter des en-têtes HTTP supplémentaires à vos demandes pour faciliter le dépannage. Vous devez conserver un enregistrement de ces informations quelque part (par exemple, dans un fichier journal) afin de pouvoir les récupérer ultérieurement si nécessaire. Cela est utile lors de l’examen du trafic réseau et est également utile si vous contactez le support Microsoft pour obtenir de l’aide.
Tableau 1. Demander des en-têtes pour la résolution des problèmes
| En-tête HTTP (EWS) | Équivalent d’API gérée EWS | Remarques |
|---|---|---|
| User-Agent |
ExchangeService.UserAgent |
Définissez cette valeur sur une valeur unique qui identifie votre application cliente. L’utilisation de la même valeur pour toutes les demandes que votre application envoie permet à Microsoft de résoudre les problèmes d’appel, s’ils surviennent. |
| client-request-id |
ExchangeService.ClientRequestId |
Définissez cette valeur sur une valeur unique différente pour chaque demande que votre application envoie. Nous vous recommandons d’utiliser un GUID. Cet identificateur unique est destiné à être utilisé pour corréler les activités entre deux systèmes en cas de problème. |
| return-client-request-id |
ExchangeService.ReturnClientRequestId |
Définissez cette valeur sur true pour signaler au serveur Exchange qu’il doit renvoyer la valeur de votre client-request-id dans la réponse correspondante. Vous pouvez l’utiliser pour corréler les demandes et les réponses dans les suivis réseau ou les suivis d’API gérées EWS. |
| X-ClientStatistics |
ExchangeService.SendClientLatencies |
Permet de signaler des latencies EWS à Microsoft si votre application accède à Exchange Online ou Exchange Online dans le cadre de Office 365. |
Journal des informations à partir des réponses
Tout comme votre client peut ajouter une instrumentation supplémentaire aux demandes qu’il envoie, Exchange ajoute une instrumentation supplémentaire aux réponses sous la forme d’en-têtes HTTP. Votre client doit capturer ces informations pour aller de même que les informations d’instrumentation de la demande.
Notes
Si vous utilisez l’API gérée EWS, il n’existe pas d’équivalent direct pour les en-têtes HTTP. Toutefois, tous les en-têtes de réponse HTTP sont accessibles via la propriété ExchangeService.HttpResponseHeaders.
Tableau 2. En-têtes de réponse HTTP
| En-tête HTTP | Description |
|---|---|
| request-id |
ID généré par le serveur pour la demande qui correspond à cette réponse. |
| client-request-id |
Valeur de l’en-tête client-request-id dans la demande. Cet en-tête est uniquement présent si la requête contient l’en-tête return-client-request-id avec la valeur true. |
| X-FEServer |
Nom deqdn du serveur d’accès au client qui a traitée la demande. |
| X-TargetBEServer |
Nom deqdn du serveur de boîtes aux lettres qui a traitée la demande. |
| X-DiagInfo |
Informations de diagnostic supplémentaires, en fonction de la demande. |
| x-ms-diagnostics |
Cet en-tête n’est applicable que si l’authentification OAuth est utilisée dans la demande. Il contient un code d’erreur explicite qui spécifie pourquoi une authentification OAuth a échoué. Elle prend le format suivant : errorId;reason="reason"error_type="error type"Le champ raison est une description lisible de l’erreur. Le champ errorId est un nombre integer et le champ _ type d’erreur est la représentation sous forme de chaîne de cet nombre, comme suit :
|
Signaler la latence EWS à Microsoft
Si votre application utilise l’API gérée EWS ou EWS pour se connecter à Exchange Online, vous pouvez signaler la latence dans les demandes EWS directement à Microsoft. Les informations sont transmises via l’en-tête de requête X-ClientStatistics. Si vous utilisez l’API gérée EWS, il vous s agit de définir la propriété ExchangeService.SendClientLatencies sur true. Si vous utilisez EWS, vous devez mesurer le temps entre l’émission d’une demande et la réception d’une réponse, puis ajouter l’en-tête X-ClientStatistics à la demande EWS suivante que votre application envoie, en utilisant le format suivant.
X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>
Nous tenez à jour des rapports pour ces latencies et les utilisons pour améliorer en permanence les services EWS dans Exchange Online.
Étapes suivantes
Une fois que vous avez ajouté l’instrumentation client à votre application, vous êtes mieux préparé en cas de problème. Si cela se produit, vous pouvez utiliser vos données d’instrumentation pour résoudre les problèmes de votre application.