Memecahkan masalah framework ekstensi Looker

Framework ekstensi Looker memungkinkan Anda membangun aplikasi dan visualisasi JavaScript dan TypeScript kustom yang berjalan di dalam Looker. Ekstensi berjalan di iframe dengan sandbox dan berinteraksi dengan instance Looker Anda melalui Extension SDK. Jika Anda mengalami masalah dengan ekstensi kustom—seperti halaman kosong atau pesan error di dalam iframe, error JavaScript konsol browser atau Cross-Origin Resource Sharing (CORS), permintaan Looker API yang gagal (kode status 4xx atau 5xx), atau error konfigurasi manifest.lkml—dokumen ini akan membantu Anda memecahkan masalah dan menyelesaikannya.

Prasyarat dan persyaratan konfigurasi umum

Sebelum mulai memecahkan masalah, pastikan lingkungan, project LookML, dan akun pengguna Anda memenuhi persyaratan untuk menjalankan ekstensi Looker:

  • Framework ekstensi diaktifkan: Administrator Looker harus mengaktifkan setelan Extension Framework di bagian Admin > Platform > Extension Framework.
  • Konfigurasi model dan project LookML: Setiap ekstensi memerlukan project LookML yang mencakup komponen berikut:
  • Hak manifes: Deklarasi application dalam file manifest.lkml harus secara eksplisit menentukan semua entitlements yang diperlukan ekstensi, seperti core_api_methods untuk panggilan Looker API atau external_api_urls untuk permintaan ke domain eksternal. Ekstensi tidak akan berjalan tanpa blok entitlements.
  • Izin pengguna: Pengguna harus memiliki izin ekstensi (seperti access_data, explore, atau develop) untuk set model yang mencakup model LookML ekstensi. Untuk membangun ekstensi, developer memerlukan izin develop LookML.
  • Alat diagnostik dan detail lingkungan: Siapkan detail dan alat berikut sebelum Anda mulai memecahkan masalah:
    • URL instance Looker Anda, nama project LookML, dan nama application yang dideklarasikan di manifest.lkml.
    • Akses ke alat developer browser web Anda (tab Console dan Network) di komputer klien.
    • Selama pengembangan lokal, akses ke terminal yang menjalankan server pengembangan lokal Anda.
    • Untuk error server 5xx pada panggilan Looker API, akses ke log instance Looker (looker.log pada instance yang dihosting pelanggan, atau Logs Explorer di Cloud Logging di Konsol Google Cloud untuk instance Looker (Google Cloud core)).

Hierarki proses debug

Gunakan pohon keputusan berikut untuk mulai memecahkan masalah framework ekstensi Looker:

Bagian berikut menjelaskan skenario dalam hierarki secara lebih mendetail.

Memeriksa konsol browser dan log jaringan

Karena ekstensi Looker berjalan di sisi klien di browser Anda, mulailah memecahkan masalah dengan memeriksa alat developer browser Anda untuk menemukan error JavaScript, pelanggaran kebijakan keamanan, dan permintaan HTTP yang gagal.

Memeriksa konsol browser untuk mengetahui error

Untuk mengidentifikasi error sisi klien yang mencegah ekstensi dimuat atau dijalankan:

  1. Di Looker, buka halaman tempat ekstensi dimuat.
  2. Klik kanan di mana saja di halaman, lalu pilih Periksa (atau tekan Control+Shift+I di Windows dan Linux, atau Command+Option+I di macOS).
  3. Di panel alat developer, pilih tab Console.
  4. Muat ulang halaman untuk mencatat error yang terjadi selama pemuatan awal.
  5. Periksa pesan error berwarna merah di konsol:

Memeriksa tab Jaringan untuk menemukan permintaan yang gagal

Untuk menganalisis permintaan HTTP yang dibuat oleh ekstensi untuk paket JavaScript, aset, atau endpoint API, ikuti langkah-langkah berikut:

  1. Di panel alat developer browser, pilih tab Jaringan.
  2. Centang kotak Disable cache agar browser tidak memuat resource yang di-cache yang sudah tidak berlaku.
  3. Muat ulang halaman tempat ekstensi dimuat.
  4. Periksa daftar permintaan jaringan untuk menemukan kode status 4xx atau 5xx, lalu pilih permintaan yang gagal untuk memeriksa tab Headers, Payload, dan Response:
    • 404 pada paket ekstensi (seperti bundle.js): Pastikan server pengembangan berjalan dan parameter url atau file di manifest.lkml akurat.
    • 401 atau 403 pada permintaan Looker API: Selidiki autentikasi, izin, dan hak akses.
    • 400 atau 422 pada permintaan API: Periksa tab Payload dan Response untuk mengidentifikasi JSON yang salah format atau parameter permintaan yang tidak valid.
    • Error server 5xx: Menunjukkan error sisi server pada instance Looker. Periksa looker.log di instance yang dihosting pelanggan atau Logs Explorer di konsol untuk instance Looker (Google Cloud core) guna menemukan entri dengan stempel waktu yang cocok.

Jika tidak ada error yang muncul di tab Console atau Network, atau jika Anda perlu memverifikasi cara Looker memuat ekstensi, lanjutkan ke bagian berikutnya.

Memverifikasi manifes dan konfigurasi project

Deklarasi application dalam file manifest.lkml project Anda mengontrol cara Looker memuat ekstensi dan resource yang dapat digunakan ekstensi. Kesalahan konfigurasi di manifest.lkml adalah penyebab umum kegagalan pemuatan dan API:

  • Verifikasi parameter url atau file: Di Looker IDE, buka file manifest.lkml project Anda dan periksa deklarasi application:
    • Deklarasi application harus menyertakan parameter url atau parameter file, tetapi tidak keduanya.
    • Selama pengembangan lokal: Pastikan parameter url sama persis dengan protokol (http atau https), nama host, port, dan jalur yang disajikan oleh server pengembangan lokal Anda (misalnya, https://localhost:8080/bundle.js).
    • Dalam produksi: Pastikan Anda telah memperbarui deklarasi application dari pengembangan lokal url ke jalur file produksi di project LookML (misalnya, file: "apps/bundle.js") atau URL paket produksi.
  • Verifikasi hak manifest.lkml: Tinjau blok entitlements dalam deklarasi application Anda. Ekstensi tidak dapat menggunakan resource Looker atau domain eksternal kecuali jika hak tersebut dinyatakan secara eksplisit, sebagai berikut:
    • core_api_methods: Harus mencantumkan setiap metode Looker API yang dipanggil ekstensi Anda (misalnya, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: Harus mencantumkan semua domain eksternal non-Looker yang diminta ekstensi secara langsung atau melalui proxy.
    • Hak tambahan: Verifikasi apakah ekstensi Anda memerlukan 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, atau scoped_user_attributes.
  • Validasi, commit, dan deploy: Setelah mengedit manifest.lkml, klik Validate LookML, commit perubahan Anda, lalu klik Deploy to Production agar konfigurasi yang diperbarui diterapkan.

Memecahkan masalah server dan lingkungan pengembangan lokal

Saat Anda mengembangkan ekstensi secara lokal menggunakan parameter url di manifest.lkml, server pengembangan lokal Anda harus berjalan dan dapat diakses dari browser:

  • Konfirmasi bahwa server pengembangan berjalan: Periksa jendela terminal tempat Anda memulai server pengembangan (misalnya, menggunakan yarn develop atau npm start):
    • Pastikan build dikompilasi tanpa error dan menampilkan pesan pemrosesan (seperti webpack compiled successfully atau listening on localhost:8080).
    • Jika server tidak berjalan, mulai server dengan yarn develop atau npm start.
    • Jika server keluar dengan error sintaksis atau error dependensi yang tidak ada, selesaikan error kode atau jalankan yarn install (atau npm install) untuk menginstal paket yang tidak ada.
    • Jika server gagal karena konflik port (EADDRINUSE), hentikan proses lain yang menggunakan port tersebut, atau konfigurasikan server pengembangan dan parameter manifest.lkml url untuk menggunakan port yang berbeda.
  • Buka URL ekstensi langsung di browser Anda: Salin nilai url dari manifest.lkml (misalnya, https://localhost:8080/bundle.js) dan buka di tab browser baru:
    • Sertifikat SSL yang ditandatangani sendiri dan tidak tepercaya: Server pengembangan lokal sering kali menggunakan sertifikat SSL yang ditandatangani sendiri. Jika browser Anda menampilkan peringatan keamanan sertifikat, pilih Advanced dan lanjutkan ke localhost untuk memercayai sertifikat untuk sesi browser Anda. Sebelum sertifikat dipercaya, browser akan memblokir pemuatan paket di dalam iframe Looker.
    • Koneksi ditolak atau diblokir: Jika browser tidak dapat menjangkau URL, pastikan tidak ada firewall lokal atau software keamanan endpoint yang memblokir koneksi ke localhost di port yang dikonfigurasi.

Memecahkan masalah jaringan, CORS, dan kebijakan keamanan

Browser web menerapkan Kebijakan Origin yang Sama, yang mencegah Looker memuat resource ekstensi atau memanggil server eksternal di origin yang berbeda, kecuali jika header dan kebijakan keamanan Cross-Origin Resource Sharing (CORS) dikonfigurasi:

  • Identifikasi error CORS di konsol browser: Cari pesan error di tab Console yang berisi Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy, atau header Access-Control-Allow-Origin yang tidak ada.
  • Konfigurasikan header CORS server pengembangan lokal: Jika Anda menggunakan webpack-dev-server (atau pemaket serupa), pastikan konfigurasi devServer di webpack.config.js menyertakan header Access-Control-Allow-Origin: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Konfigurasikan hosting produksi dan header CORS API eksternal: Jika ekstensi Anda memuat aset atau meminta data dari layanan eksternal (seperti Cloud Storage, Amazon S3, atau server backend kustom), konfigurasikan layanan hosting untuk menampilkan header Access-Control-Allow-Origin yang mengizinkan domain instance Looker Anda. Pastikan juga tidak ada proxy jaringan atau firewall yang menghapus header CORS dari respons, dan pastikan domain eksternal tercantum di external_api_urls dalam manifest.lkml.
  • Periksa Kebijakan Keamanan Konten (CSP) dan Pemuatan Ekstensi yang Ditingkatkan: Jika Anda mengalami pelanggaran CSP saat memuat ekstensi, periksa setelan Pemuatan Ekstensi yang Ditingkatkan di bagian Admin > Platform > Framework Ekstensi.

Memecahkan masalah autentikasi dan akses API

Ekstensi berinteraksi dengan Looker API atas nama pengguna yang login melalui Extension SDK. Jika panggilan API gagal dengan kode status 401 Unauthorized atau 403 Forbidden di tab Network, selidiki hal berikut:

  • Membedakan antara error 401 dan 403:
    • 401 Unauthorized: Permintaan tidak diautentikasi. Error ini biasanya terjadi jika Extension SDK tidak diinisialisasi dengan benar atau jika ekstensi mencoba panggilan API sebelum SDK menyelesaikan handshake autentikasinya.
    • 403 Forbidden: Permintaan telah diautentikasi, tetapi pengguna yang login tidak memiliki izin Looker yang diperlukan atau manifest.lkml ekstensi tidak menyertakan metode yang dipanggil di core_api_methods.
  • Verifikasi peran dan izin pengguna: Di Admin > Users dan Admin > Roles, periksa peran, set izin, dan set model yang ditetapkan untuk pengguna yang login:
    • Pastikan pengguna memiliki izin untuk menggunakan ekstensi, termasuk access_data (dan explore atau develop sesuai kebutuhan) untuk set model yang berisi model LookML ekstensi dan model apa pun yang dikueri oleh ekstensi.
    • Pastikan peran pengguna menyertakan izin spesifik yang diperlukan oleh setiap endpoint Looker API yang dipanggil ekstensi.
  • Pastikan konteks SDK sudah siap sebelum memanggil API: Pastikan kode ekstensi Anda menunggu konteks SDK Ekstensi diinisialisasi sebelum memanggil metode API.

Memecahkan masalah SDK Ekstensi dan dependensi

Masalah pada penginstalan paket npm atau Yarn atau komponen penyedia SDK yang tidak ada dapat mencegah ekstensi mengompilasi atau terhubung ke Looker:

  • Verifikasi penginstalan modul Node.js: Di terminal, buka direktori root project ekstensi Anda dan periksa direktori node_modules:
    1. Jika node_modules tidak ada atau dependensi tampak rusak, hapus direktori node_modules dan file kunci (yarn.lock atau package-lock.json).
    2. Opsional: Jika penginstalan paket gagal berulang kali, hapus cache pengelola paket Anda (misalnya, jalankan npm cache clean --force).
    3. Pastikan versi Node.js yang diinstal kompatibel dengan persyaratan project, lalu jalankan yarn install atau npm install untuk melakukan penginstalan bersih.
  • Periksa inisialisasi ExtensionProvider: Buka file entri utama ekstensi Anda (seperti App.js atau index.js) dan pastikan <ExtensionProvider> (diimpor dari @looker/extension-sdk-react) menggabungkan komponen aplikasi yang memerlukan konteks Looker SDK: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Jika <ExtensionProvider> tidak ada atau jika Anda menempatkannya setelah komponen yang memanggil SDK, komponen turunan tidak dapat mengakses konteks SDK.

Memecahkan masalah error logika dan JavaScript runtime

Jika konfigurasi, server pengembangan, izin, dan penyiapan SDK ekstensi sudah valid, masalahnya mungkin adalah error runtime dalam kode JavaScript atau TypeScript kustom ekstensi:

  • Menganalisis stack trace konsol: Di tab Console browser, temukan pesan error berwarna merah dan klik panah peluas untuk melihat stack trace lengkap. Baris teratas stack trace mengidentifikasi file dan nomor baris dalam kode sumber tempat error terjadi. Klik link file (misalnya, MyComponent.js:42) untuk langsung membuka baris tersebut di tab Sources.
  • Periksa nilai yang tidak ditentukan atau null: Untuk error seperti TypeError: Cannot read properties of undefined, pastikan respons atau properti API asinkron telah selesai dimuat sebelum kode Anda membaca properti bertingkat. Tambahkan pemeriksaan defensif (seperti if (myObject && myObject.property) atau optional chaining myObject?.property).
  • Verifikasi format respons API: Pastikan kode Anda menangani struktur data aktual yang ditampilkan oleh panggilan Looker API (misalnya, memverifikasi apakah payload respons adalah objek atau array sebelum memanggil metode array).
  • Debug dengan titik henti sementara dan logging: Di tab Sources browser, tetapkan titik henti sementara sebelum baris yang gagal untuk menjeda eksekusi dan memeriksa nilai variabel secara real time, atau tambahkan pernyataan console.log() untuk melacak alur eksekusi.

Memverifikasi kompatibilitas versi Looker

Update atau perubahan fitur utama di Looker dapat memerlukan versi Looker Extension SDK yang kompatibel:

  1. Periksa versi @looker/extension-sdk (dan @looker/extension-sdk-react, jika digunakan) di file package.json project ekstensi Anda.
  2. Di antarmuka web Looker, periksa versi rilis instance Anda saat ini di bagian Help > About atau Admin > General > Settings.
  3. Bandingkan versi rilis Looker Anda dengan catatan kompatibilitas dalam dokumentasi @looker/extension-sdk.
  4. Jika instance Looker Anda baru saja diupgrade dan ekstensi menggunakan SDK yang sudah tidak berlaku—atau jika ekstensi menggunakan fitur SDK yang lebih baru yang tidak didukung oleh versi Looker yang lebih lama—update paket SDK ke versi yang kompatibel: bash npm install @looker/extension-sdk@latest Setelah mengupdate paket, instal ulang dependensi dan mulai ulang server pengembangan Anda.

Mengumpulkan informasi diagnostik

Jika Anda tidak dapat menyelesaikan masalah setelah mengikuti langkah-langkah pemecahan masalah, kumpulkan informasi berikut sebelum menghubungi Dukungan:

  1. Informasi project dan instance Looker:
    • URL instance Looker (misalnya, instance_name.looker.com).
    • Versi rilis Looker.
    • Nama project LookML yang berisi ekstensi dan nama application di manifest.lkml.
  2. Konfigurasi ekstensi dan detail SDK:
    • Salinan atau screenshot deklarasi application dalam file manifest.lkml.
    • Versi @looker/extension-sdk yang ditentukan di package.json.
    • Apakah ekstensi berjalan dari server pengembangan lokal (url) atau di-deploy dalam produksi (file).
  3. Log error dan screenshot:
    • Screenshot atau teks lengkap error dari tab Console dan Network browser (termasuk header permintaan dan payload respons untuk permintaan 4xx atau 5xx yang gagal).
    • Jika panggilan API secara konsisten menampilkan error server 5xx, cocokkan kutipan log dari looker.log (untuk instance yang dihosting pelanggan) atau Logs Explorer di Logging (untuk instance Looker (Google Cloud core)).
  4. Ringkasan pemecahan masalah dan langkah-langkah reproduksi:
    • Ringkasan langkah-langkah pemecahan masalah yang telah Anda lakukan dan hasilnya.
    • Langkah-langkah pasti untuk mereproduksi masalah, atau contoh minimal yang dapat direproduksi jika Anda mencurigai adanya masalah dalam framework ekstensi Looker atau Extension SDK.

Hubungi Dukungan

Jika Anda telah memverifikasi semua langkah sebelumnya dan masalah masih belum terselesaikan: