تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مراسلة إطار iframe في Looker المُضمَّنة

1. قبل البدء

يجب أن يكون محتوى Looker مضمّنًا داخل إطار iframe مع تضمين خاص أو تضمين الدخول المُوحَّد (SSO). في هذا الدرس التطبيقي حول الترميز، سنتفاعل مع إطار iframe عبر JavaScript لجعل صفحة الويب أكثر ديناميكية. سترسل صفحتك على الويب رسائل إلى محتوى Looker المضمّن في إطار iframe وتستلمها.

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

امتلاك نسخة Looker قيد التشغيل
أن تكون لوحة بيانات Looker مضمّنة بشكل خاص أو مضمّنة في الدخول المُوحَّد (SSO) داخل إطار iframe
فهم طريقة window.postMessage()

المعلومات التي ستطّلع عليها

كيفية تحضير إطار iframe ومثيل Looker للتفاعل باستخدام JavaScript
كيفية الاستماع إلى الأحداث من إطار iframe
كيفية إرسال رسائل الإجراءات إلى إطار iframe

المتطلبات

الوصول إلى كل من HTML وJavaScript في رمز الواجهة الأمامية لإدارة إطار iframe
إذن الوصول إلى إعدادات تضمين المشرف في نسخة Looker

2. التحضيرات

تحتاج إلى إعداد iframe ونسخة Looker قبل أن تتمكّن من التفاعل مع iframe.

إضافة سمة `id` إلى إطار iframe

يجب التحقّق من صحة الرسائل الواردة من إطار iframe. لإجراء ذلك، حدِّد السمة id على إطار iframe:

<iframe 
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>

أضِف نطاق التضمين إلى سمة `src` في إطار iframe.

حدِّد نطاق صفحة الويب التي تستضيف إطار iframe. لنفترض أن عنوان URL لصفحة الويب هو https://mywebsite.com/with/embed، ثم نطاق صفحة الويب هو https://mywebsite.com.

إذا كنت تستخدم التضمين الخاص، في src لإطار iframe، أضِف النطاق كمَعلمة طلب بحث embed_domain:

<iframe
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>

إذا كنت تستخدم ميزة التضمين باستخدام الدخول المُوحَّد (SSO)، أضِف النطاق كمَعلمة طلب بحث embed_domain إلى عنوان URL التضمين.

إضافة نطاق التضمين إلى القائمة المسموح بها في نسخة Looker

أخيرًا، يجب إضافة نطاق التضمين إلى القائمة المسموح بها في نسخة Looker للسماح بإرسال الرسائل.

انتقِل إلى صفحة تضمين في قسم المشرف على نسخة Looker. https://your_instance.looker.com/admin/embed

في الحقل السماح للنطاق المضمّن، أدخِل نطاق التضمين. بعد كتابته، اضغط على مفتاح Tab حتى يظهر النطاق في مربع. لا تضمِّن شَرطة مائلة لاحقة /.

انقر على الزر تحديث.

3- الاستماع إلى رسائل الأحداث من إطار iframe

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

فهم مخطط عنصر الحدث

مخطط كائن الحدث هو:

{
  type: "...",
  eventSpecificProperty1: ...,
  eventSpecificProperty2: ...,
  ...
}

سيحتوي الحدث دائمًا على السمة type التي تتيح لك تحديد الحدث. يتم تحديد جميع السمات الأخرى الخاصة بالأحداث في مرجع الأحداث لدينا.

استلام الحدث وتحليله

أضِف هذا الحقل إلى المكان الذي يتم فيه إعداد أو إدارة إطار iframe في صفحة الويب باستخدام JavaScript:

window.addEventListener("message", function(message) {
  const iframeElement = document.getElementById("looker");
  if (message.source === iframeElement.contentWindow) {
    if (message.origin === "https://instance_name.looker.com") {
      const event = JSON.parse(message.data);
      switch (event.type):
        case "dashboard:run:start":
          console.log("The embedded dashboard has started loading"); 
    }
  }
});

يقوم مقتطف الرمز بما يلي:

يرصد الحدث "message" من الكائن window.
يتحقق من أنّ السمة source للرسالة هي إطار iframe الذي يتضمّن محتوى Looker المضمّن.
يتم التحقّق من أنّ الموقع الإلكتروني على origin للرسالة هو نطاق نسخة Looker.
يحلّل JSON سمة data للرسالة للوصول إلى كائن الحدث وتحليله.
تؤدي إلى تفعيل خاصية type لكائن الحدث لتحديد الحدث واتخاذ إجراء بشأنه.

يمكن الآن لصفحة الويب المضيفة أن تتفاعل ديناميكيًا مع الأحداث التي يصدرها محتوى Looker المضمّن.

4. إرسال رسالة إجراء إلى إطار iframe

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

إنشاء رسالة إجراء

إنشاء رسالة إجراء داخل JavaScript على صفحة الويب:

const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);

يتّبع الكائن action التنسيق نفسه الذي يتّبعه عنصر event السابق. سيحتوي دائمًا على السمة type ثم سمات خاصة بإجراءات محدّدة في مرجع الإجراء. يجب أن تكون رسالة الإجراء بتنسيق JSON.

إرسال رسالة الإجراء

داخل JavaScript على صفحتك على الويب، يمكنك إرسال إجراء بتنسيق JSON إلى إطار iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');

حدِّد إطار iframe الذي سترسل الإجراء إليه.
يمكنك استدعاء طريقة postMessage() في السمة contentWindow الخاصة بإطار iframe لإرسال الرسالة.

يمكن الآن لصفحة الويب المضيفة تغيير حالة محتوى Looker المضمّن بشكل ديناميكي.

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

تهانينا! يمكنك الآن الاستماع إلى الأحداث من محتوى Looker المضمّن في إطار iframe وإرسال إجراءات إليه. اطلع على هذه الموارد لمزيد من المعلومات:

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