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

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

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

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

エラーの種類

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

  1. コネクタ内部エラー
  2. コネクタ外部エラー
  3. Looker Studio のエラー

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

コネクタ内部エラー

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

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

コネクタ外部エラー

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

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

Looker Studio のエラー

Looker Studio のエラーは、コネクタコードと関係のないエラーです。たとえば 期間グラフを使用しようとしたときに、期間グラフが 日付/時刻ディメンションです。

このタイプのエラーはコネクタに直接関係するものではないため、コネクタのデベロッパーが対処する必要はありません。ユーザーは Looker Studio ヘルプセンターをご覧ください。

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

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

コネクタがエラーをスローすると、Looker Studio にエラー メッセージが表示されます。 管理者ステータスに応じて異なります

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

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

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

例:

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');
}