Power BI Embedded: إضافة التحليلات إلى تطبيقك

يحتاج كل تطبيق SaaS في النهاية إلى التحليلات. يريد المستخدمون لوحات معلومات تعرض أنماط الاستخدام ومقاييس الأداء ونتائج الأعمال. إنشاء طبقة تحليلات مخصصة من الصفر --- مكتبات التخطيط، وخطوط أنابيب البيانات، والتخزين المؤقت، ووظائف التصدير، والتفاعلات التفصيلية --- يستغرق من 6 إلى 12 شهرًا من الجهد الهندسي والصيانة المستمرة. يوفر Power BI Embedded بديلاً: إمكانات التحليلات على مستوى المؤسسة المضمنة مباشرةً في التطبيق الخاص بك، والمدعومة بالبنية الأساسية لـ Microsoft.

إن Power BI Embedded ليس مجرد "وضع إطار iframe على الصفحة". إنها منصة كاملة لتقديم تجارب تحليلية تفاعلية وآمنة ومتعددة المستأجرين ضمن واجهة مستخدم التطبيق الخاص بك. يتفاعل عملاؤك مع التحليلات التي تبدو أصلية في منتجك بينما تستفيد من محرك التصور الناضج لـ Power BI وطبقة حساب DAX والبنية الأساسية لاتصال البيانات.

يغطي هذا الدليل البنية ونماذج المصادقة والأمان متعدد المستأجرين وتخطيط السعة وتكامل SDK واعتبارات التسعير لتضمين Power BI في التطبيق الخاص بك. إذا كنت تخطط لتنفيذ التحليلات المضمنة، فاستكشف خدمات التحليلات المضمنة في Power BI للحصول على إرشادات البنية ودعم التطوير.

الوجبات الرئيسية

• يدعم Power BI Embedded سيناريوهين: "التضمين لعملائك" (البيانات التي يمتلكها التطبيق) و"التضمين لمؤسستك" (يمتلك المستخدم البيانات)
• يوصى بالمصادقة الرئيسية للخدمة لتطبيقات SaaS متعددة المستأجرين؛ تعد حسابات المستخدمين الرئيسية أبسط ولكنها تخلق نقاط فشل واحدة
• الأمان على مستوى الصف (RLS) هو الآلية الأساسية لضمان عزل بيانات المستأجر في مجموعات البيانات المشتركة
• توفر وحدات SKU الخاصة بـ Fabric F القدرة الأكثر فعالية من حيث التكلفة للسيناريوهات المضمنة، بدءًا من F2 للتطوير
• يتيح JavaScript SDK تحكمًا برمجيًا عميقًا: تطبيق المرشحات، والتقاط الأحداث، والتحكم في التنقل، وتخصيص السمات
• يعتمد حجم السعة على المستخدمين المتزامنين، وتعقيد الاستعلام، وحجم البيانات --- وليس فقط إجمالي عدد المستخدمين
• السمات المخصصة والكروم المخفي تجعل التقارير المضمنة تبدو أصلية في تطبيقك

---

سيناريوهات التضمين: العملاء مقابل المؤسسة

التضمين لعملائك (البيانات الخاصة بالتطبيق)

يعد سيناريو "التطبيق يمتلك البيانات" هو حالة الاستخدام الأساسية لتطبيقات SaaS. تتم مصادقة تطبيقك باستخدام Power BI باستخدام حساب مستخدم أساسي أو رئيسي للخدمة، ويقوم بإنشاء رمز مميز للتضمين، ويقدم التقرير المضمن للمستخدمين النهائيين. لا يتفاعل عملاؤك مطلقًا مع Power BI بشكل مباشر ولا يحتاجون إلى تراخيص Power BI.

** التدفق المعماري: **

1. يقوم عميلك بتسجيل الدخول إلى التطبيق الخاص بك باستخدام نظام المصادقة الخاص بك.
2. تستدعي الواجهة الخلفية لتطبيقك واجهة Power BI REST API لإنشاء رمز مميز للتضمين، يتم تحديد نطاقه حسب التقرير المحدد ومجموعة البيانات ودور RLS لهذا العميل.
3. تقوم الواجهة الخلفية بإرجاع رمز التضمين وعنوان URL المضمن إلى الواجهة الأمامية.
4. تقوم الواجهة الأمامية بتهيئة Power BI JavaScript SDK باستخدام الرمز المميز للتضمين وتعرض التقرير في عنصر حاوية معين.
5. تنتهي صلاحية الرمز المميز للتضمين بعد فترة قابلة للتكوين (ساعة واحدة افتراضية)، ويقوم تطبيقك بتحديثه بشفافية.

** الخصائص الرئيسية: **

• لا يحتاج العملاء إلى تراخيص Power BI Pro أو Premium لكل مستخدم
• تتحمل أنت (موفر التطبيق) جميع تكاليف السعة من خلال وحدات SKU القماشية/المضمنة
• لديك سيطرة كاملة على ما يراه المستخدمون من خلال RLS والتصفية الآلية
• المصادقة تتم بالكامل ضمن نظام مصادقة التطبيق الخاص بك
• توفر الرموز المميزة وصولاً محدد النطاق ومحدودًا زمنيًا إلى عناصر محددة

هذا هو النموذج الذي يستخدمه بائعو البرامج المستقلون ومنصات SaaS والبوابات الداخلية حيث لا ينبغي لمستهلك التحليلات أن يعرف أو يهتم بأن Power BI هي التكنولوجيا الأساسية.

تضمين لمؤسستك (يملك المستخدم البيانات)

سيناريو "يمتلك المستخدم البيانات" مخصص لتضمين محتوى Power BI داخل التطبيقات الداخلية حيث يكون لدى المستخدمين بالفعل تراخيص Power BI (Pro أو PPU). تستخدم التجربة المضمنة هوية Power BI وأذوناته الخاصة بالمستخدم.

** التدفق المعماري: **

1. يقوم المستخدم بالمصادقة مع Azure AD من خلال التطبيق الخاص بك.
2. يحصل تطبيقك على رمز وصول نيابة عن المستخدم باستخدام تدفق OAuth 2.0 نيابةً عن المستخدم.
3. يستدعي التطبيق Power BI REST API مع الرمز المميز للمستخدم للحصول على تكوين التضمين.
4. يتم عرض التقرير مع أذونات Power BI الكاملة للمستخدم.

** الخصائص الرئيسية: **

• يجب أن يكون لدى كل مستخدم ترخيص Power BI Pro أو Premium لكل مستخدم
• يرى المستخدمون المحتوى استنادًا إلى أذونات Power BI وتعيينات RLS الخاصة بهم
• لا يلزم وجود سعة إضافية للنسيج/المضمنة (يستخدم تخصيص ترخيص Pro/PPU الخاص بالمستخدم)
• تحكم أقل لمطور التطبيق، واستقلالية أكبر للمستخدم
• بنية أبسط ولكن تكلفة ترخيص أعلى لكل مستخدم

يُستخدم هذا النموذج عادةً لبوابات الإنترانت وعمليات تكامل SharePoint والتطبيقات الداخلية حيث يكون لدى المستخدمين بالفعل تراخيص Power BI ويجب عليهم الاحتفاظ بأذونات الوصول الحالية الخاصة بهم.

الاختيار بين السيناريوهات

بالنسبة لمعظم تطبيقات SaaS التي تستهدف العملاء الخارجيين، فإن "التطبيق يمتلك البيانات" هو الاختيار الصحيح. يركز الجزء المتبقي من هذا الدليل بشكل أساسي على هذا السيناريو.

---

المصادقة: مدير الخدمة مقابل المستخدم الرئيسي

المصادقة الرئيسية للخدمة

أساس الخدمة هو هوية تطبيق Azure AD التي يثق بها Power BI للوصول إلى الموارد برمجيًا. إنها طريقة المصادقة الموصى بها لتطبيقات الإنتاج المدمجة.

متطلبات الإعداد:

1. قم بتسجيل تطبيق في Azure AD.
2. قم بإنشاء سر العميل أو الشهادة الخاصة بالتطبيق.
3. قم بإنشاء مجموعة أمان Azure AD وأضف أساس الخدمة إليها.
4. في مدخل إدارة Power BI، قم بتمكين الوصول الأساسي للخدمة لمجموعة الأمان ضمن إعدادات المستأجر > إعدادات المطور.
5. امنح الخدمة الأساسية حق الوصول إلى مساحات عمل Power BI المحددة التي تحتوي على المحتوى المضمن الخاص بك.

المزايا:

• عدم الاعتماد على حساب مستخدم محدد (يزيل نقطة فشل واحدة)
• يمكن تدوير أسرار وشهادات العميل دون انقطاع الخدمة
• يمكن تحديد نطاق مبادئ الخدمة لمساحات عمل محددة (امتياز أقل)
• يعمل مع الهويات المُدارة من Azure AD في التطبيقات المستضافة على Azure
• يدعم المصادقة المستندة إلى الشهادة لمزيد من الأمان

القيود:

• لا يمكن الوصول إلى "مساحة العمل الخاصة بي" (مساحات العمل الشخصية)
• لا يمكن استدعاء واجهات برمجة تطبيقات إدارية معينة
• يتطلب Azure AD Premium لبعض الميزات المتقدمة
• الإعداد الأولي أكثر تعقيدًا من الإعداد الرئيسي للمستخدم

مصادقة المستخدم الرئيسي

المستخدم الرئيسي هو حساب مستخدم Azure AD عادي مع ترخيص Power BI Pro أو PPU الذي يستخدمه تطبيقك للمصادقة باستخدام Power BI. يقوم التطبيق بتسجيل الدخول باسم هذا المستخدم لإنشاء الرموز المميزة للتضمين.

المزايا:

• إعداد أولي أبسط (إنشاء مستخدم، تعيين ترخيص، منح الوصول إلى مساحة العمل)
• يمكنه الوصول إلى جميع ميزات Power BI بما في ذلك واجهات برمجة التطبيقات الإدارية
• لا يلزم تسجيل تطبيق Azure AD

عيوب:

• نقطة فشل واحدة: إذا تم قفل حساب المستخدم، أو انتهت صلاحية كلمة المرور، أو تم تشغيل MFA، فسيفقد تطبيقك الوصول إلى التحليلات
• لا يمكن استخدام سياسات الوصول المشروط التي تتطلب تسجيل الدخول التفاعلي
• يتطلب تدوير كلمة المرور تحديثات التطبيق
• ينتهك أفضل الممارسات الأمنية المتمثلة في عدم استخدام الحسابات البشرية في العمليات الآلية
• تكلفة الترخيص لحساب المستخدم

التوصية: استخدم المصادقة الأساسية للخدمة لجميع عمليات نشر الإنتاج. تعد حسابات المستخدمين الرئيسية مقبولة لبيئات إثبات المفهوم والتطوير حيث تكون البساطة أكثر أهمية من الموثوقية.

إنشاء الرمز المميز وإدارته

بغض النظر عن طريقة المصادقة، يقوم التطبيق الخاص بك بإنشاء الرموز المميزة للتضمين من خلال Power BI REST API. يحتوي الرمز المميز على أذونات الجلسة المضمنة.

تضمين اعتبارات الرمز المميز:

• عمر الرمز المميز: الافتراضي هو ساعة واحدة، ويمكن تكوينه حتى 24 ساعة. تعد فترات العمر الأقصر أكثر أمانًا ولكنها تتطلب تحديثًا أكثر تكرارًا.
• نطاق الرمز المميز: يتم تحديد نطاق كل رمز مميز لتقارير ومجموعات بيانات ومساحات عمل محددة. توليد أضيق نطاق ممكن.
• هوية RLS: عند استخدام الأمان على مستوى الصف، يتم تضمين هوية RLS (اسم المستخدم والأدوار) في الرمز المميز. هذه هي الطريقة التي تضمن عزل المستأجر.
• تحديث الرمز المميز: يجب أن تراقب الواجهة الأمامية انتهاء صلاحية الرمز المميز وتطلب رمزًا مميزًا جديدًا قبل انتهاء صلاحيته. توفر JavaScript SDK أحداثًا لهذا الغرض.

مثال لتدفق إنشاء الرمز المميز:

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
{
    "datasets": [{"id": "dataset-guid"}],
    "reports": [{"id": "report-guid"}],
    "identities": [{
        "username": "[email protected]",
        "roles": ["TenantRole"],
        "datasets": ["dataset-guid"]
    }]
}

تحتوي الاستجابة على رمز التضمين والطابع الزمني لانتهاء الصلاحية. تقوم الواجهة الخلفية لديك بتخزين هذا الرمز المميز مؤقتًا (مع مراعاة انتهاء الصلاحية) وتقديمه لطلبات الواجهة الأمامية المصادق عليها.

---

الأمان على مستوى الصف متعدد المستأجرين

لماذا يعد RLS أمرًا بالغ الأهمية للتضمين

في تطبيق SaaS متعدد المستأجرين، غالبًا ما تتواجد بيانات العديد من العملاء في نفس مجموعة بيانات Power BI. بدون الأمان على مستوى الصف، يمنح رمز التضمين الوصول إلى جميع البيانات الموجودة في مجموعة البيانات. يضمن RLS أن يرى كل عميل بياناته الخاصة فقط، على الرغم من مشاركة مجموعة البيانات الأساسية.

لا يعد RLS اختياريًا للسيناريوهات المضمنة متعددة المستأجرين. الفشل في عزل المستأجر هو خرق للبيانات. تصميم RLS كعنصر تحكم أمني أساسي، وليس فكرة لاحقة.

خدمة RLS الثابتة

تحدد خدمة RLS الثابتة قواعد التصفية الثابتة باستخدام تعبيرات DAX في Power BI Desktop. يحتوي كل دور على مجموعة من عوامل تصفية الجدول التي تقيد الصفوف المرئية.

مثال:

"دور المستأجر" مع عامل التصفية هذا في جدول العملاء:

[TenantId] = USERNAME()

عند إنشاء رمز مميز للتضمين، يقوم التطبيق الخاص بك بتعيين قيمة USERNAME() إلى معرف المستأجر الحالي. يقوم عامل تصفية DAX بتقييد كافة الاستعلامات على الصفوف التي يتطابق فيها TenantId.

يعد Static RLS بسيطًا وفعالًا لعزل المستأجر بشكل مباشر. يعمل بشكل جيد عندما:

• يعتمد عزل المستأجر على عمود واحد (TenantId) ينتشر من خلال العلاقات
• يرى جميع المستأجرين نفس هيكل التقرير، ولكن تمت تصفيته فقط وفقًا لبياناتهم
• عدد أدوار RLS صغير ومستقر

نظام RLS الديناميكي

يستخدم RLS الديناميكي تعبيرات DAX التي يتم تقييمها في وقت الاستعلام بناءً على هوية المستخدم. يؤدي ذلك إلى تمكين سيناريوهات أمان أكثر تعقيدًا دون إنشاء أدوار منفصلة لكل مستأجر.

أنماط RLS الديناميكية الشائعة:

نمط USERPRINCIPALNAME():

[Email] = USERPRINCIPALNAME()

يقوم رمز التضمين بتعيين اسم مستخدم الهوية الفعالة إلى البريد الإلكتروني للمستخدم. يتطابق عامل التصفية مع عمود البريد الإلكتروني في جدول تعيين الأمان.

نمط جدول الأمان: قم بإنشاء جدول أمان مخصص لتعيين المستخدمين بالبيانات التي يمكنهم الوصول إليها:

قم بتطبيق عوامل تصفية RLS التي تربط جدول الأمان هذا بجداول الحقائق الخاصة بك من خلال العلاقات. يدعم هذا النمط الأذونات على مستوى المستخدم داخل المستأجر، وليس فقط العزل على مستوى المستأجر.

اختبار RLS والتحقق من صحتها

اختبار ما قبل النشر:

1. في Power BI Desktop، استخدم "عرض باسم" لاختبار كل دور RLS باستخدام نماذج لأسماء المستخدمين.
2. تحقق من أن التصفية المتبادلة بين الجداول تحترم حدود RLS.
3. حالات حافة الاختبار: المستخدمون الذين ليس لديهم صفوف متطابقة (يجب أن يروا تقارير فارغة، وليس أخطاء)، والمستخدمون الذين لديهم أدوار متعددة، وقيم فارغة في أعمدة التصفية.
4. تحقق من أن مقاييس DAX التي تستخدم ALL() أو REMOVEFILTERS() لا تتجاوز RLS (لا ينبغي لها ذلك، ولكن تحقق).

التحقق من الإنتاج:

• أتمتة اختبار RLS كجزء من مسار النشر الخاص بك
• إنشاء رموز التضمين لهويات المستأجر الاختبارية والتحقق من تطابق نتائج الاستعلام مع البيانات المتوقعة
• مراقبة محاولات تجاوز RLS في مقاييس السعة (أنماط الاستعلام غير العادية، وأحجام البيانات غير المتوقعة)
• إجراء مراجعات أمنية ربع سنوية لتكوينات RLS

---

تحجيم السعة ووحدات SKU للنسيج

فهم القدرة

يتطلب Power BI Embedded سعة مخصصة --- موارد الحوسبة المحجوزة لأحمال العمل المضمنة لديك. يتم قياس السعة بوحدات السعة (CUs)، التي تحدد قوة المعالجة المتاحة لتقديم التقارير وتنفيذ الاستعلامات وتحديث مجموعات البيانات.

القدرة ليست لكل مستخدم. إنها عبارة عن مجموعة مشتركة من الحوسبة تستمد منها جميع جلساتك المضمنة. وهذا يعني أن التسعير يقيس التزامن وتعقيد الاستعلام، وليس مع إجمالي عدد المستخدمين.

خيارات SKU للنسيج F

وحدات SKU الخاصة بـ Microsoft Fabric F هي نموذج التسعير الحالي لسعة Power BI Embedded. لقد استبدلوا وحدات SKU القديمة بنموذج أكثر مرونة وقدرة على الإيقاف المؤقت.

ملاحظات هامة:

• المستخدمون المتزامنون لا يعني إجمالي المستخدمين. وهذا يعني أن المستخدمين يقومون بالاستعلام بنشاط في نفس اللحظة. النسبة النموذجية هي 5-10% من إجمالي المستخدمين المتزامنين في أي وقت محدد.
• هذه أرقام توجيهية تقريبية. تعتمد السعة الفعلية بشكل كبير على مدى تعقيد الاستعلام وحجم النموذج وعدد المرئيات لكل تقرير.
• يمكن إيقاف وحدات SKU مؤقتًا عند عدم استخدامها (على عكس وحدات P SKU القديمة)، وهو أمر ذو قيمة للتطوير وأعباء العمل الموسمية.
• يتضمن F64 والإصدارات الأحدث ميزات Power BI Premium (التقارير المرقّمة، والذكاء الاصطناعي، ومسارات النشر) دون أي تكلفة ترخيص إضافية.

منهجية تحديد حجم السعة

الخطوة 1: تقدير المستخدمين المتزامنين.

المستخدمون المتزامنون = إجمالي المستخدمين × ذروة نسبة التزامن

بالنسبة للوحات معلومات تحليلات SaaS التي يتم الوصول إليها خلال ساعات العمل: نسبة التزامن 5-10%. بالنسبة للوحات المعلومات التشغيلية التي يتم فحصها بشكل متكرر على مدار اليوم: نسبة التزامن 15-25%. بالنسبة للوحات المعلومات المستندة إلى الأحداث (المراقبة في الوقت الفعلي والتنبيهات): نسبة التزامن 30-50%.

الخطوة 2: تقييم مدى تعقيد طلب البحث.

تقارير بسيطة (5-10 صور، تجميعات أساسية، جدول حقائق واحد): 1x خط الأساس. التقارير المتوسطة (10-20 صورة، معلومات الوقت، جداول الحقائق المتعددة): 2-3x خط الأساس. تقارير معقدة (أكثر من 20 عنصر مرئي، DAX معقد، مجموعات بيانات كبيرة، استعلامات عبر المصادر): 4-6x خط الأساس.

الخطوة 3: حساب السعة المطلوبة.

ابدأ برمز SKU الذي يطابق تقدير المستخدم المتزامن الخاص بك من الجدول أعلاه. اضرب بعامل التعقيد الخاص بك. إذا تجاوزت النتيجة سعة الاستعلام المتزامن لـ SKU، فانتقل إلى المستوى التالي.

الخطوة 4: التحقق من الصحة من خلال اختبار الحمل.

التحجيم النظري هو نقطة البداية. قبل إطلاق الإنتاج، قم بإجراء اختبار التحميل باستخدام أحجام بيانات واقعية وأنماط الاستعلام ومستويات التزامن. توفر Microsoft أداة اختبار حمل السعة Power BI Embedded لهذا الغرض.

الخطوة 5: التخطيط للنمو.

قم بإضافة 30-50% من الارتفاع فوق ذروتك الحالية لاستيعاب النمو على مدى 6-12 شهرًا القادمة. يمكن ترقية وحدات SKU الخاصة بـ F دون توقف، حتى تتمكن من ضبط الحجم الصحيح بشكل تدريجي.

استراتيجيات تحسين التكلفة

• إيقاف مؤقت لقدرات التطوير في غير أوقات العمل. يتم إصدار فواتير F SKU لكل ثانية عندما تكون نشطة، ومجانية عند الإيقاف المؤقت. يمكن أن يؤدي التشغيل التلقائي للإيقاف المؤقت/الاستئناف باستخدام Azure Automation أو Logic Apps إلى تقليل تكاليف التطوير بنسبة 60-70%.

• تحسين النماذج قبل توسيع نطاق السعة. غالبًا ما يتفوق النموذج المحسن جيدًا على F8 على النموذج المحسن بشكل سيئ على F32. استثمر في تحسين النموذج قبل طرح مشكلات الأداء في الحوسبة.

• استخدم جداول التجميع لمجموعات البيانات الكبيرة. يؤدي التجميع المسبق للبيانات بتفاصيل مشتركة (يوميًا وأسبوعيًا وشهريًا) إلى تقليل معالجة الاستعلام بنسبة 80-90% للمرئيات على مستوى الملخص مع الحفاظ على إمكانية التعمق لمزيد من التفاصيل.

• تنفيذ التخزين المؤقت على مستوى التقرير من خلال Power BI REST API. بالنسبة للوحات المعلومات ذات تحديثات البيانات غير المتكررة، تعمل النتائج المخزنة مؤقتًا على تقليل استهلاك السعة لكل جلسة مستخدم.

• فكر في القدرات المنفصلة لأحمال العمل المختلفة. يؤدي عزل عمليات التحديث عن الاستعلامات التفاعلية إلى منع ارتفاعات التحديث من تدهور تجربة المستخدم. وهذا مهم بشكل خاص إذا كان لديك مجموعات بيانات كبيرة يتم تحديثها أثناء ساعات العمل.

---

تكامل جافا سكريبت SDK

التضمين الأساسي

توفر Power BI JavaScript SDK (powerbi-client) واجهة برمجية لتضمين محتوى Power BI والتحكم فيه في تطبيق الويب الخاص بك.

** التثبيت: **

npm install powerbi-client

تدفق التضمين الأساسي:

import * as pbi from 'powerbi-client';

const powerbi = new pbi.service.Service(
    pbi.factories.hpmFactory,
    pbi.factories.wpmpFactory,
    pbi.factories.routerFactory
);

const embedConfig = {
    type: 'report',
    id: reportId,
    embedUrl: embedUrl,
    accessToken: embedToken,
    tokenType: pbi.models.TokenType.Embed,
    settings: {
        panes: {
            filters: { visible: false },
            pageNavigation: { visible: true }
        },
        background: pbi.models.BackgroundType.Transparent,
        layoutType: pbi.models.LayoutType.Custom,
        customLayout: {
            displayOption: pbi.models.DisplayOption.FitToWidth
        }
    }
};

const reportContainer = document.getElementById('report-container');
const report = powerbi.embed(reportContainer, embedConfig);

التحكم البرمجي

يكشف SDK عن تحكم برمجي شامل في التقرير المضمن:

تطبيق المرشحات:

const filter = {
    $schema: "http://powerbi.com/product/schema#basic",
    target: {
        table: "Sales",
        column: "Region"
    },
    operator: "In",
    values: ["North", "South"],
    filterType: pbi.models.FilterType.BasicFilter
};

await report.setFilters([filter]);

** التقاط الأحداث: **

report.on('loaded', function() {
    console.log('Report loaded successfully');
});

report.on('dataSelected', function(event) {
    const data = event.detail;
    // Handle user selection — navigate to detail page, update other UI, etc.
});

report.on('pageChanged', function(event) {
    const pageName = event.detail.newPage.displayName;
    // Track page navigation in your analytics
});

تحديث الرمز:

report.on('tokenExpired', async function() {
    const newToken = await fetchNewEmbedToken();
    await report.setAccessToken(newToken);
});

** التحكم في الملاحة: **

// Navigate to a specific page
const pages = await report.getPages();
const targetPage = pages.find(p => p.displayName === 'Revenue Analysis');
await targetPage.setActive();

// Set a specific slicer value
const visuals = await targetPage.getVisuals();
const slicer = visuals.find(v => v.type === 'slicer');
await slicer.setSlicerState({
    filters: [{
        $schema: "http://powerbi.com/product/schema#basic",
        target: { table: "Date", column: "Year" },
        operator: "In",
        values: [2026],
        filterType: pbi.models.FilterType.BasicFilter
    }]
});

العرض المرحلي للأداء

بالنسبة للتقارير المعقدة التي تحتوي على العديد من العناصر المرئية، يعمل العرض المرحلي على تحسين الأداء الملموس من خلال عرض المحتوى الموجود في الجزء العلوي أولاً:

const embedConfig = {
    // ... standard config
    settings: {
        // ... other settings
        commands: [{
            visualRendered: {
                phase: 1,
                visualNames: ['revenue-kpi', 'trend-chart', 'summary-table']
            }
        }]
    }
};

report.on('visualRendered', function(event) {
    if (event.detail.phase === 1) {
        // Hide loading spinner, show report
        document.getElementById('loading').style.display = 'none';
    }
});

---

السمات والعلامات التجارية المخصصة

سبب أهمية السمات المخصصة

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

هيكل موضوع JSON

يتم تعريف سمات Power BI على أنها ملفات JSON مع التحكم في الألوان والخطوط والافتراضيات المرئية وتصميم العناصر:

{
    "name": "MyApp Theme",
    "dataColors": [
        "#2563EB", "#7C3AED", "#059669", "#D97706",
        "#DC2626", "#0891B2", "#4F46E5", "#65A30D"
    ],
    "background": "#FFFFFF",
    "foreground": "#1E293B",
    "tableAccent": "#2563EB",
    "textClasses": {
        "callout": {
            "fontSize": 28,
            "fontFace": "Inter, sans-serif",
            "color": "#0F172A"
        },
        "title": {
            "fontSize": 14,
            "fontFace": "Inter, sans-serif",
            "color": "#1E293B"
        },
        "header": {
            "fontSize": 12,
            "fontFace": "Inter, sans-serif",
            "color": "#475569"
        },
        "label": {
            "fontSize": 11,
            "fontFace": "Inter, sans-serif",
            "color": "#64748B"
        }
    },
    "visualStyles": {
        "*": {
            "*": {
                "border": [{
                    "color": {"solid": {"color": "#E2E8F0"}},
                    "radius": 8
                }],
                "background": [{
                    "color": {"solid": {"color": "#FFFFFF"}},
                    "transparency": 0
                }]
            }
        }
    }
}

تطبيق السمات برمجياً

يمكن تطبيق السمات في وقت التضمين أو تبديلها ديناميكيًا (مفيدة لدعم الوضع المظلم):

// Apply theme at embed time
const embedConfig = {
    // ... standard config
    theme: { themeJson: customThemeJson }
};

// Switch theme dynamically (e.g., light/dark mode toggle)
await report.applyTheme({ themeJson: darkThemeJson });

إخفاء Power BI Chrome

للحصول على مظهر أصلي بالكامل، قم بإخفاء عناصر واجهة المستخدم المضمنة في Power BI واستبدلها بعناصر التحكم في التطبيق الخاصة بك:

const settings = {
    panes: {
        filters: { visible: false },      // Hide filter pane
        pageNavigation: { visible: false } // Hide page tabs
    },
    bars: {
        actionBar: { visible: false },     // Hide action bar
        statusBar: { visible: false }      // Hide status bar
    },
    background: pbi.models.BackgroundType.Transparent,
    visualRenderedEvents: true
};

ثم أنشئ عناصر تحكم مخصصة للتنقل والتصفية والتصدير في إطار عمل واجهة المستخدم للتطبيق الخاص بك. استخدم JavaScript SDK لتطبيق عوامل التصفية وتغيير الصفحات وتشغيل عمليات التصدير برمجيًا عندما يتفاعل المستخدمون مع عناصر التحكم المخصصة الخاصة بك.

يتطلب هذا الأسلوب المزيد من جهود التطوير ولكنه ينتج تجربة سلسة حيث لا يستطيع المستخدمون التمييز بين الميزات الأصلية لتطبيقك ومحتوى Power BI المضمن.

---

تحسين الأداء للمضمنة

أداء الواجهة الأمامية

• تحميل SDK ببطء. يبلغ حجم Power BI JavaScript SDK حوالي 300 كيلو بايت. قم بتحميله بشكل غير متزامن وفقط عندما ينتقل المستخدم إلى صفحة التحليلات.
• تحميل الرموز المميزة للتضمين مسبقًا. قم بإنشاء الرموز المميزة للتضمين قبل أن يطلب المستخدم التقرير. إذا كان تطبيقك يعلم أن المستخدم من المحتمل أن يعرض التحليلات (استنادًا إلى أنماط التنقل)، فقم بتحميل الرمز المميز مسبقًا أثناء انتقالات الصفحة.
• استخدم تضمين bootstrap. تدعم SDK نمط bootstrap الذي يقوم بتهيئة إطار iframe قبل أن يتوفر رمز التضمين، مما يقلل وقت التحميل المتوقع بمقدار 200-500 مللي ثانية.

// Bootstrap first (fast — creates iframe immediately)
const report = powerbi.bootstrap(container, { type: 'report' });

// Load later when token is available
const embedConfig = { /* full config */ };
report.load(embedConfig);

• تنفيذ التخزين المؤقت للتقرير. بمجرد تحميل التقرير، يحتفظ به إطار iframe في الذاكرة. إذا انتقل المستخدم بعيدًا ثم عاد، فأعد استخدام إطار iframe الموجود بدلاً من إعادة التضمين. يؤدي هذا إلى تقليل وقت التحميل تمامًا لزيارات العودة خلال نفس الجلسة.

أداء الواجهة الخلفية

• رموز التضمين في ذاكرة التخزين المؤقت. الرموز المميزة للتضمين صالحة طوال عمرها الافتراضي (ساعة واحدة افتراضية). قم بتخزينها مؤقتًا في Redis أو في الذاكرة وإعادة استخدامها عبر الطلبات لنفس مجموعة التقرير/الهوية.
• إنشاء الرموز المميزة المجمعة. إذا كانت لوحة معلومات المستخدم تحتوي على تقارير مضمنة متعددة، فقم بإنشاء جميع الرموز المميزة للتضمين في استدعاء واحد لواجهة برمجة التطبيقات (API) باستخدام إمكانية الموارد المتعددة لنقطة نهاية GenerateToken.
• مراقبة حدود معدل API. لدى Power BI REST API حدود للمعدل لكل خدمة رئيسية. مراقبة 429 استجابة وتنفيذ التراجع الأسي. بالنسبة للتطبيقات واسعة النطاق، قم بتوزيع الحمل عبر مبادئ الخدمة المتعددة.

تصميم التقرير للمضمنة

يجب أن تعطي التقارير المصممة للاستهلاك المضمن الأولوية للأداء على التعقيد البصري:

• الحد من العناصر المرئية إلى 8-12 لكل صفحة (كل عنصر مرئي ينشئ استعلامًا منفصلاً)
• استخدم وضع الاستيراد بدلاً من DirectQuery عندما يكون ذلك ممكنًا (10-100x أسرع)
• تجميع البيانات مسبقًا بالتفاصيل المناسبة
• تجنب مقاييس DAX المعقدة على الصفحات المقصودة (احفظها للاطلاع على تفاصيل التصفح)
• استخدم الإشارات المرجعية لطرق العرض المحسوبة مسبقًا بدلاً من الحسابات الديناميكية
• اختبار أوقات تحميل التقرير على مستوى التزامن المتوقع لديك، وليس فقط لمستخدم واحد

بالنسبة للمؤسسات التي تطبق التحليلات المضمنة، توفر ECOSIRE خدمات الاستشارات والتطوير المعماري لضمان الأداء الأمثل من اليوم الأول.

---

الاعتبارات الأمنية للمضمنة

أمان الرمز المميز

تمنح الرموز المميزة للتضمين حق الوصول إلى محتوى Power BI. التعامل معها كأوراق اعتماد حساسة:

• لا تكشف مطلقًا عن الرموز المميزة للتضمين في التعليمات البرمجية المصدر من جانب العميل أو معلمات URL
• إنشاء الرموز المميزة من جانب الخادم وتسليمها من خلال نقاط نهاية API المصادق عليها
• استخدم أقصر عمر عملي للرمز المميز (الساعة الافتراضية هي ساعة واحدة معقولة لمعظم التطبيقات)
• تنفيذ منطق تحديث الرمز المميز بدلاً من إنشاء الرموز المميزة طويلة الأمد
• مراقبة أنماط إنشاء الرمز المميز بحثًا عن الحالات الشاذة (الحجم غير المعتاد، ومعرفات التقارير غير المتوقعة)

التحقق من عزل المستأجر

بالنسبة للتطبيقات متعددة المستأجرين، تحقق من صحة عزل المستأجر بشكل مستمر:

• الاختبارات الآلية التي تنشئ الرموز المميزة للمستأجر أ وتتحقق من عدم إمكانية الوصول إلى بيانات المستأجر ب
• تسجيل الاستعلام للكشف عن محاولات الوصول إلى بيانات المستأجرين
• عمليات تدقيق منتظمة لتكوين RLS (يمكن تعديل أدوار RLS في Power BI Desktop وإضعافها عن طريق الخطأ)
• التنبيه على أخطاء مرشح RLS (والتي قد تشير إلى التكوين الخاطئ)

أمن الشبكات

• تقييد الوصول إلى Power BI REST API إلى نطاقات IP المعروفة باستخدام الوصول المشروط لـ Azure AD
• استخدم نقاط النهاية الخاصة لاتصالات البوابة بمصادر البيانات المحلية
• تمكين تسجيل التدقيق في بوابة إدارة Power BI لتتبع جميع استدعاءات واجهة برمجة التطبيقات (API) وتضمين إنشاء الرمز المميز
• قم بتنفيذ رؤوس سياسة أمان المحتوى لتقييد تضمين iframe في مجال التطبيق الخاص بك

---

الأسئلة الشائعة

ما هي تكلفة Power BI Embedded لتطبيق SaaS الذي يضم 10000 مستخدم؟

تعتمد التكلفة على المستخدمين المتزامنين، وليس إجمالي المستخدمين. إذا كان 5% من مستخدميك البالغ عددهم 10000 مستخدمًا متزامنين في فترة الذروة (500 مستخدم متزامن)، فستحتاج إلى سعة F32 تقريبًا بتكلفة 8200 دولار أمريكي شهريًا (الدفع أولاً بأول). مع الحجز (التزام لمدة عام واحد)، ينخفض ​​هذا المبلغ إلى حوالي 5500 دولار شهريًا. يمكن أن تكون التكلفة الفعلية أعلى أو أقل اعتمادًا على مدى تعقيد التقرير وحجم مجموعة البيانات وأنماط الاستخدام. ابدأ بـ F8 كإصدار تجريبي، ثم قم بإجراء اختبار التحميل بتزامن واقعي، ثم قم بالقياس بناءً على القياسات الفعلية.

هل يمكنني استخدام Power BI Embedded بدون Azure؟

يتطلب Power BI Embedded Azure AD للمصادقة وتوفير سعة النسيج/المضمنة من خلال Azure. يمكن استضافة تطبيقك نفسه في أي مكان (AWS، وGCP، محليًا)، ولكن يجب أن تكون موارد Power BI في Azure. يجب أن يكون حساب المستخدم الرئيسي أو الرئيسي للخدمة موجودًا في Azure AD، ويجب أن تكون السعة أحد موارد Azure. بالنسبة للمؤسسات التي ليس لديها بصمة Azure موجودة، يضيف الإعداد ما يقرب من 2-4 ساعات من عمل تكوين Azure والحد الأدنى من إدارة Azure المستمرة بما يتجاوز السعة نفسها.

ما الفرق بين وحدات SKU Power BI Embedded A ووحدات SKU EM ووحدات SKU Fabric F؟

كانت وحدات SKU هي سعة Power BI Embedded الأصلية، والتي تم توفيرها من خلال Azure. كانت وحدات SKU الخاصة بـ EM خيار ترخيص للتضمين الداخلي في Office 365. وقد تم استبدال كليهما بوحدات SKU الخاصة بـ Fabric F، والتي توفر نموذج سعة موحدًا لجميع أحمال عمل Power BI وFabric. توفر وحدات SKU F إعداد فواتير بالثانية وإمكانية الإيقاف المؤقت/الاستئناف وبنية تسعير أبسط. بالنسبة للتطبيقات الجديدة، استخدم F SKU حصريًا. يجب على عملاء SKU الحاليين التخطيط للانتقال إلى F SKU للحصول على أسعار وقدرات أفضل.

هل يمكن للمستخدمين تصدير البيانات من التقارير المضمنة؟

نعم، ولكن يمكنك التحكم في ذلك من خلال إعدادات التضمين. تتيح لك JavaScript SDK تمكين أو تعطيل إمكانات التصدير (التصدير إلى Excel وPDF وPowerPoint) لكل تقرير. يمكنك أيضًا تنفيذ وظيفة التصدير المخصصة من خلال واجهة برمجة تطبيقات التصدير، والتي تمنحك المزيد من التحكم في التنسيق والمرشحات المطبقة وتسجيل التدقيق. بالنسبة للبيانات الحساسة، قم بتعطيل التصدير المضمن وتوفير آلية التصدير الخاصة بك والتي تطبق فحوصات ترخيص إضافية وعلامات مائية.

كيف أتعامل مع تطوير التقرير في سيناريو مضمن؟

يتبع تطوير التقرير سير عمل Power BI القياسي: إنشاء التقارير في Power BI Desktop، ونشرها في مساحة عمل التطوير، واختبارها باستخدام نماذج الرموز المميزة، والترقية إلى الإنتاج من خلال مسارات النشر. يتمثل الاختلاف الرئيسي في أن التقارير المضمنة تحتاج إلى اختبارات إضافية لسلوك RLS والأداء في ظل التزامن والتخطيط سريع الاستجابة عبر أحجام الشاشات والتفاعل مع واجهة مستخدم التطبيق الخاص بك. قم بإنشاء خط أنابيب CI/CD يتضمن التحقق الآلي من RLS واختبار انحدار الأداء كجزء من كل عملية نشر للتقرير.