Perhatikan bahwa Anda sedang melihat dokumentasi Looker. Untuk dokumentasi Looker Studio, buka https://support.google.com/looker-studio.

Halaman ini diterjemahkan oleh Cloud Translation API.

Pengantar Embed SDK

Embed SDK Looker adalah library fungsi yang dapat Anda tambahkan ke kode aplikasi web berbasis browser untuk mengelola dasbor, Tampilan, dan Jelajah tersemat 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 mudah 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

Contoh ini membuat konteks penyematan Looker, menyisipkannya ke elemen DOM dengan ID dashboard, lalu menampilkan dasbor dengan ID 11 dalam konteks penyematan Looker. 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.

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

const setupDashboard = (dashboard) => {
  document.querySelector('#run').addEventListener('click', () => {
    dashboard.send('dashboard:run')
  })
}

LookerEmbedSDK.createDashboardWithId(11)
  .appendTo('#dashboard')
  .on('dashboard:run:start',
      () => updateState('#dashboard-state', 'Running')
  )
  .on('dashboard:run:complete',
      () => updateState('#dashboard-state', 'Done')
  )
  .build()
  .connect()
  .then(setupDashboard)
  .catch((error: 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.

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 repo Looker Embed SDK:

Instal Node.js, jika Anda belum memilikinya.
Download atau clone repositori /looker-open-source/embed-sdk.
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 web Anda dan, secara opsional, endpoint di server Anda yang akan melakukan autentikasi. Ini digunakan oleh semua konten tersemat.

Sertakan nomor port jika diperlukan untuk menjangkau server Looker dari klien browser. Contoh: looker.example.com:443

LookerEmbedSDK.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).

LookerEmbedSDK.createDashboardWithId(id)

atau

LookerEmbedSDK.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')

Anda dapat menambahkan pengendali peristiwa:

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

Anda selesai dengan mem-build elemen tersemat:

.build()

Menghubungkan ke konten tersemat

Jika ingin mengirim pesan ke dan menerima pesan dari elemen tersemat, Anda harus memanggil connect(), yang menampilkan Promise yang me-resolve ke antarmuka komunikasi elemen tertentu:

.connect()
.then(setupDashboard)
.catch(console.error)

Membuat URL untuk SDK

Dokumentasi utama untuk URL penyematan yang ditandatangani Looker ada di halaman dokumentasi Penyematan yang ditandatangani. Satu-satunya perbedaan saat membuat URL untuk SDK adalah Anda harus menambahkan parameter sdk=2 ke URL penyematan bersama parameter lainnya, seperti filter dan parameter embed_domain. Parameter ini memungkinkan Looker menentukan bahwa SDK ada dan memanfaatkan fitur tambahan yang disediakan oleh SDK. Contoh:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

SDK tidak dapat menambahkan parameter ini sendiri karena parameter tersebut merupakan bagian dari URL sematan yang ditandatangani.

Endpoint autentikasi

Karena secret penyematan harus dijaga dengan cermat, URL penyematan yang ditandatangani tidak dapat dibuat di browser. Untuk mempermudah dan meningkatkan keamanan prosesnya, Anda dapat mengikuti langkah-langkah berikut:

Terapkan fungsi penandatanganan URL di server web Anda. Server harus menampilkan URL yang ditandatangani menggunakan salah satu proses yang didokumentasikan di repositori GitHub Contoh SSO Penyematan Looker.
Teruskan URL penyematan yang ditandatangani ke endpoint penandatanganan tersebut di Embed SDK. Lokasi endpoint ditentukan oleh parameter authUrl di LookerEmbedSDK.init().

Jika ditentukan, setiap kali elemen sematan dibuat hanya menggunakan ID, URL sematan akan dibuat menggunakan jenis elemen, host Looker yang disediakan, dan parameter apa pun yang disediakan. Contoh:

LookerEmbedSDK.init('looker.example.com', '/looker_auth')
LookerEmbedSDK.createcreateDashboardWithId(11)
  .build()

Contoh sebelumnya akan memanggil endpoint /looker_auth dan menampilkan URL sematan yang ditandatangani yang dapat digunakan untuk membuat konten sematan:

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

Konfigurasi autentikasi lanjutan

Endpoint autentikasi dapat dikonfigurasi lebih lanjut untuk mengizinkan header permintaan kustom serta dukungan CORS. Anda dapat melakukannya dengan meneruskan objek opsi ke metode init:


LookerEmbedSDK.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
  })

Node helper

Metode helper penandatanganan createSignedUrl() disediakan di server_utils/auth_utils.ts. Penggunaannya adalah sebagai berikut:

import { createSignedUrl } from './auth_utils'

app.get('/looker_auth', function(req, res) {
  // TO DO: Add your code here to authenticate that the request is from a valid user
  const src = req.query.src;
  const host = 'https://looker.example.com'
  const secret = YOUR_EMBED_SECRET
  const user = authenticatedUser
  const url = createSignedUrl(src, user, host, secret);
  res.json({ url });
});

Ini adalah struktur data pengguna:

interface LookerEmbedUser {
  external_user_id: string
  first_name?: string
  last_name?: string
  session_length: number
  force_logout_login?: boolean,
  permissions: LookerUserPermission[]
  models: string[]
  group_ids?: number[]
  external_group_id?: string
  user_attributes?: {[key: string]: any}
  access_filters: {}
}

Parameter access_filters dihapus di Looker 3.10, tetapi masih diperlukan dengan placeholder kosong di URL sematan.

Pemecahan masalah

Logging

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 = ''