مقدمة

  • 7 دقائق

لتضمين محتوى Power BI في تطبيقك، تحتاج إلى إكمال مهام التطوير التالية.

  1. إضافة مكتبة العميل للتحكم برمجياً في التضمين.
  2. قم بتضمين مكتبة العميل.
  3. إضافة حاوية تضمين.
  4. حقائق تم إنشاؤها من جانب خادم الإخراج.
  5. إعداد كائن تكوين.
  6. تضمين محتوى Power BI.

إضافة مكتبة العميل

استخدم واجهة برمجة تطبيقات عميل Power BI لتضمين محتوى Power BI باستخدام JavaScript أو TypeScript. إنها مكتبة عميل توفر تحكماً برمجياً في تجربة التضمين بأكملها.

تتكون واجهات برمجة التطبيقات من ثلاث حزم:

  • powerbi-client - يتضمن جميع واجهات برمجة التطبيقات التي تتضمن المحتوى، باستثناء تلك الموجودة في مكتبة powerbi-report-authoring (الموضحة أدناه).
  • powerbi-models - يحتوي على نماذج الكائنات. يحتوي كل نموذج على واجهة TypeScript وتعريف مخطط JSON ووظيفة التحقق من الصحة لضمان أن كائناً معيناً هو نموذج صالح.
  • powerbi-report-authoring - ملحق لإنشاء مرئيات وتخصيصها، وتأليف تقرير Power BI بعد تحميله. كما يسمح لتطبيقك بتحرير تقارير Power BI المضمنة برمجياً.

يمكنك تثبيت مكتبة واجهة برمجة تطبيقات عميل Power BI باستخدام NuGet أو npm.

لمزيد من المعلومات، راجع ما هو ملعب تحليلات Power BI المضمن?.

قم بتضمين مكتبة العميل

يجب أن يتضمن script تطبيقك عنصراً لمصدر مكتبة العميل.

<script src="/powerbi-client/dist/powerbi.js"></script>

من الممكن أيضاً الحصول على مكتبة العميل من شبكة تسليم المحتوى (CDN). على سبيل المثال، راجع JSDelivr powerbi-client.

<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.19.1/dist/powerbi.min.js"></script>

عندما يتم تضمينها مباشرة، يتم عرض مكتبة العميل على أنها عميل powerbi-client عالمي. هناك أيضاً اسم عالمي آخر يسمى powerbi، وهو مثال على خدمة Power BI.

إضافة حاوية تضمين

يجب أن يتضمن div التطبيق عنصراً يعمل كحاوية تضمين.

<div id="embedContainer"></div>

يقوم التطبيق بتضمين محتوى Power BI في العنصر div، واستضافة المحتوى داخل عنصر iframe. يفصل العنصر iframe بين التطبيق والمحتوى المضمن، مع التأكد من أمان البيانات. تتواصل واجهات برمجة تطبيقات العميل دائماً بشكل آمن بين التطبيق والمحتوى المضمن.

شاهد الفيديو التالي الذي يوضح كيفية عمل مكتبة العميل.

حقائق تم إنشاؤها من جانب خادم الإخراج

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

تلميح

لمعرفة كيفية الحصول على رموز الوصول المميزة واسترداد خصائص عناصر Power BI، اعمل من خلال أذونات الإعداد لتضمين وحدة محتوى Power BI.

يحتوي العنصر التالي script على ثلاثة متغيرات. يقوم accessToken المتغير بتخزين رمز الوصول المميز الذي تم إنشاؤه من جانب الخادم. تخزن reports المتغيرات تمثيلات datatsets JSON للتحف القابلة للتضمين. في هذا المثال، تكون أنواع البيانات الاصطناعية عبارة عن تقارير ومجموعات بيانات. وعلى وجه التحديد، تخزن المتغيرات معرف الأداة الفنية وتضمين خصائص عنوان URL التي يجب أن تكون متاحة من جانب العميل لدعم التضمين. كما يتضمن خاصية الاسم حتى يتمكن التطبيق من تقديم أسماء البيانات الاصطناعية للمستخدم بطريقة سهلة الاستخدام، كما هو الحال في القائمة.

<script>
    var accessToken = "@Model.AccessToken";
    var reports = @Html.Raw(Model.ReportsJson)
    var datasets = @Html.Raw(Model.DatasetsJson)
</script>

إعداد كائن تكوين

يجب على تطبيقك إنشاء كائن تكوين لتوفير كافة المعلومات المطلوبة لتضمين محتوى Power BI. يجب عليك تعيين الخصائص الخمس التالية لكائن التكوين:

  • tokenType - إما models.TokenType.Aad عند استخدام سيناريو For your organization (الرمز المميز للوصول هو رمز Microsoft Azure Active Directory)، أو models.TokenType.Embed عند استخدام سيناريو For your customers (رمز الوصول هو رمز مميز للتضمين).
  • accessToken- تم إنشاء رمز الوصول من جانب الخادم.
  • type- إما تقرير( Power BI أو تقرير مرقم) أو مرئي (لتقرير Power BI) أو لوحة معلومات (للوحة معلومات) أو تجانب (لتجانب لوحة معلومات) أو qna (لتجربة Q&A). تصف الوحدتان 2 و3 كيفية تضمين كل نوع من أنواع محتوى Power BI.
  • id - معرف الأداة Power BI.
  • embedUrl - عنوان URL لتضمين الأداة Power BI. يصبح عنوان URL هذا مصدر العنصر الذي iframe يستضيف الأداة المضمنة. وعلى وجه التحديد، تقوم واجهة برمجة التطبيقات بتعيين عنوان URL لسمة src العنصرiframe.

توضح التعليمة البرمجية التالية كيفية إنشاء كائن تكوين لتضمين تقرير Power BI باستخدام السيناريو For your customers. models هو مرجع إلى نماذج مكتبة العميل، التي تحتوي على أنواع تعداد مفيدة (enums).

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

هناك خصائص تكوين إضافية خاصة بالمحتوى يمكنك تعيينها. يتم وصفها في الوحدتين 2 و 3.

تضمين محتوى Power BI

استخدم الوظيفة powerbi.embed(embedContainer, config) لتضمين محتوى Power BI.

توضح التعليمة البرمجية التالية كيفية تضمين تقرير Power BI. يخزن embedContainer المتغير مرجعاً إلى حاوية التضمين div(العنصر)، بينما يخزن المتغير كائن التكوينconfig الذي تم إعداده لتقرير Power BI معين. تقوم العبارة الأخيرة بالتضمين عن طريق المرور في حاوية التضمين وكائن التكوين. يخزن report المتغير مرجعاً إلى التقرير المضمن.

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Get a reference to the embedding container.
let embedContainer = $('#embedContainer')[0];

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

// Embed the report in the embedding container.
report = powerbi.embed(embedContainer, config);

في الوحدة التالية، ستتعرف على كيفية تضمين تقرير Power BI، وهو نوع محتوى Power BI الأكثر شيوعاً المضمن.