Введение

  • 7 мин

Чтобы внедрить содержимое Power BI в свое приложение, необходимо выполнить следующие задачи разработки:

  1. добавить клиентскую библиотеку для программного управления внедрением;
  2. подключить клиентскую библиотеку;
  3. добавить контейнер для внедрения;
  4. вывести факты, генерируемые на стороне сервера;
  5. настроить объект конфигурации;
  6. внедрить содержимое Power BI.

Добавление клиентской библиотеки

Используйте клиентские API-интерфейсы для внедрения содержимого Power BI с помощью JavaScript или TypeScript. Они представляют собой клиентскую библиотеку, которая обеспечивает программный контроль всего процесса внедрения.

API-интерфейсы составляют три пакета:

  • powerbi-client — включает все API-интерфейсы, внедряющие содержимое, за исключением API,найденных в библиотеке powerbi-report-authoring .
  • powerbi-models — содержит объектные модели. Каждая модель имеет интерфейс TypeScript, определение схемы JSON и функцию проверки, чтобы гарантировать, что данный объект является допустимой моделью.
  • powerbi-report-authoring — расширение для создания и индивидуальной настройки визуальных элементов и для разработки отчета Power BI после его загрузки. Оно также позволяет приложению редактировать встроенные отчеты Power BI программным способом.

Установить клиентскую API-библиотеку Power BI можно с помощью NuGet или npm.

Дополнительные сведения: Что такое клиентский API встроенной аналитики 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.22.3/dist/powerbi.min.js"></script>

При включении напрямую клиентская библиотека предоставляется как глобальный элемент powerbi-client. Существует другой глобальный элемент, powerbi, который является экземпляром службы Power BI.

Добавление контейнера для внедрения

Приложение должно включать элемент div, который является контейнером для внедрения.

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

Приложение внедряет содержимое Power BI из элемента div и размещает его в элементе iframe. Элемент iframe отделяет в приложении внедренное содержимое, обеспечивая безопасность данных. Клиентские API всегда обеспечивают защищенное взаимодействие между внедренным содержимым и приложением.

Работа клиентской библиотеки показана в следующем видео.

Вывод фактов, генерируемых на стороне сервера

Ваше приложение должно получить маркер доступа, который выводится на стороне клиента. Кроме того, оно должно выводить на стороне клиента ряд свойств артефакта Power BI.

Совет

Сведения о получении маркеров доступа и свойств артефактов Power BI см. в модуле Настройка разрешений на внедрение содержимого Power BI.

Следующий элемент script содержит три переменные. Переменная accessToken содержит маркер доступа, создаваемый на стороне сервера. Переменные reports и datatsets содержат JSON-представления внедряемых артефактов. В нашем примере типами артефактов являются отчеты и наборы данных. В частности, переменные содержат свойства ИД артефакта и URL-адреса внедрения, которые должны быть доступны на стороне клиента для поддержки внедрения. Сюда также входит свойство name, позволяющее приложению выдавать пользователю понятные имена артефактов, как в меню.

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

Настройка объекта конфигурации

Приложение должно создать объект конфигурации, чтобы иметь все необходимые сведения для внедрения содержимого Power BI. Объекту конфигурации нужно задать следующие пять свойств:

  • tokenType — Задайте значение на основе одного из следующих сценариев:
    • Для вашей организации Маркер доступа является маркером Azure AD. Присвойте ему значение models.TokenType.Aad.
    • Для ваших клиентов Маркер доступа является маркером внедрения. Присвойте ему значение models.TokenType.Embed.
  • accessToken — маркер доступа, генерируемый на стороне сервера.
  • type — Задайте для одного из следующих значений. Принципы внедрения каждого типа содержимого Power BI рассматриваются в уроках 2 и 3.
    • Отчет Для отчета Power BI или отчета с разбивкой на страницы.
    • Visual Для визуального элемента отчета Power BI.
    • Панели мониторинга Для панели мониторинга.
    • Плитки Для плитки панели мониторинга.
    • qna Для интерфейса Q&A.
  • id — идентификатор артефакта Power BI.
  • embedUrl — URL-адрес внедрения артефакта Power BI. Этот URL будет источником элемента iframe, в котором размещается внедряемый артефакт. В частности, API назначает URL-адрес атрибуту src элемента iframe.

В следующем коде показано, как создать объект конфигурации для внедрения отчета Power BI с использованием сценария Для клиентов. models — это ссылка на модели клиентской библиотеки, которые содержат полезные типы перечисления (enum).

// 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

Для внедрения содержимого Power BI используется функция powerbi.embed(embedContainer, config).

В следующем коде показано внедрение отчета 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.