Signed Embedding with Looker

1. قبل البدء

تتيح ميزة "التضمين الموقّع" عرض "لوحات بيانات" أو "استكشافات" أو "عناصر مرئية" أو "تقارير Looker" مضمّنة بشكل خاص للمستخدمين بدون الحاجة إلى تسجيل الدخول إلى Looker بشكل منفصل. بدلاً من ذلك، ستتم مصادقة المستخدمين من خلال تطبيقك.

تبدأ عملية التضمين الموقّع بإنشاء عنوان URL خاص في Looker ستستخدمه في إطار iframe. يحتوي عنوان URL على المعلومات التي تريد مشاركتها، ورقم تعريف المستخدم في نظامك، والأذونات التي تريد منحها لهذا المستخدم. بعد ذلك، وقِّع عنوان URL باستخدام مفتاح سري تقدّمه Looker.

المتطلبات الأساسية

  • أن يكون لديك نسخة Looker قيد التشغيل
  • أن تكون مشرفًا على نسخة Looker

ما ستتعرّف عليه

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

2. الاستضافة المناسبة لتطبيق Looker

تتضمّن بعض المتصفّحات تلقائيًا سياسة أمان تحظر ملفات تعريف الارتباط التابعة لجهات خارجية، ما يمنع عمل عملية التضمين الموقّعة. في هذا الدرس العملي، أسهل طريقة لحلّ هذه المشكلة هي السماح مؤقتًا بملفات تعريف الارتباط التابعة لجهات خارجية في متصفّحك:

في إعداد الإنتاج، يجب اختيار إحدى الاستراتيجيات التالية للتعامل مع ملفات تعريف الارتباط التابعة لجهات خارجية:

  • ضَع كلّاً من مثيل Looker والتطبيقات التي ستستخدم فيها التضمين الموقّع على النطاق نفسه. على سبيل المثال، قد يتم العثور على مثيل Looker في looker.mycompany.com بينما كان موقع التضمين الموقّع في analytics.mycompany.com.
  • فعِّل ميزة التضمين بدون ملفات تعريف الارتباط التي تتيح للمتصفّحات التي تحظر ملفات تعريف الارتباط التابعة لجهات خارجية إمكانية المصادقة على مستوى نطاقات مختلفة. يتطلّب استخدام هذا الخيار إعدادات إضافية كما هو موضّح بالتفصيل في صفحة مستندات التضمين بدون ملفات تعريف الارتباط في Looker.

3- إنشاء مفتاح سري

لإنشاء عنوان URL مضمّن موقَّع، ستحتاج إلى مفتاح سري من Looker. ولإجراء ذلك، يُرجى اتّباع الخطوات التالية:

  1. انتقِل إلى صفحة التضمين في قسم المشرف في Looker.
  2. اختَر مفعَّل من القائمة المنسدلة تضمين مصادقة الدخول المُوحَّد، ثمّ اختَر تعديل.
  3. انقر على الزر إعادة ضبط الرمز السري في قسم تضمين الرمز السري لإنشاء رمز سري للتضمين.

انسخ هذا الرمز السري إلى مكان آمن، لأنّه لن تتمكّن من استرداده من Looker بدون إعادة ضبطه. ستؤدي إعادة ضبط المفتاح إلى إيقاف أي عمليات تضمين استخدمت المفتاح القديم.

4. جمع الإدخالات لعنوان URL الموقّع المضمّن

لإنشاء عنوان URL مضمّن موقَّع، عليك جمع المعلومات التالية.

عنوان URL الخاص بالبيانات المطلوب عرضها

استرجِع عنوان URL الخاص بـ Look أو "استكشاف" أو تمثيل طلب البحث بشكل مرئي أو لوحة البيانات التي تريد تضمينها. بعد ذلك، أزِل النطاق وضَع /embed قبل المسار.

على سبيل المثال، سيصبح https://instance_name.cloud.looker.com/looks/4 هو /embed/looks/4.

أو سيصبح https://instance_name.cloud.looker.com/explore/my_model/my_explore هو /embed/explore/my_model/my_explore.

الأذونات التي تريد منحها للمستخدم المضمّن

اختَر الأذونات التي تريد منحها للمستخدم المضمّن. يمكنك العثور على الأذونات ذات الصلة بالتضمين الموقّع في صفحة مستندات التضمين الموقّع في Looker.

لأغراض هذا الدرس التطبيقي العملي، من المرجّح أن تكون الأذونات التالية هي الحد الأدنى من القائمة الممكنة:

  • access_data
  • see_lookml_dashboards
  • see_looks
  • see_user_dashboards
  • explore

إذا أردت اختبار قدرة المستخدمين المضمّنين على تصفّح المحتوى وحفظه، يمكنك أيضًا مراعاة ما يلي:

  • save_content
  • embed_browse_spaces
  • embed_save_shared_space

أذونات الوصول إلى النموذج التي تريد منحها للمستخدم المضمّن

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

سمات المستخدم التي تريد أن يتمتّع بها المستخدم المضمّن

اختَر سمات المستخدم التي تريد أن يتمتّع بها المستخدم المضمّن في Looker، إن وُجدت. قد لا يكون من الضروري إضافة أي سمات مستخدمين في هذا الدرس العملي.

المجموعات التي تريد أن ينتمي إليها المستخدم المضمّن

حدِّد أرقام تعريف المجموعات (وليس أسماء المجموعات) التي يجب أن ينتمي إليها المستخدم، إن وُجدت. قد لا يكون من الضروري إضافة أي مجموعات في هذا الدرس العملي.

رقم تعريف المستخدم والمجموعة في شركتك

تتطلّب عناوين URL الموقَّعة المضمّنة في Looker توفير معرّف فريد لكل مستخدم في تطبيقك يعرض عنصر Looker مضمّنًا. يُطلق Looker على هذا الاسم "معرّف المستخدم الخارجي" ويمكن أن يكون أي سلسلة.

يمكنك أيضًا تقديم "معرّف مجموعة خارجي" إذا كان ذلك منطبقًا. هذا المعرّف هو معرّف فريد للمجموعة التي ينتمي إليها المستخدم في تطبيقك.

5- اختيار النص البرمجي لإنشاء عناوين URL

يتطلّب إنشاء عنوان URL صالح للتضمين موقّع استخدام رمز، وذلك لتتمكّن من ترميز عنوان URL بشكل صحيح باستخدام مفتاحك السري وإنشاء عناصر أخرى ذات صلة بالأمان.

لحسن الحظ، تتوفّر عدة نماذج لبرامج نصية بلغات برمجة مختلفة في مستودع looker_embed_sso_examples على GitHub. اختَر النص البرمجي المناسب لك وانسَخه إلى بيئة التطوير.

6. ملء البيانات وتشغيل النص البرمجي

سيتضمّن النص البرمجي لإنشاء عنوان URL الذي اخترته متغيرات أو عنصرًا يمكنك وضع جميع المعلومات التي تم جمعها سابقًا فيه، بالإضافة إلى أمثلة على كيفية عرض هذه المعلومات:

اسم النص البرمجي

عدد الصفوف التقريبي للإدخال

LookerEmbedClientExample.java

15 - 28

csharp_example.cs

‫18 - 35

go_example.go

‫193 - 202

node_example.js

‫87 - 104

python_example.py

103 - 111

ruby_example.rb

88 - 101

sso_embed.php

‫14 - 27

بعد استبدال الأمثلة بالبيانات التي جمعتها، شغِّل النص البرمجي لإنشاء عنوان URL المضمّن الموقّع. دوِّن عنوان URL للخطوة التالية.

7. اختبار عنوان URL

لاختبار عنوان URL النهائي، الصِقه في أداة التحقّق من معرّف الموارد المنتظم المضمّن في صفحة تضمين ضمن قسم المشرف في Looker. على الرغم من أنّ هذه الميزة لا يمكنها تحديد ما إذا كانت البيانات والأذونات التي تتوقّعها قد تم إعدادها بشكل صحيح، يمكنها التأكّد من أنّ المصادقة تعمل بشكل سليم.

8. تضمين عنوان URL في إطار iframe

أخيرًا، يمكنك تضمين Look أو Explore أو عرض مرئي لطلب البحث أو لوحة البيانات في تطبيقك عن طريق إضافة عنوان URL الذي أنشأته إلى السمة src الخاصة بعنصر iframe. ضَع إطار iframe هذا في تطبيقك أو بيئة الاختبار.

إذا أردت ذلك، يمكنك التفاعل مع iframe باستخدام JavaScript من خلال الاستفادة من أحداث JavaScript المضمّنة في Looker.

9- معلومات إضافية

يجب إعداد ميزة التضمين الموقّع في Looker بعناية لضمان اقتصار المستخدمين المضمّنين على أذونات ورؤية البيانات المطلوبة. يُرجى مراعاة ما يلي:

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