Pengantar Embed SDK

Embed SDK Looker adalah library fungsi yang dapat Anda tambahkan ke kode aplikasi web berbasis browser untuk mengelola dasbor, Tampilan, laporan, dan Jelajah yang disematkan di aplikasi web Anda.

Embed SDK memfasilitasi penyematan dengan cara berikut:

  • Memberikan enkapsulasi konten tersemat tanpa perlu membuat elemen HTML secara manual.
  • Memberikan komunikasi point-to-point sehingga tidak ada komunikasi lintas frame. Embed SDK menangani penerusan pesan lintas-domain antara halaman web host dan konten Looker tersemat, menggunakan saluran pesan khusus.

Tanpa Embed SDK, Anda dapat memanggil atau merespons peristiwa dalam konten Looker tersemat menggunakan peristiwa JavaScript seperti dashboard:run:start atau page:changed, yang dijelaskan di halaman dokumentasi Peristiwa JavaScript tersemat. Developer yang menyematkan konten Looker dengan peristiwa JavaScript harus membuat elemen HTML untuk menyimpan konten tersemat dan mengandalkan peristiwa siaran jendela untuk komunikasi antara aplikasi web dan konten tersemat.

Perhatikan bahwa Looker Embed SDK berbeda dengan Looker API dan Looker API SDK:

  • Looker Embed SDK berada di kode sisi klien aplikasi web Anda dan mengelola konteks serta konten penyematan Looker. (Embed SDK tidak memberikan akses ke Looker API.)
  • Looker API berada di server dengan instance Looker Anda dan menjalankan perintah di server Looker.
  • SDK klien Looker API berada dalam kode aplikasi non-browser untuk memberikan akses ke fungsi Looker API.

Perhatikan bahwa Looker tidak mengontrol urutan pengiriman peristiwa oleh browser ke aplikasi web. Artinya, urutan peristiwa tidak dijamin di seluruh browser atau platform. Pastikan untuk menulis JavaScript dengan tepat untuk memperhitungkan penanganan peristiwa di berbagai browser.

Contoh cepat

Dalam contoh ini, dasbor dengan ID 11 dibuat di dalam elemen DOM dengan ID embed_container. Peristiwa dashboard:run:start dan dashboard:run:complete digunakan untuk memperbarui status UI jendela penyematan, dan tombol dengan ID run dibuat skripnya untuk mengirim pesan dashboard:run ke dasbor.

getEmbedSDK().init('looker.example.com', '/auth')

const setupConnection = (connection) => {
  document.querySelector('#run').addEventListener('click', () => {
    connection.asDashboardConnection().run()
  })
}

try {
  connection = await getEmbedSDK()
    .createDashboardWithId('11')
    .appendTo('#embed_container')
    .on('dashboard:run:start', () => updateStatus('Running'))
    .on('dashboard:run:complete', () => updateStatus('Done'))
    .build()
    .connect()
  setupConnection(connection)
} catch (error) {
  console.error('An unexpected error occurred', error)
}

Contoh yang lebih lengkap dijelaskan di halaman dokumentasi Demo Embed SDK.

Menyiapkan Looker Embed SDK

Looker Embed SDK menggunakan pola antarmuka yang lancar. Setelah menginstal Embed SDK, Anda harus membuat konten tersemat dan terhubung ke konten tersemat. Aplikasi hosting dapat berinteraksi dengan konten tersemat setelah koneksi dibuat.

Menginstal Embed SDK

Anda bisa mendapatkan library Embed SDK Looker melalui pengelola paket node (NPM) di https://www.npmjs.com/package/@looker/embed-sdk. Namun, jika ingin melihat kode contoh atau demo, Anda harus menggunakan repositori Looker Embed SDK.

Untuk menginstal Looker Embed SDK menggunakan repositori Looker Embed SDK, ikuti langkah-langkah berikut:

  1. Instal Node.js, jika Anda belum memilikinya.
  2. Download atau clone repositori /looker-open-source/embed-sdk.
  3. Di jendela terminal, buka direktori /embed-sdk dan jalankan perintah berikut:
npm install
npm start

Membuat konten tersemat

Pertama, lakukan inisialisasi SDK dengan alamat server Looker dan endpoint server aplikasi penyematan yang akan membuat URL login tersemat Looker yang ditandatangani. Server ini digunakan oleh semua konten tersemat. Untuk penyematan pribadi, hapus endpoint penandatanganan.

getEmbedSDK().init('looker.example.com', '/auth')

Kemudian, konten tersemat dibuat menggunakan serangkaian langkah untuk menentukan parameternya. Beberapa parameter ini bersifat opsional, dan beberapa bersifat wajib.

Prosesnya dimulai dengan membuat builder dengan id dasbor atau dengan url yang merujuk ke dasbor (dibuat oleh proses yang dijelaskan di halaman dokumentasi Penyematan yang ditandatangani).

getEmbedSDK().createDashboardWithId('id')

atau

getEmbedSDK().createDashboardWithUrl('url')

Kemudian, Anda dapat menambahkan atribut tambahan ke builder untuk menyelesaikan penyiapan.

Misalnya, Anda dapat menentukan tempat di halaman web untuk menyisipkan UI sematan Looker. Panggilan berikut menempatkan UI penyematan Looker di dalam elemen HTML dengan nilai ID dashboard:

.appendTo('#dashboard')

Tambahkan pengendali peristiwa:

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

Buat klien tersemat dengan memanggil metode build:

.build()

Menghubungkan ke konten tersemat

Setelah klien dibuat, panggil connect untuk membuat iframe. Proses koneksi membuat atribut src yang digunakan untuk iframe sebenarnya. Cara nilai src dihasilkan didasarkan pada cara SDK sematan diinisialisasi:

  1. Ditandatangani: Endpoint yang ditentukan oleh argumen kedua panggilan init dipanggil. Endpoint diharapkan menampilkan URL login penyematan yang ditandatangani.
  2. Tanpa cookie: Endpoint atau fungsi yang ditentukan oleh argumen kedua panggilan initCookieless dipanggil. Endpoint atau fungsi diharapkan menampilkan token tanpa cookie, khususnya token autentikasi dan navigasi. Token ditambahkan ke URL login penyematan.
  3. Pribadi: Koneksi penyematan bersifat pribadi jika argumen kedua panggilan init tidak diberikan. Dalam hal ini, URL berasal dari builder dan dihiasi dengan parameter yang diperlukan untuk penyematan Looker. Untuk penyematan pribadi, pengguna diharapkan sudah login ke Looker atau URL penyematan menyertakan parameter allow_login_screen=true.

connect menampilkan Promise yang me-resolve ke antarmuka koneksi untuk iframe tersemat.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Berinteraksi

Embed SDK 2.0.0 menampilkan koneksi terpadu yang mendukung interaksi dengan semua jenis konten Looker. Aplikasi penyematan dapat menentukan jenis konten yang ditampilkan dan berinteraksi dengan sesuai.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

Iframe tidak perlu dibuat ulang saat konten yang berbeda perlu dimuat. Sebagai gantinya, metode koneksi loadDashboard, loadLook, loadExplore, atau loadUrl dapat digunakan. Metode loadDashboard, loadLook, dan loadExplore menerima id. Metode loadUrl menerima URL sematan, dan metode ini dapat digunakan untuk menentukan parameter tambahan (seperti filter).

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Jika perlu membuat iframe baru, Embed SDK tidak akan memanggil endpoint sesi penandatanganan atau akuisisi lagi. Sebagai gantinya, iframe src akan dibuat langsung dari builder. Jika perlu membuat sesi penyematan baru, Embed SDK harus diinisialisasi ulang dengan cara berikut:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

Endpoint autentikasi URL yang ditandatangani

Bagian ini tidak berlaku untuk penyematan tanpa cookie. Lihat Penyematan tanpa cookie untuk mengetahui detailnya.

Untuk menggunakan Embed SDK, Anda harus menyediakan layanan backend yang menangani penandatanganan URL penyematan. Layanan ini dipanggil oleh Embed SDK untuk membuat URL yang ditandatangani yang unik bagi pengguna yang meminta. Proses backend dapat membuat URL sematan yang ditandatangani menggunakan secret sematan, atau proses backend dapat membuat URL dengan memanggil Looker Create Signed Embed URL API. Pembuatan dan penandatanganan URL manual menghindari pemanggilan Looker API, yang mengurangi latensi. Memanggil Looker API memerlukan lebih sedikit kode dan lebih mudah dikelola.

Contoh JavaScript untuk metode helper yang menghasilkan URL yang ditandatangani, createSignedUrl(), dapat ditemukan di server/utils/auth_utils.ts. Fungsi ini digunakan dengan cara berikut:

import { createSignedUrl } from './utils/auth_utils'

app.get('/looker_auth', function (req, res) {
  // It is assumed that the request is authorized
  const src = req.query.src
  const host = 'looker.example.com'
  const secret = ... // Embed secret from Looker Server Embed Admin page
  const user = ... // Embedded user definition
  const url = createSignedUrl(src, user, host, secret)
  res.json({ url })
})

Lihat contoh python di repositori.

Konfigurasi autentikasi lanjutan URL yang ditandatangani

Bagian ini tidak berlaku untuk penyematan tanpa cookie. Lihat Penyematan tanpa cookie untuk mengetahui detailnya.

Anda dapat mengonfigurasi endpoint autentikasi untuk mengizinkan header permintaan kustom dan dukungan CORS dengan meneruskan objek opsi ke metode init.

getEmbedSDK().init('looker.example.com', {
  url: 'https://api.acme.com/looker/auth',
  headers: [{ name: 'Foo Header', value: 'Foo' }],
  params: [{ name: 'foo', value: 'bar' }],
  withCredentials: true, // Needed for CORS requests to Auth endpoint include Http Only cookie headers
})

Pemecahan masalah

Embed SDK dibuat berdasarkan chatty. Chatty menggunakan debug untuk logging. Anda dapat mengaktifkan logging di konsol browser dengan perintah ini:

localStorage.debug = 'looker:chatty:*'
```none

Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:

```javascript
localStorage.debug = ''