Looker 拡張フレームワークのトラブルシューティング

Looker 拡張フレームワークを使用すると、Looker 内で実行されるカスタム JavaScript および TypeScript アプリケーションとビジュアリゼーションを構築できます。拡張機能はサンドボックス化された iframe で実行され、Extension SDK を介して Looker インスタンスとやり取りします。カスタム拡張機能で問題が発生した場合（iframe 内の空白のページやエラー メッセージ、ブラウザ コンソールの JavaScript またはクロスオリジン リソース シェアリング（CORS）エラー、Looker API リクエストの失敗（4xx または 5xx ステータス コード）、manifest.lkml 構成エラーなど）、このドキュメントは、トラブルシューティングと解決に役立ちます。

前提条件と一般的な構成要件

トラブルシューティングを開始する前に、環境、LookML プロジェクト、ユーザー アカウントが Looker 拡張機能の実行要件を満たしていることを確認します。

  • 拡張機能フレームワークが有効になっている: Looker 管理者は、[管理者] > [プラットフォーム] > [拡張機能フレームワーク] で拡張機能フレームワークの設定を有効にする必要があります。
  • LookML プロジェクトとモデルの構成: すべての拡張機能には、次のコンポーネントを含む LookML プロジェクトが必要です。
  • マニフェストの利用資格: manifest.lkml ファイルの application 宣言では、拡張機能に必要なすべての entitlements（Looker API 呼び出しの core_api_methods や外部ドメインへのリクエストの external_api_urls など）を明示的に定義する必要があります。拡張機能は、entitlements ブロックがないと実行されません。
  • ユーザー権限: ユーザーには、拡張機能の LookML モデルを含むモデルセットに対する拡張機能の権限（access_data、explore、develop など）が必要です。拡張機能を構築するには、デベロッパーに LookML の develop 権限が必要です。
  • 診断ツールと環境の詳細: トラブルシューティングを開始する前に、次の詳細とツールを準備してください。
    • Looker インスタンスの URL、LookML プロジェクト名、manifest.lkml で宣言されている application 名。
    • クライアント マシンでウェブブラウザのデベロッパー ツール（[コンソール] タブと [ネットワーク] タブ）にアクセスできること。
    • ローカル開発中に、ローカル開発サーバーを実行するターミナルにアクセスします。
    • Looker API 呼び出しの 5xx サーバーエラーの場合、Looker インスタンス ログ（セルフホスト型インスタンスの looker.log、または Looker（Google Cloud コア）インスタンスの Google Cloud コンソールの Cloud Logging のログ エクスプローラ）にアクセスします。

デバッグツリー

次のディシジョン ツリーを使用して、Looker 拡張機能フレームワークの問題のトラブルシューティングを開始します。

以降のセクションでは、ツリー内のシナリオについて詳しく説明します。

ブラウザのコンソールとネットワーク ログを調べる

Looker 拡張機能はブラウザのクライアントサイドで実行されるため、ブラウザのデベロッパー ツールで JavaScript エラー、セキュリティ ポリシー違反、失敗した HTTP リクエストを検査して、トラブルシューティングを開始します。

ブラウザのコンソールでエラーを確認する

拡張機能の読み込みや実行を妨げるクライアントサイドのエラーを特定するには:

  1. Looker で、拡張機能が読み込まれるページを開きます。
  2. ページ上の任意の場所を右クリックして [検証] を選択します（または、Windows と Linux では Ctrl+Shift+I、macOS では Command+Option+I を押します）。
  3. デベロッパー ツール パネルで [Console] タブを選択します。
  4. ページを更新して、最初の読み込み時に発生したエラーをキャプチャします。
  5. コンソールで赤色のエラー メッセージを調べます。

[ネットワーク] タブで失敗したリクエストを調べる

JavaScript バンドル、アセット、API エンドポイントの拡張機能によって行われた HTTP リクエストを分析する手順は次のとおりです。

  1. ブラウザのデベロッパー ツール パネルで、[ネットワーク] タブを選択します。
  2. [Disable cache] チェックボックスをオンにして、ブラウザが古いキャッシュ リソースを読み込まないようにします。
  3. 拡張機能が読み込まれるページを更新します。
  4. ネットワーク リクエストのリストで 4xx または 5xx ステータス コードを確認し、失敗したリクエストを選択して、[Headers]、[Payload]、[Response] タブを調べます。
    • 拡張機能バンドル（bundle.js など）の 404: 開発サーバーが実行されていること、manifest.lkml の url または file パラメータが正確であることを確認します。
    • Looker API リクエストの 401 または 403: 認証、権限、利用資格を調査します。
    • API リクエストの 400 または 422: [ペイロード] タブと [レスポンス] タブを調べて、不正な JSON または無効なリクエスト パラメータを特定します。
    • 5xx サーバーエラー: Looker インスタンスのサーバーサイドのエラーを示します。セルフホスト型インスタンスの looker.log、または Looker（Google Cloud コア）インスタンスのコンソールのログ エクスプローラで、タイムスタンプが一致するエントリを探します。

[Console] タブまたは [Network] タブにエラーが表示されない場合、または Looker が拡張機能を読み込む方法を確認する必要がある場合は、次のセクションに進みます。

マニフェストとプロジェクトの構成を確認する

プロジェクトの manifest.lkml ファイル内の application 宣言は、Looker が拡張機能を読み込む方法と、拡張機能が使用できるリソースを制御します。manifest.lkml の構成ミスは、読み込みエラーや API エラーの一般的な原因です。

  • url または file パラメータを確認する: Looker IDE で、プロジェクトの manifest.lkml ファイルを開き、application 宣言を調べます。
    • application 宣言には、url パラメータまたは file パラメータのいずれかを含める必要があります。両方を含めることはできません。
    • ローカル開発中: url パラメータが、ローカル開発サーバーによって提供される正確なプロトコル（http または https）、ホスト名、ポート、パス（例: https://localhost:8080/bundle.js）と一致していることを確認します。
    • 本番環境: LookML プロジェクト（file: "apps/bundle.js" など）または本番環境バンドル URL で、application 宣言をローカル開発 url から本番環境 file パスに更新したことを確認します。
  • manifest.lkml の利用資格を確認する: application 宣言の entitlements ブロックを確認します。拡張機能は、次のように、その権限が明示的に宣言されていない限り、Looker リソースまたは外部ドメインを使用できません。
    • core_api_methods: 拡張機能が呼び出す Looker API メソッド（core_api_methods: ["me", "all_looks", "run_inline_query"] など）をすべてリストする必要があります。
    • external_api_urls: 拡張機能が直接またはプロキシ経由でリクエストする、Looker 以外のすべての外部ドメインをリストする必要があります。
    • 追加の利用資格: 拡張機能に local_storage、navigation、new_window、new_window_external_urls、use_form_submit、use_embeds、use_downloads、use_iframes、use_clipboard、oauth2_urls、global_user_attributes、scoped_user_attributes が必要かどうかを確認します。
  • 検証、commit、デプロイ: manifest.lkml を編集したら、[Validate LookML] をクリックして変更を commit し、[Deploy to Production] をクリックして、更新された構成を有効にします。

ローカル開発用サーバーと環境のトラブルシューティング

manifest.lkml の url パラメータを使用してローカルで拡張機能を開発する場合は、ローカル開発用サーバーが実行されていて、ブラウザからアクセスできる必要があります。

  • 開発用サーバーが実行されていることを確認する: 開発用サーバーを起動したターミナル ウィンドウを確認します（yarn develop や npm start を使用するなど）。
    • ビルドがエラーなしでコンパイルされ、リスニング メッセージ（webpack compiled successfully や listening on localhost:8080 など）が表示されることを確認します。
    • サーバーが実行されていない場合は、yarn develop または npm start で起動します。
    • サーバーが構文エラーまたは依存関係の欠落エラーで終了した場合は、コードエラーを解決するか、yarn install（または npm install）を実行して、欠落しているパッケージをインストールします。
    • ポートの競合（EADDRINUSE）によりサーバーが失敗した場合は、そのポートを使用している他のプロセスを停止するか、別のポートを使用するように開発サーバーと manifest.lkml url パラメータを構成します。
  • 拡張機能の URL をブラウザで直接開きます。 url値をmanifest.lkmlからコピーし（例：https://localhost:8080/bundle.js）、新しいブラウザタブで開きます。
    • 信頼できない自己署名 SSL 証明書: ローカル開発サーバーでは、自己署名 SSL 証明書が頻繁に使用されます。ブラウザに証明書のセキュリティ警告が表示された場合は、[詳細設定] を選択し、localhost に進んで、ブラウザ セッションの証明書を信頼します。証明書が信頼されるまで、ブラウザは Looker iframe 内でのバンドルの読み込みをブロックします。
    • 接続が拒否またはブロックされた: ブラウザが URL にアクセスできない場合は、ローカル ファイアウォールまたはエンドポイント セキュリティ ソフトウェアが、構成ポートで localhost への接続をブロックしていないことを確認します。

ネットワーキング、CORS、セキュリティ ポリシーの問題のトラブルシューティング

ウェブブラウザは同一生成元ポリシーを適用します。これにより、クロスオリジン リソース シェアリング（CORS）ヘッダーとセキュリティ ポリシーが構成されていない限り、Looker は拡張機能リソースを読み込んだり、異なる生成元の外部サーバーを呼び出したりできません。

  • ブラウザ コンソールで CORS エラーを特定する: [コンソール] タブで、Cross-Origin Resource Sharing、CORS、has been blocked by CORS policy、または Access-Control-Allow-Origin ヘッダーの欠落を含むエラー メッセージを探します。
  • ローカル開発サーバーの CORS ヘッダーを構成する: webpack-dev-server（または同様のバンドラ）を使用する場合は、webpack.config.js の devServer 構成に Access-Control-Allow-Origin ヘッダーが含まれていることを確認します。 javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • 本番環境のホスティングと外部 API CORS ヘッダーを構成する: 拡張機能が外部サービス（Cloud Storage、Amazon S3、カスタム バックエンド サーバーなど）からアセットを読み込むか、データをリクエストする場合は、Looker インスタンス ドメインを許可する Access-Control-Allow-Origin ヘッダーを返すようにホスティング サービスを構成します。また、ネットワーク プロキシやファイアウォールがレスポンスから CORS ヘッダーを削除していないことを確認し、外部ドメインが manifest.lkml の external_api_urls にリストされていることを確認します。
  • コンテンツ セキュリティ ポリシー（CSP）と拡張機能の読み込みの強化を確認する: 拡張機能の読み込み時に CSP 違反が発生した場合は、[管理] > [プラットフォーム] > [拡張機能フレームワーク] の [拡張機能の読み込みの強化] 設定を確認します。

認証と API アクセスに関する問題のトラブルシューティング

拡張機能は、Extension SDK を介して、ログインしたユーザーに代わって Looker API とやり取りします。[ネットワーク] タブで API 呼び出しが 401 Unauthorized または 403 Forbidden ステータス コードで失敗した場合は、次の点を確認します。

  • 401 エラーと 403 エラーを区別する:
    • 401 Unauthorized: リクエストが認証されませんでした。このエラーは通常、拡張機能 SDK が正しく初期化されていない場合や、SDK が認証ハンドシェイクを完了する前に拡張機能が API 呼び出しを試みた場合に発生します。
    • 403 Forbidden: リクエストは認証されましたが、ログインしたユーザーに必要な Looker 権限がないか、拡張機能の manifest.lkml に core_api_methods で呼び出されたメソッドが含まれていません。
  • ユーザーのロールと権限を確認する: [管理] > [ユーザー] と [管理] > [ロール] で、ログインしているユーザーに割り当てられているロール、権限セット、モデルセットを確認します。
    • ユーザーに拡張機能を使用する権限があることを確認します。これには、拡張機能の LookML モデルと拡張機能によってクエリされるモデルを含むモデルセットに対する access_data（および必要に応じて explore または develop）が含まれます。
    • ユーザーのロールに、拡張機能が呼び出す各 Looker API エンドポイントに必要な特定の権限が含まれていることを確認します。
  • API を呼び出す前に SDK コンテキストが準備できていることを確認する: 拡張機能コードが、API メソッドを呼び出す前に Extension SDK コンテキストの初期化を待機していることを確認します。

拡張機能 SDK と依存関係のトラブルシューティング

npm または Yarn パッケージのインストールに関する問題や、SDK プロバイダ コンポーネントの欠落により、拡張機能がコンパイルまたは Looker に接続できないことがあります。

  • Node.js モジュールのインストールを確認する: ターミナルで、拡張機能プロジェクトのルート ディレクトリに移動し、node_modules ディレクトリを確認します。
    1. node_modules が見つからない場合や、依存関係が破損していると思われる場合は、node_modules ディレクトリとロックファイル（yarn.lock または package-lock.json）を削除します。
    2. 省略可: パッケージのインストールが繰り返し失敗する場合は、パッケージ マネージャーのキャッシュをクリアします（たとえば、npm cache clean --force を実行します）。
    3. インストールされている Node.js のバージョンがプロジェクトの要件と互換性があることを確認してから、yarn install または npm install を実行してクリーン インストールを行います。
  • ExtensionProvider の初期化を確認する: 拡張機能のメイン エントリ ファイル（App.js や index.js など）を開き、<ExtensionProvider>（@looker/extension-sdk-react からインポート）が Looker SDK コンテキストを必要とするアプリケーション コンポーネントをラップしていることを確認します。 javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); <ExtensionProvider> がない場合、または SDK を呼び出すコンポーネントの後に配置した場合、子コンポーネントは SDK コンテキストにアクセスできません。

実行時の JavaScript エラーとロジックエラーのトラブルシューティング

拡張機能の構成、開発サーバー、権限、SDK の設定が有効な場合は、拡張機能のカスタム JavaScript または TypeScript コードのランタイム エラーが原因である可能性があります。

  • コンソールのスタック トレースを分析する: ブラウザの [コンソール] タブで、赤色のエラー メッセージを見つけて展開矢印をクリックし、完全なスタック トレースを表示します。スタック トレースの先頭行には、エラーが発生したソースコードのファイルと行番号が表示されます。ファイルリンク（MyComponent.js:42 など）をクリックすると、[Sources] タブの該当する行に直接移動します。
  • 未定義の値または null 値を確認する: TypeError: Cannot read properties of undefined などのエラーの場合は、コードがネストされたプロパティを読み取る前に、非同期 API レスポンスまたはプロパティの読み込みが完了していることを確認します。防御的なチェック（if (myObject && myObject.property) やオプショナル チェーン myObject?.property など）を追加します。
  • API レスポンスの形式を確認する: Looker API 呼び出しによって返される実際のデータ構造をコードが処理することを確認します（たとえば、配列メソッドを呼び出す前に、レスポンス ペイロードがオブジェクトか配列かを確認します）。
  • ブレークポイントとロギングを使用したデバッグ: ブラウザの [Sources] タブで、失敗した行の前にブレークポイントを設定して実行を一時停止し、変数の値をリアルタイムで検査します。または、console.log() ステートメントを追加して実行フローをトレースします。

Looker バージョンの互換性を確認する

Looker のメジャー機能の更新または変更には、互換性のあるバージョンの Looker Extension SDK が必要になる場合があります。

  1. 拡張機能プロジェクトの package.json ファイルで、@looker/extension-sdk（および @looker/extension-sdk-react（使用されている場合））のバージョンを確認します。
  2. Looker ウェブ インターフェースで、[ヘルプ] > [概要] または [管理] > [全般] > [設定] でインスタンスの現在のリリース バージョンを確認します。
  3. Looker のリリース バージョンを @looker/extension-sdk のドキュメントの互換性に関するメモと比較します。
  4. Looker インスタンスが最近アップグレードされ、拡張機能が古い SDK を使用している場合、または拡張機能が以前の Looker バージョンでサポートされていない新しい SDK 機能を使用している場合は、SDK パッケージを互換性のあるバージョンに更新します。 bash npm install @looker/extension-sdk@latest パッケージを更新したら、依存関係を再インストールして開発サーバーを再起動します。

診断情報を収集する

トラブルシューティングの手順を行っても問題を解決できない場合は、サポートに問い合わせる前に次の情報を収集してください。

  1. Looker インスタンスとプロジェクトの情報:
    • Looker インスタンスの URL（例: instance_name.looker.com）。
    • Looker のリリース バージョン。
    • 拡張機能を含む LookML プロジェクトの名前と、manifest.lkml の application 名。
  2. 拡張機能の構成と SDK の詳細:
    • manifest.lkml ファイル内の application 宣言のコピーまたはスクリーンショット。
    • package.json で指定されている @looker/extension-sdk のバージョン。
    • 拡張機能がローカル開発用サーバー（url）から実行されているか、本番環境（file）にデプロイされているか。
  3. エラーログとスクリーンショット:
    • ブラウザの [Console] タブと [Network] タブのエラーのスクリーンショットまたは全文（失敗した 4xx リクエストまたは 5xx リクエストのリクエスト ヘッダーとレスポンス ペイロードを含む）。
    • API 呼び出しで 5xx サーバーエラーが常に返される場合は、looker.log（セルフホスト型インスタンスの場合）または Logging のログ エクスプローラ（Looker（Google Cloud コア）インスタンスの場合）から一致するログの抜粋。
  4. トラブルシューティングの概要と再現手順:
    • すでに実施したトラブルシューティングの手順とその結果の概要。
    • 問題を再現するための正確な手順。Looker 拡張フレームワークまたは拡張 SDK に問題があると思われる場合は、最小限の再現可能な例。

サポートに問い合わせる

上記の手順をすべて確認しても問題が解決しない場合: