تضمين Looker في Conversational Analytics

1. قبل البدء

سيرشدك هذا الدرس التطبيقي حول الترميز إلى كيفية دمج لوحة بيانات Looker مضمّنة مع محادثة تستند إلى "التحليلات الحوارية" لإنشاء تجربة موحّدة للبيانات تستند إلى اللغة الطبيعية. لتحقيق أقصى استفادة، يجب أن تكون على دراية بتضمين Looker و"الإحصاءات الحوارية" وJavaScript وReact.

ما ستتعلمه

بعد اتّباع هذا الدرس التطبيقي، ستتعرّف على ما يلي:

• كيفية إعداد تطبيق Looker Embed Reference محليًا
• كيفية إنشاء مكوّن محادثة React باستخدام مكتبة Looker Components
• كيفية إرسال فلتر لوحة البيانات المضمّنة كمرجع إلى "التحليلات الحوارية"
• كيفية تفعيل الدردشة المستندة إلى "التحليلات الحوارية" للتحكّم في فلاتر لوحة البيانات المضمّنة

المتطلبات

لإكمال هذا الدرس التطبيقي، ستحتاج إلى:

• مثيل Looker مثبَّت عليه وحدة Looker البرمجية لبيانات التركيبة السكانية في "متجر Play" مع تفعيل التضمين باستخدام الدخول المُوحَّد (SSO)
• إمكانية وصول واجهة برمجة التطبيقات والمطوّرين إلى نسخة Looker
• بيئة محلية مثبَّت عليها Node v18 وyarn وGit وgcloud
• مشروع على السحابة الإلكترونية تمّ إعداد أدوار إدارة الهوية وإمكانية الوصول هذه لحسابك:
• roles/bigquery.dataViewer عارِض بيانات في BigQuery
• roles/bigquery.user مستخدم BigQuery
• roles/looker.instanceUser مستخدم نسخة Looker

2. إعداد Conversational Analytics

لنبدأ بإعداد وكيل بيانات "الإحصاءات الحوارية" الذي ستستخدمه محادثة لوحة البيانات المضمّنة للإجابة عن الأسئلة باللغة الطبيعية.

المصادقة باستخدام gcloud

1. المصادقة باستخدام حسابك في بيئتك المحلية:

gcloud auth login

2. اضبط بيانات الاعتماد التلقائية للتطبيق (ADC) ومشروع الفوترة على gcloud:

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

تفعيل واجهات Conversational Analytics API

3. فعِّل واجهات برمجة التطبيقات لمشروع على السحابة الإلكترونية. يُرجى استبدال YOUR_PROJECT_ID بمعرّف مشروعك على Google Cloud:

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

إنشاء وكيل البيانات

4. افتح Google Colab.
5. في Google Colab، حمِّل ورقة الملاحظات هذه من مستودع Looker Embed Reference.
6. نفِّذ جميع خطوات دفتر الملاحظات. ستحتاج إلى رقم تعريف مشروعك على السحابة الإلكترونية ومعرّف الموارد المنتظم (URI) لمثيل Looker مع شرطة مائلة في النهاية، مثل "https://my.looker.app/". يجب أن تحصل على نتيجة ناجحة في نهاية ورقة الملاحظات.

يتوفّر لديك الآن موظّف دعم "التحليلات الحوارية" وهو جاهز لتلقّي رسائل المحادثة، والاستعلام عن استكشافات Looker في لوحة بيانات Looker المضمّنة، وعرض النتائج والعروض المرئية.

3- إعداد Looker Embed Reference

لنبدأ بإعداد تطبيق Looker Embed Reference في بيئتك المحلية حتى تتمكّن من تجربة مثال على دمج محادثة Conversational Analytics مع لوحة بيانات Looker مضمّنة.

إنشاء نسخة طبق الأصل من المستودع

1. استنسِخ مستودع GitHub إلى بيئتك المحلية. اطّلِع على مثال الأمر التالي أدناه:

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

2. انتقِل إلى الدليل LookerEmbedReference الذي نسخته:

cd LookerEmbedReference

إعداد خادم الواجهة الأمامية المحلّي وتشغيله

3. تثبيت التبعيات في الدليل Frontend

cd Frontend
yarn install

4. إعداد ملف .env في جذر دليل Frontend باستخدام بيانات الاعتماد يجب أن يكون YOUR_LOOKER_INSTANCE_URI هو معرّف الموارد المنتظم (URI) لنسخة Looker بدون شرطة مائلة لاحقة. يجب أن يكون محتوى الملف على النحو التالي:

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

يمكنك استخدام مثال الأمر التالي لإنشاء الملف:

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. شغِّل خادم تطوير الواجهة الأمامية:

yarn run dev

إعداد خادم الخلفية وتشغيله محليًا

6. افتح نافذة shell أو Terminal أو وحدة تحكّم أو علامة تبويب جديدة. انتقِل إلى الدليل Backend-Node وثبِّت الموارد التابعة. احرص على إبقاء نافذة الصدفة/الوحدة الطرفية السابقة مفتوحة مع تشغيل خادم الواجهة الأمامية.

cd ../Backend-Node
yarn install

7. أنشئ ملف .env في جذر دليل Backend-Node يتضمّن بيانات الاعتماد:

• ‫YOUR_LOOKER_CLIENT_ID هو معرّف عميل Looker.
• ‫YOUR_LOOKER_CLIENT_SECRET هو سر عميل Looker.
• ‫YOUR_LOOKER_EMBED_SECRET هو سر التضمين.
• YOUR_PROJECT_ID هو رقم تعريف مشروعك على السحابة الإلكترونية.
• ‫YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH هو معرّف الموارد المنتظم (URI) لنسخة Looker مع شرطة مائلة لاحقة.
• ‫YOUR_LOOKER_INSTANCE_URI هو معرّف الموارد المنتظم (URI) لنسخة Looker بدون شرطة مائلة لاحقة.

يجب أن يكون محتوى الملف على النحو التالي:

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

يمكنك استخدام مثال الأمر التالي لإنشاء الملف. استبدِل جميع بيانات الاعتماد على النحو التالي:

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. شغِّل خادم تطوير الخلفية:

yarn run dev

أصبح لديك الآن خادم تطوير الواجهة الأمامية يعمل ويعرض JavaScript لتطبيق الويب. يجب أيضًا تشغيل خادم تطوير الخلفية للتعامل مع طلبات عنوان URL المضمّن للدخول المُوحَّد وطلبات الخادم الوكيل إلى نقاط نهاية "الإحصاءات الحوارية".

4. تجربة المثال

لنختبر تطبيق الويب الذي يتم تشغيله الآن على جهازك في بيئتك.

بدء محادثة

1. افتح العنوان https://localhost:3001 في المتصفّح الذي تختاره.
2. انتقِل إلى صفحة لوحة البيانات المضمّنة مع ميزة "المحادثة" في قائمة التنقّل الرئيسية اليمنى.
3. بعد تحميل مكوّن المحادثة على يسار الصفحة، اكتب: "مرحبًا، من أنت؟"
4. دوِّن الردّ.

أنشأ التطبيق تلقائيًا عنصر محادثة في Conversational Analytics لتتبُّع سجلّ المحادثات، وتم تحميل واجهة المحادثة. عندما طرحت سؤالاً على واجهة المحادثة، أرسلت الواجهة الأمامية رسالة مستخدم إلى خادم Node الخلفي المحلي. بعد ذلك، تم توجيه الطلب إلى نقطة نهاية المحادثة في "إحصاءات المحادثات" وتلقّي الردّ منها.

فلترة لوحة البيانات المضمّنة

الآن، تعرَّف على لوحة البيانات المضمّنة وتفاعَل معها.

5. تصفَّح لوحة البيانات المضمّنة. يُرجى العِلم أنّه يغطّي بيانات التعداد السكاني على مستوى سمات ومقاييس متعدّدة.
6. يمكنك فلترة لوحة البيانات حسب الولاية والمقاطعة في أعلى يمين لوحة البيانات. اضبط الفلتر في فلتر لوحة البيانات على تكساس. بعد ذلك، انقر على زر السهم الدائري المميّز باللون الأزرق لتشغيل لوحة البيانات مرة أخرى.
7. لاحظ كيف يتم فلترة جميع بيانات التصورات حسب الولاية تكساس.

طرح سؤال مع سياق لوحة البيانات

بعد أن فلترنا لوحة البيانات، لنواصل التحقيق في البيانات الواردة فيها.

8. أرسِل "أريد معرفة أهم 5 مقاطعات ذات إيجار منخفض" في المحادثة.
9. يُرجى العِلم أنّ طلبك إلى "الإحصاءات الحوارية" يتضمّن الآن الكلمات الإضافية "فلترة حسب السمة state.state_name التي تساوي Texas".
10. الآن، لاحظ أنّه يتم فلترة طلب البحث والبيانات الخاصة بالردّ حسب الولاية تكساس.
11. بعد عرض نتائج البيانات، تمّت إعادة تشغيل لوحة البيانات المضمّنة مع ضبط فلتر المقاطعة على المقاطعات الخمس المحدّدة في بيانات النتيجة.

يمكنك الآن مواصلة التحقيق في بيانات التعداد السكاني، مع فلترة المقاطعات الخمس بسهولة.

تهانينا! لقد أعددت مثالاً بسيطًا على لوحة بيانات مضمّنة مدمَجة مع محادثة Conversational Analytics وجرّبته.

5- إنشاء مكوّن محادثة

لنتعرّف على ما يحدث في الخلفية من خلال استكشاف المكوّن Chat أولاً. نفترض أنّك تعرف كيفية تضمين لوحة بيانات Looker باستخدام Looker Embed SDK.

استخدام مكتبة Looker Component

1. افتح ملف المكوّن Chat في Frontend/src/components/EmbedChat/components/chat.js في بيئة التطوير المتكاملة المفضّلة لديك أو في نافذة الأوامر.
2. تم إنشاء المكوّن Chat باستخدام مكوّنات React القياسية لواجهة مستخدم Looker من حزمة مكتبة مكوّنات Looker.

تتيح مكتبة Looker Components التكامل السلس بين محتوى Looker وتطبيقك من خلال توفير مكوّنات React مُعدّة مسبقًا تتوافق مع الأنماط والمكوّنات في لوحة بيانات Looker مضمّنة.

إرسال رسالة إلى مستخدم

يجب أن ترسل واجهة المحادثة طلب المستخدم إلى Conversational Analytics.

3. بالقرب من أسفل ملف مكوّن Chat، يحتوي مكوّن Chat على المكوّن الفرعي ChatInput الذي يوفّر حقل الإدخال لطلب المستخدم.
4. عند الإرسال، ترسل الطريقة showAndSendUserPrompt طلب المستخدم إلى "الإحصاءات الحوارية" (يتمّ توجيهه من خلال الخلفية المستندة إلى Node).

عرض رسائل النظام

بعد أن يرسل المستخدم رسالة إلى "الإحصاءات الحوارية"، علينا عرض ردّها.

5. بالقرب من أسفل ملف مكوّن Chat، يحتوي مكوّن Chat على المكوّن الفرعي MessageList الذي يتضمّن منطق عرض الرسائل من "الإحصاءات الحوارية" استنادًا إلى نوع الرسالة.
6. تعالج الدالة streamAndParseResponse الاستجابة من خلال محاولة تحليل رسائل النظام الصالحة باستمرار من استجابة JSON للبث. عندما يتم تحليل رسالة نظام صالحة بنجاح، يتم عرضها في MessageList.

ننصحك بشدة بعرض رسائل النظام من "الإحصاءات الحوارية" فور وصولها لتوفير تجربة مستخدم أكثر استجابة.

يتألف ردّ "التحليلات الحوارية" على طلب المستخدم من عدة رسائل نظام تغطي مصادر البيانات التي تم البحث فيها وطلب البحث والنتائج والعروض المرئية وغير ذلك. قد يؤدي انتظار وصول جميع رسائل النظام إلى افتراض المستخدم وجود مشاكل في الأداء أو التطبيق.

لقد استكشفت الآن كيف يرسل المكوّن Chat، الذي تم إنشاؤه باستخدام مكتبة Looker Components، رسالة مستخدم ويعيد بث الرد.

6. إرسال فلاتر لوحة البيانات إلى Conversational Analytics

لنتعرّف الآن على كيفية تضمين فلاتر لوحة البيانات في طلب المستخدم حتى تتمكّن ميزة "الإحصاءات الحوارية" من فلترة طلب البحث باستخدام سياق لوحة البيانات (فلاترها).

الاستماع إلى حدث تغيير الفلتر في لوحة البيانات

1. افتح ملف المكوّن EmbedChat في Frontend/src/components/EmbedChat/EmbedChat.js, الذي يمثّل صفحة التطبيق التي تحتوي على لوحة البيانات المضمّنة والمدمجة مع المكوّن Chat الذي تم استكشافه سابقًا.
2. يستمع المكوّن EmbedChat إلى الحدث "dashboard:filters:changed" من لوحة البيانات المضمّنة باستخدام طريقة .on(...) في Embed SDK. بعد ذلك، يخزّن المكوّن الفلاتر الحالية في حالة الفلتر.

إرسال حالة الفلتر إلى "إحصاءات المحادثات"

3. يمرِّر المكوّن EmbedChat الفلاتر إلى المكوّن Chat، الذي يحوّل كل فلتر إلى سلسلة مثل "Filter on dimension '...' being ..." في الطريقة showAndSendUserPrompt ليتم إلحاقها بطلب المستخدم.

ليس من الضروري أن يكون اسم فلتر لوحة البيانات أو مفتاحه هو نفسه اسم السمة الفعلية. يجب ربط مفتاح الفلتر باسم السمة الفعلي لكي تفهم "إحصاءات المحادثات" السمات التي يجب الفلترة استنادًا إليها.

في هذه الحالة، على سبيل المثال في المكوّن Chat، يربط العنصر FIELD_FILTER_MAP اسم السمة "state.state_name" بمفتاح الفلتر "State 📍". بعد ذلك، تستخدم طريقة showAndSendUserPrompt الخريطة لتحديد اسم السمة التي سيتم الفلترة استنادًا إليها.

7. التحكّم في فلاتر لوحة البيانات من المحادثة

أخيرًا، لنتعرّف على كيفية تفعيل مكوّن Chat للتحكّم في فلاتر لوحة البيانات المضمّنة.

تحديد الفلاتر التي تريد ضبطها

1. تتحقّق طريقة streamAndParseResponse في مكوّن Chat دائمًا من وجود رسالة نظام تتضمّن نتائج البيانات من "الإحصاءات الحوارية".
2. عندما تحلّل الطريقة streamAndParseResponse رسالة نظام تتضمّن نتائج بيانات، فإنّها تتحقّق ممّا إذا كانت أيّ سمات في البيانات تتطابق مع السمات في الفلاتر.
3. في هذه الحالة، تحوّل الطريقة streamAndParseResponse أعمدة البيانات إلى فلاتر في لوحة البيانات. في هذه المرة، تستخدم الطريقة FIELD_FILTER_MAP مرة أخرى، ولكن بشكل عكسي، أي من اسم السمة إلى مفتاح الفلتر. قيم الفلتر هي القيم في عمود البيانات.

إرسال حدث تغيير الفلتر إلى لوحة البيانات المضمّنة

4. باستخدام فلاتر لوحة البيانات المطلوبة، تستدعي الطريقة streamAndParseResponse الطريقة setFilters للمكوّن Chat مع الفلاتر المطلوبة.
5. يؤدي ذلك إلى استدعاء طريقة setDashboardFilters في المكوّن EmbedChat، ما يؤدي إلى إرسال حدثَين، "dashboard:filters:update" مع الفلاتر و"dashboard:run" إلى لوحة البيانات المضمّنة على الفور باستخدام طريقة send في Embed SDK.
6. يغيّر الحدث "dashboard:filters:update" فلاتر لوحة البيانات المضمّنة، بينما يعيد الحدث "dashboard:run" تنفيذ طلبات البحث في لوحة البيانات باستخدام الفلاتر الجديدة.

يجب إرسال الحدث "dashboard:run" بعد الحدث "dashboard:filters:update". لا يعيد الحدث "dashboard:filters:update" تنفيذ طلبات البحث في لوحة البيانات تلقائيًا.

8. الخاتمة والنقاط الرئيسية

لقد أعددت مثالاً عمليًا خاصًا بك على لوحة بيانات Looker مضمّنة ومدمجة مع محادثة Conversational Analytics. لقد تعلّمت كيفية تفعيل استكشاف البيانات المستند إلى اللغة الطبيعية باستخدام لوحة بيانات Looker المضمّنة و"الإحصاءات الحوارية".

• لقد أنشأت مكوّن محادثة باستخدام مكتبة Looker Component.
• لقد نقلت سياق لوحة بيانات Looker المضمّنة إلى "التحليلات الحوارية" لتسهيل استكشاف البيانات.
• لقد فعّلت "الإحصاءات الحوارية" للتحكّم في فلاتر لوحة البيانات المضمّنة من أجل الحصول على سياق محسّن أثناء استكشاف البيانات.

الخطوات التالية

• مزيد من المعلومات عن إمكانات Conversational Analytics
• عدِّل تطبيق المثال Looker Embed Reference ليعمل مع لوحات بيانات Looker المضمّنة.
• جرِّب حالات الاستخدام الأخرى المضمّنة المتوفّرة في تطبيقك النموذجي Looker Embed Reference الذي يتم تشغيله على جهازك.