このページは Cloud Translation API によって翻訳されました。

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

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

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

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

エラーの種類

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

コネクタ内部エラー
コネクタ外部エラー
Looker Studio のエラー

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

コネクタ内部エラー

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

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

コネクタ外部エラー

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

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

Looker Studio のエラー

Looker Studio のエラーは、コネクタコードとは無関係のエラーです。たとえば、ユーザーが日時ディメンションのないデータソースで時系列グラフを使用しようとした場合です。

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

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

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

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

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

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

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

GitHub で表示

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