コミュニティ コネクタのエラー処理とメッセージ

優れたユーザー エクスペリエンスを提供するには、 ユーザーに表示するエラー メッセージで、問題に対する具体的な対処方法と手順を示すことで、エラーを正しく処理する必要があります。

このドキュメントでは、コネクタに関連するエラー、エラー メッセージの仕組み、コネクタエラーを適切に処理する方法について説明します。

情報: JavaScript で例外を処理する方法について詳しくは、try...catch 文をご覧ください。

エラーの種類

コネクタの使用時に発生するエラーの種類と原因は、一般に次の 3 つのカテゴリに分類されます。

  1. コネクタ内部エラー
  2. コネクタ外部エラー
  3. データポータルのエラー

コネクタ内部エラーおよび外部エラーは、デベロッパーの記述するコードに原因があるため、デベロッパーが対応する必要があります。

コネクタ内部エラー

コネクタ内部エラーは、コネクタの実行中に発生します。たとえば、getData() の実行中にコネクタが API レスポンスの解析に失敗すると、内部エラーと見なされます。このタイプのエラーは、事前に予測しておき、必要に応じてわかりやすい説明をユーザーに提供する必要があります。

コネクタ内部エラーの処理方法について詳しくは、コネクタエラー処理のおすすめの方法をご覧ください。

コネクタ外部エラー

コネクタ外部エラーは、コネクタの実行後に発生します。たとえば、3 つのフィールドに対して getData() リクエストを実行したにもかかわらず、2 つのフィールドのデータのみが返される場合、外部エラーと見なされます。コネクタの実行は正常に完了していますが、データポータルのリクエストが満たされていません。 このタイプのエラーは、入念なテストにより防ぐことができます。

コネクタ外部エラーを修正するには、通常、エラーの詳細情報(入手可能な場合)を確認して、コードをデバッグし、問題を特定する必要があります。コネクタのデバッグについて詳しくは、コードのデバッグをご覧ください。

データポータルのエラー

データポータルのエラーは、コネクタのコードとは無関係に発生するエラーです。たとえば、ユーザーが日時ディメンションのないデータソースを使って時系列グラフを作成しようとすると、データポータルのエラーと見なされます。

このタイプのエラーはコネクタに直接関係するものではないため、コネクタのデベロッパーが対処する必要はありません。ユーザーは、データスタジオ ヘルプセンターにアクセスして、その他の役立つ情報を確認できます。

エラー メッセージを表示する

管理ステータスに基づいてエラーの詳細情報を表示する

データポータルでは、コネクタがエラーをスローすると、ユーザーの管理ステータスに応じてエラー メッセージが表示されます。

  • ユーザーが管理ユーザーである: すべての詳細情報が表示されます。これには、エラー メッセージ、エラーの種類、スタック トレースが含まれます。
  • ユーザーが管理ユーザーでない: 詳細なエラー メッセージが表示されるのは、エラーにユーザー向けのメッセージが含まれている場合のみです。管理者以外のユーザーにエラー メッセージを表示する方法について詳しくは、ユーザー向けのエラーをスローするをご覧ください。

ユーザー向けのエラーをスローする

デフォルトでは、エラーの詳細情報はコネクタの管理者のみに公開されます。これは、スタック トレース内の API キーなど、機密性の高い情報が誤って開示されることを防ぐためです。管理者以外のユーザーにエラー メッセージを表示する場合は、データポータル Apps Script サービスの newUserError() を使用します。

例:

try {
      // API request that can be malformed.
      getDataFromAPI();
    } catch (e) {
      DataStudioApp.createCommunityConnector()
          .newUserError()
          .setDebugText('Error fetching data from API. Exception details: ' + e)
          .setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
          .throwException();

    }
    

この例では、setText() ですべてのユーザーに表示されるテキストを設定し、setDebugText() で管理ユーザーのみに表示されるテキストを設定しています。

コネクタエラー処理のおすすめの方法

コネクタコードの実行中にできるだけ多くのエラーをキャッチして処理するようにしてください。たとえば、次のような場合にエラーまたは望ましくない状態が発生することがよくあります。

  • URL の取得に失敗する(一時的なエラー、タイムアウト)
  • リクエストされた期間のデータが存在しない
  • API のデータが解析またはフォーマットできない
  • 承認トークンが取り消されている

回復可能なエラーを処理する

エラーが発生しても回復可能なコネクタ実行ポイントがある場合は、エラーの処理を試みる必要があります。たとえば、致命的でない理由(サーバーの負荷制限など)で API リクエストが失敗する場合は、エラーをスローする前に再試行します。

エラーをキャッチしてスローする

回復不能なエラーはキャッチして、再スローする必要があります。エラーを再スローする際には、ユーザーがエラーの発生原因を理解できるようにしてください。問題の対処方法がある場合は、その手順の詳細をユーザーに提示する必要があります。

ユーザー向けのエラーをスローするをご覧ください。

Stackdriver にエラーを記録する

エラーとその他のメッセージを記録するには、Stackdriver を使用します。エラーを記録することで、エラーの詳細を理解し、問題をデバッグすることができます。また、未処理の例外を発見することもできます。

Stackdriver Error Reporting、スクリプトの例外ロギングを有効にする方法、デバッグを目的としてユーザーを安全に識別する方法について詳しくは、Stackdriver Logging の使用をご覧ください。

サポート終了: 表示しても問題のないエラー メッセージに DS_USER: 接頭辞を使用する

管理者以外のユーザーにユーザー フレンドリーなエラー メッセージを表示するには、DS_USER: 接頭辞をエラー メッセージに含めます。この接頭辞は、管理者以外のユーザーに表示しても問題ないメッセージを識別するために使用され、実際のエラー メッセージには含まれません。

次の例は、管理者以外のユーザーにエラー メッセージが表示される場合と、管理者にのみエラー メッセージが表示される場合を示しています。

data-studio/errors.gs
// Admin and non-admin users will see the following error.
    try {
      // Code that might fail.
    } catch (e) {
      throw new Error('DS_USER:This will be shown to admin & non-admin.');
    }

    // Only admin users will see the following error.
    try {
      // Code that might fail.
    } catch (e) {
      throw new Error('This message will only be shown to admin users');
    }