Office 365 レポート Web サービスが返すエラーとステータス

  • [アーティクル]

標準の HTTP 応答コードを返すことに加えて、要求の処理中に問題が発生した場合、Office 365 レポート Web サービス はエラーも返します。 このトピックでは、それらのエラーを説明し、可能な場合にはそれらを回避するための推奨事項を示し、開発者による レポート Web サービス アプリケーションのトラブルシューティングを支援します。

最終更新日: 2015年9月17日

適用対象: Office 365

エラーの表示場所

主に 4 つの場所にエラーが表示されます。

HTTP 応答コード

すべての HTTP ベースの Web サービスと同様に、レポート Web サービス は HTTP 応答コードを返すことがあります。それらの定義が示されている標準の場所は、http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html です。特に、以下のエラーに注意してください。

  • HTTP 400 不正な要求: クエリに構造上の問題がある場合や、指定した要求情報が矛盾している場合に返されます。Atom や JSON 応答のエラー ペイロードにも、さらに詳しい情報が含まれています。

  • HTTP 403: 禁止: 渡した資格情報が正しくないか、アカウントの管理権限が不十分であるか、またはアクセス権限のないレポートを要求した場合に返されます。

  • HTTP 404: 見つかりません: 開発中にしばしば生じるもので、レポート名が正しくない場合に返されます。

<ServiceFault> XML ドキュメントと JSON エラー オブジェクト

開発中に表示されるエラーのほとんどは、不正な要求や不適切な列の名前などによるものです。それらのエラーを受け取ったときには、その中で問題が適格に特定されている場合が多いため、注意して読んでください。JSON 形式で返されるエラーの例を次に示します。この最初の例は、列の名前を不正確に入力した結果として生じるものです。

  {
    "error":
      {
        "code":"",
        "message":
          {
            "lang":"en-US",
            "value":"Type 'TenantReporting.MailFilterListReport' does not have a property named 'Organizations'; 
            there is no service action named 'Organizations' that is bindable to the type 
           'TenantReporting.MailFilterListReport'; and there is no type with the name 'Organizations'."
          } 
      }
  }

このエラーは、$filter オプションの構文が正しくなかったとき Atom 形式で返されています。、この例では date-time 文字列の形式が正しくありません。

<?xml version="1.0" encoding="utf-8"?>
<m:error xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <m:code />
  <m:message xml:lang="en-US">Unrecognized 'Edm.DateTime' literal 'datetime'2013010T00:00:00'' in '86'.</m:message>
</m:error>

また、アプリケーションは、レポートに固有のエラーを受け取る可能性があることを認識して、それらを適切に処理する必要があります。好都合なことに、URI 構文のロジックをデバッグした後には、それらのエラーの可能性は小さくなります。

空のレポート結果

空のレポート結果で十分に正しいという場合もあります。または、ユーザー名のスペル間違い、トランスポート ルールでの大文字小文字の間違い、その他の小さな問題で、正常に機能すると想定されていても結果は生成されないという場合もあります。そのような目障りな性質のエラーの 1 つとして、MailDetail レポートの呼び出しの試行があります。これは常にデータを返さないため、試行する必要はありません。

コード内で発生する例外

例外は、常にコード内でキャッチします。ただし、多くの場合にそれらのエラーは HTTP プロトコル処理での通常のエラーに対する通常の反応であり、いつも レポート Web サービス に関連しているとは限りません。

問題の防止

以下のリストには、開発中や使用中に難易度の高いトラブルシューティング作業を行わなくても済むようにするためのベスト プラクティスが示されています。

  • サービスのドキュメントや MailFilterList の結果を長い期間キャッシュに入れたままにしないでください。それらを 10 分ごとに取得する必要はありませんが、複数または多数の管理者が在籍する大きな組織では、名前のポリシーや規則の変更が生じることがあり、システムはそれらの頻繁ではない変更に柔軟に対応する必要があります。

  • レポート要求を行う前に、**サービスが利用可能であることを確認してください。**サービスが機能していると推定しないでください。サービスのドキュメントを定期的に要求してそれを確認し、呼び出そうとしているレポートが存在することを確認します。 要求ごとにこれを行う必要はありませんが、アプリケーションの開始時には確実に行う必要があります。

  • **名前には、常に MailFilterList 出力を使用します。**Data Leakage Prevention ポリシーなどの項目名やルール名は管理者がフォームに手作業で入力する場合が多く、スペルの間違いが生じることがあります。MailFilterList 結果に依存することで、レポート Web サービス に渡す名前を正確なものとすることができます。

  • $metadata を使用して検証します。$metadata ドキュメントには、各レポートのすべてのフィールド名が含まれています。それらの名前をアプリケーションの始動時から検索、検証、および使用することを検討してください。別の方法として、アプリケーションの使用する列名が $metadata ドキュメント内の列名と等しいことを注意深く確認することもできます。

  • サービスのバージョンを要求に含めて、応答にもその同じものが含まれていることを確認します。ただし、サービスのバージョンは 1 回だけ指定するように注意してください。アプリケーションは、それを HTTP ヘッダー内に指定するか、または REST URI 内のパラメータとして指定することができます。両方を指定した場合、同じサービスのバージョンを両方に指定した場合であっても、レポート Web サービス はエラーを返します。

  • HttpWebRequest では**リダイレクトを許可しないでください。**AllowAutoRedirect を false に設定します。

  • データを XML パーサーに渡す前、およびブラウザで JSON データを処理する前に、HTTP Content-Length 応答ヘッダーが応答バッファーの長さと一致することを確認してください。いずれかで部分的な応答を渡した場合、主要な問題も微妙な問題も生じる可能性があります。

  • **Accept-Language HTTP 要求ヘッダーを明示的に設定します。**現在 レポート Web サービス でローカライズされている項目はありませんが、この状況は変わることがあり、顧客が別のカルチャ設定を使用している場合にはアプリケーションに表示される情報が不正確になることがあります。

  • 次の要求でアプリケーションに送信されるすべてのサーバーの cookie を返します。

  • いくつかのレポートが Atom 形式の結果で <link rel="edit" title="" ... /> 項目を返すための [編集] リンクを無視します。レポートのデータは常に読み取り専用なので、アプリケーションがこのリンクを使用してデータを変更することがないようにします。

  • **ユーザー名やパスワードをテキスト定数としてアプリケーションに保存しないでください。**それらをユーザーから要求する必要がある場合には, .NET FrameworkSecureString 内に安全な方法で保存します。

  • **ログ機能を提供します。**アプリケーションで実行時エラー、ネットワーク エラー、web サービス エラーが発生したときには、要求と応答に関する詳細をログに記録する機能が必要になります。これはトラブルシューティングに役立ち、Microsoft のカスタマー サポートが Office 365 内の問題をトラブルシューティングする場合に必要となることがあります。

  • 常に空のレポートが返されるので、MailDetails レポートは呼び出さないでください。

単純なミス

サンプル アプリケーションの開発中に発生する問題のいくつかを以下に示します。これらは、レポート要求の操作に慣れるまで共通に生じる事柄です。

  • ドキュメントを参照しながら、列の名前を慎重に確認してください。

  • **レポートの名前を慎重に確認してください。**レポート名が間違っている場合には、HTTP 404 エラーが返されます。これを防止するための最適な方法は、Reporting.svc サービス記述ドキュメントに基づくレポート名だけを使用することです。

  • 対象となる項目をマッチングする際には、**MailFilterList レポートにある名前だけを使用します。**メッセージ処理のイベント、ポリシー、およびルールのすべての名前はそのドキュメントだけから取得することで、スペルが正しく、値が実際に存在するようにします。

  • **StartDate を使用する場合、EndDate を含める必要があります。**それらはどちらもオプションのマークが付いていますが、一方を含めるのであれば他方も含める必要があります。

  • **StartDate、EndDate、または Date を使用するときは、正しい構文を使用してください。**日付と時刻を指定するための ODATA 構文は、他の基準と比較して制限が幾らか多くなります。「プリミティブ データ型の ODATA 仕様」 には詳細が示されています。

  • **datetime および guid 型は $filter オプションでキャストされることに注意してください。**フィルターに使用する文字列値の datetime や guid をキャストしていない場合は、データ型に互換性がないことを示すエラーが表示されます。

  • **すべてのレポートで StartDate や EndDate が使用されるわけではありません。**詳細については、「方法: レポート期間の指定」を参照してください。

  • サービスのバージョンを 2 回要求しないでください。

  • **ODATA では、クエリのオプションを 1 つだけ指定できます。**たとえば 2 つの $filter オプションを含めないでください。

問題のように見える正常な状態

以下の状態は開発者やユーザーにとって問題のように見えることがありますが、レポート Web サービス の正常な状態である可能性があります。

  • **データはすぐに利用できません。**メール処理やメッセージ トレース等に関するほとんどのタイプの情報は、数時間でレポートで使用可能になります。ただし、「瞬時に」表示されるデータはありません。ユーザー アカウントの作成やメールボックスの頻繁な変更が可能になるのはカレンダー上での翌日なので、最大48 時間の遅延が生じることになります。アプリケーションでは、この点を考慮に入れて、ユーザーが適切な想定を行えるような設定にする必要があります。

  • **空のレポート結果は、正常である場合や、**制限の大きい時間間隔または厳密な一致条件に起因する場合があります。これがアプリケーションで正常な状態であれば、レポート要求は正常に処理されたもののデータが存在しないことをユーザーに知らせるための方法を備える必要があります。

  • 詳細データの量によっては、**レポートに数秒以上かかることがあります。**アプリケーションでは、レポートの取得に必要な時間を計測し、状況を示し、ユーザーが適切な想定を行えるような設定にする必要があります。再試行可能なデータ マートのタイムアウト エラーを受け取ることもあります。

  • レポートが返すことのできる行は最大で 2000 です。

  • **$top および $orderby オプションはすべてのレポートでサポートされているわけではありません。**これらのクエリ オプションがサポートされるかどうかについては、使用しているレポートのリファレンス ドキュメントを確認してください。一部のレポートはこれらのオプションを無視し、エラーを表示しません。

  • **レポートのデータは、最終的に削除されます。**ほとんどのデータは 1 年間保持され、メッセージ トレース データは 40 日間だけ保持されます。 トレース データの詳細なメッセージは、メッセージの最終的な処置から 48 時間のみ利用可能です。レポート期間を設定する際にはこのことに注意して、メッセージ配信の問題をトレースするようにします。

  • **Lync ユーザーは、組織のアカウントにログインする必要があります。**組織のユーザーは「ゲスト」として、またはユーザー アカウントにログオンすることで、 Lync 会議に参加できます。レポートにリストされた会議リソースは、組織のアカウントにログオンして参加している参加者のためだけに議事録を作成します。さらに、モバイル装置によって出席している参加者のためには議事録が作成されません。これは事実です。 (現状では) モバイル経由の参加者にはそれが表示されません。

  • モバイル装置経由の Lync 参加者は含まれません。 いずれの Lync レポートにも、モバイル装置上の参加者のために使用されるセッションや時間が含まれません。

  • **Lync レポートには、自己編成された会議だけが含まれます。**Lync レポートは、組織のユーザーによって編成された会議についてのみ、時間とセッション数を返します。さまざまな Lync Online プランでは、会議を編成する機能がなくても会議に参加する機能を持つ場合があるので、そのテナント内に編成される会議の数として常にゼロが返される可能性もあります。

  • **MxRecordReport、OutboundConnectorReport、および ServiceDeliveryReport は、現在の状態だけをレポートします。**これら 3 つのレポートは、現在の構成に関する情報と Office 365 システムの状態を返します。履歴情報やサマリー情報は返しません。

制御不能のイベント

Office 365 レポート Web サービス は、さまざまなソースやデータセンターからのデータを受け取る統合サービスです。以下のリストは、アプリケーションに生じる可能性があり、制御することがほとんどまたはまったく不可能な事柄のいくつかを示しています。

  • レポート Web サービス は Exchange Online インフラストラクチャに依存しています。そのため、計画されたまたは計画されないダウンタイムによって Exchange Online サービスが使用できない場合、レポート Web サービス も使用不可になることがあります。

  • **Exchange Server ポリシーは、応答時間に影響を与える可能性があります。**アプリケーションが多数の要求を行う場合やダッシュボード Web サイトが単一のサービス アカウントを使用してすべてのレポート データを収集する場合は、要求のスロットルが生じることがあります。Office 365 では、組織の管理者はスロットル設定を制御できず、現在の設定を知ることもできません。使用可能であると推定する Office 365 リソースの大きさには注意してください。

  • **データ マートへの接続が遅延したかまたは失われました。**レポート対象のデータベースが負荷の大きい作業中または多数の新規情報で更新中のとき、レポート Web サービス は一時的に使用不可になったりタイムアウトしたりする場合があります。受け取る ConnectionFailedException エラーは、"Failed to connect to the datamart." または類似のものとなります。これがアプリケーションにとって問題となることはほとんどありませんが、要求を再試行して、データやサービスが使用不可の可能性があることをユーザーに知らせる必要があります。