Exchange で EWS と REST のクライアントの要求をインストルメント化する
Exchange アプリケーションのモニターとトラブルシューティングに役立つ EWS と REST の要求と応答の HTTP ヘッダーについて説明します。
次のような経験があるかもしれません。 アプリケーションのユーザーが予期しないエラーを報告します。 調査しようとしましたが、再現できません。 エラーがユーザーに現れなくなり、役に立つデータはほとんどありません。 これはストレスのたまる状況です。 このようなシナリオに対して事前に準備し、今後のストレス回避に役立つ可能性のある方法を説明します。
要求にインストルメンテーションを追加する
トラブルシューティングを容易にするために、要求に HTTP ヘッダーを追加することをお勧めします。後で必要になったら取得できるように、この情報をどこかに (ログ ファイルなど) 記録しておいてください。これは、ネットワーク トラフィックを調べるときに役立ちますが、Microsoft サポートに連絡して支援を求めるときにも役立ちます。
表 1. トラブルシューティングのための要求ヘッダー
| HTTP ヘッダー (EWS) | EWS マネージ API の同等物 | メモ |
|---|---|---|
| User-Agent |
ExchangeService.UserAgent |
クライアント アプリケーションを識別する一意の値に設定します。 アプリケーションが送信するすべての要求に同じ値を使用すると、呼び出しの失敗が発生した場合に、Microsoft がトラブルシューティングを行うのに役立ちます。 |
| client-request-id |
ExchangeService.ClientRequestId |
アプリケーションが送信する要求ごとに異なる一意の値に設定します。 GUID を使用することをお勧めします。 この一意の識別子は、問題が発生した場合に 2 つのシステムの間でアクティビティを関連付けるために使用されます。 |
| return-client-request-id |
ExchangeService.ReturnClientRequestId |
true に設定することで、対応する応答で client-request-id の値を返す必要があることを Exchange サーバーに通知します。 これを使用して、ネットワーク トレースまたは EWS マネージ API のトレースで要求と応答を関連付けることができます。 |
| X-ClientStatistics |
ExchangeService.SendClientLatencies |
アプリケーションが Exchange Online または Office 365 の一部としての Exchange Online にアクセスしている場合に、Microsoft に EWS の待機時間を報告するために使用されます。 |
応答からのログ情報
クライアントが送信する要求にインストルメンテーションを追加できるのと同様、Exchange も HTTP ヘッダーの形式でインストルメンテーションを応答に追加します。クライアントはこの情報を要求のインストルメンテーションの情報とともにキャプチャする必要があります。
注意
EWS マネージ API を使用している場合、HTTP ヘッダーに直接相当するものはありません。 しかし、すべての HTTP 応答ヘッダーに、ExchangeService.HttpResponseHeaders プロパティ経由でアクセスできます。
表 2. HTTP 応答ヘッダー
| HTTP ヘッダー | 説明 |
|---|---|
| request-id |
この応答に対応する要求を表す、サーバーによって生成される ID。 |
| client-request-id |
要求の client-request-id ヘッダーの値。 このヘッダーは、要求に true の値を持つ return-client-request-id ヘッダーが含まれる場合にのみ存在します。 |
| X-FEServer |
要求を処理したクライアント アクセス サーバーの FQDN。 |
| X-TargetBEServer |
要求を処理したメールボックス サーバーの FQDN。 |
| X-DiagInfo |
要求に応じた追加の診断情報。 |
| x-ms-diagnostics |
このヘッダーは、要求で OAuth 認証が使用される場合にのみ適用されます。 これには、OAuth 認証が失敗した理由を指定する明示的なエラー コードが含まれます。 次の形式を使用します。 errorId;reason="reason"error_type="error type"reason フィールドは、人間が理解しやすい形式でエラーを説明したものです。 errorId フィールドは整数、error_type フィールドは整数の文字列表現であり、次のようになります。
|
Microsoft への EWS の待機時間の報告
アプリケーションが EWS マネージ API または EWS を使用して Exchange Online に接続する場合に、EWS 要求の要求の待機時間を Microsoft に直接報告できます。 情報は、X-ClientStatistics 要求ヘッダーを使用して渡されます。 EWS マネージ API を使用する場合、必要なのは ExchangeService.SendClientLatencies プロパティを true に設定することだけです。 EWS を使用する場合は、要求を発行してから応答を受け取るまでの時間を測定し、アプリケーションが送信するその次の EWS 要求に X-ClientStatistics ヘッダーを追加する必要があります。使用する形式は次のとおりです。
X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>
Microsoft はこれらの待機時間の報告を保存し、Exchange Online の EWS のサービスを継続的に改善するために使用します。
次の手順
クライアントのインストルメンテーションをアプリケーションに追加したので、問題が発生した場合の準備がより一層整いました。 問題が発生した場合は、インストルメンテーション データを使用してアプリケーションのトラブルシューティングを行うことができます。