Menyematkan Looker dengan Analisis Percakapan

1. Sebelum memulai

Codelab ini akan memandu Anda mengintegrasikan dasbor Looker tersemat dengan chat yang didukung Analisis Percakapan untuk menciptakan pengalaman data yang terpadu dan didukung bahasa alami. Untuk mendapatkan nilai maksimal, Anda harus memahami penyematan Looker, Analisis Percakapan, JavaScript, dan React.

Yang akan Anda pelajari

Setelah mengikuti codelab ini, Anda akan mempelajari:

• Cara menyiapkan aplikasi Referensi Sematan Looker secara lokal
• Cara membuat komponen React chat dengan library Komponen Looker
• Cara mengirim filter dasbor sematan sebagai konteks ke Analisis Percakapan
• Cara mengaktifkan percakapan yang didukung Analisis Percakapan untuk mengontrol filter dasbor sematan Anda

Yang Anda butuhkan

Untuk menyelesaikan codelab ini, Anda memerlukan:

• Instance Looker dengan ASC Demographic Data Looker Block yang diinstal dan penyematan SSO yang diaktifkan
• Akses API dan developer ke instance Looker Anda
• Lingkungan lokal dengan Node v18, yarn, Git, dan gcloud terinstal
• Project cloud dengan peran IAM ini disiapkan untuk akun pengguna Anda:
• roles/bigquery.dataViewer BigQuery Data Viewer
• roles/bigquery.user Pengguna BigQuery
• roles/looker.instanceUser Pengguna Instance Looker

2. Menyiapkan Analisis Percakapan

Mari siapkan agen data Analisis Percakapan yang akan digunakan chat dasbor sematan Anda untuk menjawab pertanyaan bahasa alami.

Menggunakan gcloud untuk melakukan autentikasi

1. Lakukan autentikasi dengan akun pengguna Anda di lingkungan lokal:

gcloud auth login

2. Tetapkan kredensial default aplikasi (ADC) dan project penagihan di gcloud Anda:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Mengaktifkan Conversational Analytics API

3. Aktifkan Cloud Project API. Ganti YOUR_PROJECT_ID dengan ID project Google Cloud Anda:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Buat agen data

4. Buka Google Colab.
5. Di dalam Google Colab, muat notebook ini dari repositori Referensi Sematan Looker.
6. Jalankan semua langkah notebook. Anda akan memerlukan ID project Cloud dan URI instance Looker dengan garis miring di akhir, seperti "https://my.looker.app/". Anda akan mendapatkan hasil yang berhasil di akhir notebook.

Anda kini memiliki agen data Analisis Percakapan yang tersedia dan siap menerima pesan chat, mengkueri eksplorasi Looker di dasbor Looker tersemat Anda, serta menampilkan hasil dan visualisasi.

3. Menyiapkan Referensi Sematan Looker

Siapkan aplikasi Referensi Sematan Looker di lingkungan lokal Anda agar Anda dapat mencoba contoh mengintegrasikan chat Analisis Percakapan dengan dasbor Looker yang disematkan.

Membuat clone repositori

1. Buat clone repositori github ke lingkungan lokal Anda. Lihat contoh perintah berikut di bawah:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Buka direktori LookerEmbedReference yang telah Anda clone:

cd LookerEmbedReference

Menyiapkan dan menjalankan server frontend lokal

3. Instal dependensi di direktori Frontend

cd Frontend
yarn install

4. Siapkan file .env di root direktori Frontend dengan kredensial. YOUR_LOOKER_INSTANCE_URI harus berupa URI instance Looker Anda tanpa garis miring di akhir. Isi file harus sebagai berikut:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Anda dapat menggunakan contoh perintah berikut untuk membuat file:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Jalankan server pengembangan frontend:

yarn run dev

Siapkan dan jalankan server backend secara lokal

6. Buka shell, terminal, konsol, atau tab baru. Buka direktori Backend-Node dan instal dependensi. Pastikan untuk tetap menjalankan server frontend di shell/terminal sebelumnya.

cd ../Backend-Node
yarn install

7. Siapkan file .env di root direktori Backend-Node dengan kredensial:

• YOUR_LOOKER_CLIENT_ID adalah client ID Looker Anda.
• YOUR_LOOKER_CLIENT_SECRET adalah rahasia klien Looker Anda.
• YOUR_LOOKER_EMBED_SECRET adalah secret penyematan Anda.
• YOUR_PROJECT_ID adalah project ID Cloud Anda.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH adalah URI instance Looker Anda dengan garis miring di akhir.
• YOUR_LOOKER_INSTANCE_URI adalah URI instance Looker Anda tanpa garis miring di akhir .

Isi file harus sebagai berikut:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Anda dapat menggunakan contoh perintah berikut untuk membuat file. Ganti semua kredensial yang sesuai:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Jalankan server dev backend:

yarn run dev

Sekarang Anda telah menjalankan server dev frontend, yang melayani JavaScript untuk aplikasi web. Anda juga menjalankan server pengembangan backend untuk menangani permintaan URL Sematan SSO dan permintaan proxy ke endpoint Conversational Analytics.

4. Coba contohnya

Sekarang, mari kita coba aplikasi web Anda yang berjalan secara lokal di lingkungan Anda.

Memulai percakapan

1. Buka alamat https://localhost:3001 di browser pilihan Anda.
2. Buka halaman Dasbor Sematan dengan Chat di navigasi utama sebelah kiri.
3. Setelah komponen chat di sebelah kanan dimuat, ketik: "Halo, siapa kamu?"
4. Catat responsnya.

Aplikasi secara otomatis membuat objek conversation Analisis Percakapan untuk melacak histori chat dan memuat antarmuka chat. Saat Anda mengajukan pertanyaan ke antarmuka chat, frontend akan mengirimkan pesan pengguna ke server backend Node lokal Anda. Kemudian, permintaan dan respons dari endpoint chat Conversational Analytics akan di-proxy.

Memfilter dasbor sematan

Sekarang, pelajari dasbor sematan dan berinteraksi dengannya.

5. Scroll dasbor yang disematkan. Perhatikan bahwa laporan ini mencakup data sensus di berbagai dimensi dan metrik.
6. Anda dapat memfilter dasbor berdasarkan Negara Bagian dan Kabupaten di kiri atas dasbor. Tetapkan filter pada filter dasbor ke Texas. Kemudian, pilih tombol panah melingkar yang baru ditandai dengan warna biru untuk menjalankan ulang dasbor.
7. Perhatikan bagaimana semua data visualisasi difilter berdasarkan negara bagian Texas.

Mengajukan pertanyaan dengan konteks dasbor

Setelah memfilter dasbor, mari kita lanjutkan penyelidikan data di dasbor.

8. Kirimkan "Tell me the top 5 counties with lowest rent" di chat.
9. Perhatikan bahwa perintah Anda ke Analisis Percakapan kini berisi kata-kata tambahan "Filter pada dimensi 'state.state_name' yang merupakan Texas".
10. Sekarang, perhatikan bahwa kueri dan data respons difilter berdasarkan negara bagian Texas.
11. Selain itu, setelah hasil data ditampilkan, dasbor sematan Anda telah dijalankan kembali dengan filter County yang ditetapkan ke 5 county yang ditentukan dalam data hasil.

Anda kini dapat melanjutkan penyelidikan data sensus, dengan 5 wilayah yang difilter dengan mudah untuk Anda.

Selamat! Anda telah menyiapkan dan mencoba contoh sederhana dasbor sematan yang terintegrasi dengan chat Analisis Percakapan.

5. Membangun komponen chat

Mari kita pahami apa yang terjadi di balik layar, dengan terlebih dahulu mempelajari komponen Chat. Kami mengasumsikan Anda memahami cara menyematkan dasbor Looker dengan Looker Embed SDK.

Menggunakan library Komponen Looker

1. Buka file komponen Chat di Frontend/src/components/EmbedChat/components/chat.js di IDE favorit Anda atau di terminal Anda.
2. Komponen Chat dibuat dengan komponen React UI Looker standar dari paket Looker Components Library.

Looker Components Library memungkinkan integrasi yang lancar antara konten Looker dan aplikasi Anda dengan menyediakan komponen React siap pakai yang sesuai dengan gaya dan komponen dalam dasbor Looker yang disematkan.

Mengirim pesan pengguna

Antarmuka chat perlu mengirimkan perintah pengguna ke Conversational Analytics.

3. Di dekat bagian bawah file komponen Chat, komponen Chat berisi subkomponen ChatInput, yang menyediakan kolom input untuk perintah pengguna.
4. Saat mengirimkan, metode showAndSendUserPrompt mengirimkan perintah pengguna ke Analytics Percakapan (di-proxy melalui backend Node Anda).

Streaming dan menampilkan pesan sistem

Setelah pengguna mengirim pesan ke Conversational Analytics, kita perlu menampilkan responsnya.

5. Di dekat bagian bawah file komponen Chat, komponen Chat berisi subkomponen MessageList, yang berisi logika untuk menampilkan pesan dari Analisis Percakapan berdasarkan jenis pesan.
6. Metode streamAndParseResponse menangani respons, dengan terus mencoba mengurai pesan sistem yang valid dari respons JSON streaming. Setiap kali pesan sistem yang valid berhasil diuraikan, pesan tersebut akan ditampilkan di MessageList.

Sebaiknya tampilkan pesan sistem dari Analisis Percakapan segera setelah pesan tersebut tiba untuk pengalaman pengguna yang lebih responsif.

Respons Analisis Percakapan terhadap perintah pengguna terdiri dari beberapa pesan sistem, yang mencakup sumber data yang dikueri, kueri, hasil, visualisasi, dan lainnya. Menunggu semua pesan sistem tiba dapat membuat pengguna mengasumsikan adanya masalah performa atau aplikasi.

Sekarang Anda telah mempelajari cara komponen Chat, yang dibuat dengan library Komponen Looker, mengirim pesan pengguna dan mengalirkan kembali respons.

6. Mengirim filter dasbor ke Analisis Percakapan

Sekarang, mari kita pahami cara menyertakan filter dasbor dalam perintah pengguna agar Analisis Konversasional dapat memfilter kuerinya dengan konteks dasbor (filternya).

Memproses peristiwa perubahan filter dasbor

1. Buka file komponen EmbedChat di Frontend/src/components/EmbedChat/EmbedChat.js, yang merepresentasikan halaman aplikasi yang berisi dasbor sematan yang terintegrasi dengan komponen Chat yang telah dijelajahi sebelumnya.
2. Komponen EmbedChat memproses peristiwa "dashboard:filters:changed" dari dasbor sematan dengan metode .on(...) Embed SDK. Kemudian, komponen menyimpan filter saat ini dalam status filternya.

Mengirim status filter ke Conversational Analytics

3. Komponen EmbedChat meneruskan filter ke komponen Chat, yang mengonversi setiap filter menjadi string seperti "Filter on dimension '...' being ..." dalam metode showAndSendUserPrompt untuk ditambahkan ke perintah pengguna.

Nama atau kunci filter dasbor tidak harus sama dengan nama dimensi sebenarnya. Anda harus memetakan kunci filter ke nama dimensi sebenarnya agar Analytics Percakapan memahami dimensi yang akan difilter.

Dalam hal ini, misalnya di komponen Chat, objek FIELD_FILTER_MAP-nya memetakan nama dimensi "state.state_name" ke kunci filter "State 📍". Kemudian, metode showAndSendUserPrompt menggunakan peta untuk menentukan nama dimensi yang akan difilter.

7. Mengontrol filter dasbor dari chat

Terakhir, mari kita lihat cara mengaktifkan komponen Chat untuk mengontrol filter dasbor sematan.

Menentukan filter yang akan ditetapkan

1. Metode streamAndParseResponse komponen Chat selalu memeriksa pesan sistem dengan hasil data dari Analisis Percakapan.
2. Setiap kali metode streamAndParseResponse mengurai pesan sistem dengan hasil data, metode tersebut akan memeriksa apakah ada dimensi dalam data yang sesuai dengan dimensi dalam filter.
3. Jika ya, metode streamAndParseResponse akan mengonversi kolom data menjadi filter dasbor. Kali ini, metode tersebut menggunakan FIELD_FILTER_MAP lagi, tetapi secara terbalik, yaitu mengonversi dari nama dimensi ke kunci filter. Nilai filter adalah nilai dalam kolom data.

Mengirim peristiwa perubahan filter ke dasbor sematan

4. Dengan filter dasbor yang diinginkan, metode streamAndParseResponse memanggil metode setFilters komponen Chat dengan filter yang diinginkan.
5. Tindakan ini memanggil metode setDashboardFilters komponen EmbedChat, yang mengirimkan dua peristiwa, "dashboard:filters:update" dengan filter dan "dashboard:run" ke dasbor sematan secara berurutan menggunakan metode send Embed SDK.
6. Peristiwa "dashboard:filters:update" mengubah filter dasbor sematan, sedangkan peristiwa "dashboard:run" menjalankan kembali kueri dasbor dengan filter baru.

Anda harus mengirim "dashboard:run" setelah peristiwa "dashboard:filters:update". Peristiwa "dashboard:filters:update" tidak otomatis menjalankan ulang kueri dasbor.

8. Kesimpulan dan poin penting

Anda telah menyiapkan contoh kerja dasbor Looker sematan yang terintegrasi dengan chat Analisis Percakapan. Anda telah mempelajari cara mengaktifkan eksplorasi data yang didukung bahasa alami dengan dasbor Looker tersemat dan Analisis Percakapan.

• Anda telah membuat komponen chat dengan library Komponen Looker.
• Anda meneruskan konteks dasbor Looker yang disematkan ke Analisis Percakapan untuk mempermudah eksplorasi data.
• Anda mengaktifkan Analisis Percakapan untuk mengontrol filter dasbor sematan guna meningkatkan konteks saat menjelajahi data.

Langkah berikutnya

• Pelajari lebih lanjut kemampuan Analisis Percakapan.
• Perbarui aplikasi contoh Looker Embed Reference agar berfungsi dengan dasbor Looker sematan Anda sendiri.
• Coba kasus penggunaan sematan lainnya yang tersedia di aplikasi contoh Referensi Sematan Looker yang berjalan secara lokal.