Руководство. Внедрение отчета Power BI в приложение для клиентов

  • Статья

В этом руководстве вы узнаете, как внедрить отчет Power BI в приложение .NET 5.0 в рамках решения внедрения для клиентов (также известного как решение app-owns-data). В решении для внедрения для клиентов пользователи приложения не должны входить в Power BI или иметь лицензию Power BI.

В этом руководстве описано, как внедрить:

  • Отчет Power BI.
  • В приложении внедрения для клиентов.
  • С помощью субъекта-службы.
  • С помощью .NET 5.0.
  • С библиотекой Microsoft.Identity.Web (эта библиотека также поддерживается в .NET Core).

Примечание.

Полное решение, используемое в этом руководстве, доступно в репозитории GitHub DOTNET5-AppOwnsData-Tutorial .

Необходимые компоненты

Ресурсы

В этом руководстве вы используете следующее:

  • API REST Отчетов Power BI для внедрения URL-адреса и получения маркера внедрения.

  • Библиотека веб-проверки подлинности Microsoft Identity Web.

  • API клиента аналитики Power BI embedded analytics для внедрения отчета.

Способ

Чтобы внедрить содержимое Power BI в решение для внедрения для клиентов, выполните следующие действия.

  1. Настройте приложение Microsoft Entra и субъект-службу.

  2. Получение значений параметров внедрения.

  3. Добавьте необходимые пакеты NuGet.

  4. Включите проверку подлинности на стороне сервера.

  5. Создайте клиентскую сторону приложения.

  6. Запустите приложение.

Шаг 1. Настройка приложения Microsoft Entra и субъекта-службы

В этом руководстве вы используете субъект-службу для проверки подлинности веб-приложения с идентификатором Microsoft Entra. Кроме того, вам потребуется приложение Microsoft Entra, которое позволяет создать токен Microsoft Entra. С помощью маркера Microsoft Entra веб-приложение может вызывать REST API Power BI и внедрять элементы Power BI, такие как отчеты, панели мониторинга и плитки.

Следуйте инструкциям субъекта-службы, чтобы создать приложение Microsoft Entra и включить субъект-службу приложения для работы с содержимым Power BI.

Шаг 2. Получение значений параметров внедрения

Чтобы внедрить отчет, вам потребуется следующее:

Идентификатор домена и клиента

Если вы не знаете идентификатор домена или клиента, ознакомьтесь с идентификатором клиента Microsoft Entra и основным доменным именем.

Примечание.

Чтобы внедрить содержимое для пользователя в другой клиент (гостевой пользователь), необходимо настроить authorityUri параметр.

Client ID

Чтобы получить ИДЕНТИФИКАТОР клиента (также известный как идентификатор приложения), выполните следующие действия:

  1. Войдите в Microsoft Azure.

  2. Найдите Регистрация приложений и выберите ссылку Регистрация приложений.

  3. Выберите приложение Microsoft Entra, которое вы используете для внедрения содержимого Power BI.

  4. Из раздела "Обзор" скопируйте ИДЕНТИФИКАТОР идентификатора приложения (клиента).

Секрет клиента

Чтобы получить секрет клиента, выполните приведенные ниже действия.

  1. Войдите в Microsoft Azure.

  2. Найдите Регистрация приложений и выберите ссылку Регистрация приложений.

  3. Выберите приложение Microsoft Entra, которое вы используете для внедрения содержимого Power BI.

  4. В разделе Управление выберите Сертификаты и секреты.

  5. В разделе Секреты клиента выберите Новый секрет клиента.

  6. Во всплывающем окне "Добавление секрета клиента" укажите описание секрета приложения, выберите, когда срок действия секрета приложения истекает, и нажмите кнопку "Добавить".

  7. Из раздела секретов клиента скопируйте строку в столбце Value созданного секрета приложения. Значение секрета клиента — это идентификатор клиента.

Примечание.

Скопируйте значение секрета клиента при первом появлении. После перехода от этой страницы секрет клиента будет скрыт, и вы не сможете получить его значение.

Идентификатор рабочей области

Чтобы получить GUID идентификатора рабочей области, выполните следующие действия.

  1. Выполните вход в службу Power BI.

  2. Откройте отчет, который требуется внедрить.

  3. Скопируйте GUID из URL-адреса. GUID — это число между /groups/ и /reports/.

    A screenshot showing workspace ID GUID in the Power B I service U R L

Примечание.

Чтобы получить идентификатор рабочей области программным способом , используйте API получения групп .

Код отчета

Чтобы получить guid идентификатора отчета, выполните следующие действия.

  1. Выполните вход в службу Power BI.

  2. Откройте отчет, который требуется внедрить.

  3. Скопируйте GUID из URL-адреса. GUID — это число между /reports/ и /ReportSection.

    A screenshot showing report ID GUID in the Power B I service U R L

Примечание.

Чтобы получить идентификатор отчета программным способом , используйте API получения отчетов в группе .

Шаг 3. Добавление необходимых пакетов NuGet

Прежде чем начать, необходимо добавить Microsoft.Identity.Webпакеты NuGet в Microsoft.PowerBI.Api приложение.

Добавьте необходимые пакеты NuGet в приложение:

  • В VS Code откройте терминал и введите следующий код.

  • В Visual Studio перейдите в раздел Tools>NuGet диспетчер пакетов> диспетчер пакетов Console и введите следующий код.

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

Шаг 4. Включение проверки подлинности на стороне сервера

Включите проверку подлинности на стороне сервера в приложении, создав или изменив файлы в следующей таблице.

Файл Использование
Startup.cs Инициализация Microsoft.Identity.Web службы проверки подлинности
appsettings.json Настройка сведений о проверке подлинности
PowerBiServiceApi.cs Получение маркера Microsoft Entra и внедрение метаданных
HomeController.cs Передача данных внедрения в виде модели в представление

Настройка файла запуска для поддержки Microsoft.Identity.Web

Измените код в Startup.cs , чтобы правильно инициализировать службу проверки подлинности, предоставляемую Microsoft.Identity.Web.

Добавьте следующий код в файл Startup.cs приложения.

Примечание.

Код выполняет ConfigureServices несколько важных действий.

  1. AddMicrosoftWebAppCallsWebApi Вызов для настройки библиотеки проверки подлинности Майкрософт для получения маркеров доступа (токены Microsoft Entra).
  2. AddInMemoryTokenCaches Вызов для настройки кэша маркеров, который библиотека проверки подлинности Майкрософт использует для кэширования маркеров доступа и маркеров обновления за кулисами.
  3. services.AddScoped(typeof(PowerBiServiceApi)) Вызов для настройки PowerBiServiceApi класса в качестве класса службы, который можно добавить в другие классы с помощью внедрения зависимостей.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc.Authorization;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AppOwnsData.Services;

namespace AppOwnsData
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services) {

    services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
            .EnableTokenAcquisitionToCallDownstreamApi()
            .AddInMemoryTokenCaches();

            services.AddScoped(typeof(PowerBiServiceApi));

            services.AddControllersWithViews(options => {
                var policy = new AuthorizationPolicyBuilder()
                    .RequireAuthenticatedUser()
                    .Build();
                options.Filters.Add(new AuthorizeFilter(policy));
            });
            services.AddRazorPages()
                    .AddMicrosoftIdentityUI();
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");
                // The default HSTS value is 30 days. You might want to change this for production scenarios. See https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }
            app.UseHttpsRedirection();
            app.UseStaticFiles();

            app.UseRouting();

            app.UseAuthentication();
            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                    name: "default",
                    pattern: "{controller=Home}/{action=Index}/{id?}");
                endpoints.MapRazorPages();
            });
        }
    }
}

Создание файла сведений о проверке подлинности

В этом руководстве файл appsettings.json содержит конфиденциальную информацию, например идентификатор клиента и секрет клиента. По соображениям безопасности не рекомендуется хранить эти сведения в файле параметров. При внедрении в приложение рассмотрите более безопасный инструмент, например Azure Key Vault, для защиты конфиденциальной информации.

  1. В проекте создайте файл и назовите его appsettings.json.

  2. Добавьте следующий код в appsettings.json:

    {
 "AzureAd": {
   "Instance": "https://login.microsoftonline.com/",
   "Domain": "yourtenant.onMicrosoft.com",
   "TenantId": "",
   "ClientId": "",
   "ClientSecret": "",
   "CallbackPath": "/signin-oidc",
   "SignedOutCallbackPath": "/signout-callback-oidc"
 },
 "PowerBi": {
   "ServiceRootUrl": "https://api.powerbi.com/"
 },
 "Logging": {
   "LogLevel": {
     "Default": "Information",
     "Microsoft": "Warning",
     "Microsoft.Hosting.Lifetime": "Information"
   }
 },
"AllowedHosts": "*"
}

  3. Заполните значения параметров внедрения, полученные из шага 2. Получение значений параметров внедрения.

Примечание.

В приведенном выше коде PowerBi:ServiceRootUrl параметр добавляется в качестве настраиваемого значения конфигурации для отслеживания базового URL-адреса в служба Power BI. При программе для служба Power BI в общедоступном облаке Майкрософт URL-адрес.https://api.powerbi.com/ Однако корневой URL-адрес для служба Power BI отличается в других облаках, таких как облако для государственных организаций. Таким образом, настраиваемое значение конфигурации хранится в качестве значения конфигурации проекта, поэтому его можно изменить по мере необходимости.

Получение маркера доступа Microsoft Entra и вызов служба Power BI

Чтобы внедрить содержимое Power BI, например отчеты и панели мониторинга, приложение должно получить маркер Microsoft Entra. Чтобы получить маркер, требуется объект конфигурации.

Код в этом разделе использует шаблон внедрения зависимостей .NET Core. Если классу нужно использовать службу, можно добавить параметр конструктора для этой службы. Среда выполнения .NET Core заботится о передаче экземпляра службы во время выполнения. В этом случае конструктор внедряет экземпляр службы конфигурации .NET Core с помощью IConfiguration параметра, который используется для получения PowerBi:ServiceRootUrl значения конфигурации из appsettings.json. Параметр ITokenAcquisition , который называется tokenAcquisition, содержит ссылку на службу проверки подлинности Майкрософт, предоставляемую библиотекой Microsoft.Identity.Web . Этот ITokenAcquisition параметр используется для получения маркеров доступа из идентификатора Microsoft Entra.

Поле RequiredScopes содержит строковый массив, содержащий набор делегированных разрешений, поддерживаемых API служба Power BI. При вызове приложения через сеть для получения маркера Microsoft Entra он передает этот набор делегированных разрешений, чтобы идентификатор Microsoft Entra был включен в маркер доступа, который он возвращает.

Примечание.

Убедитесь, что приложение Microsoft Entra настроено с помощью область, необходимых веб-приложению. Дополнительные сведения см. в разделе "Изменение разрешений приложения Microsoft Entra".

  1. В проекте приложения создайте папку с заголовком "Службы".

  2. В папке "Службы" создайте файл с названием PowerBiServiceApi.cs.

  3. Добавьте следующий код в PowerBiServiceApi.cs.

    using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;
using Microsoft.Identity.Web;
using Microsoft.Rest;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Newtonsoft.Json;

namespace AppOwnsData.Services {

    // A view model class to pass the data needed to embed a single report
    public class EmbeddedReportViewModel {
        public string Id;
        public string Name;
        public string EmbedUrl;
        public string Token;
    }

    public class PowerBiServiceApi {

        private ITokenAcquisition tokenAcquisition { get; }
        private string urlPowerBiServiceApiRoot { get; }

        public PowerBiServiceApi(IConfiguration configuration, ITokenAcquisition tokenAcquisition) {
            this.urlPowerBiServiceApiRoot = configuration["PowerBi:ServiceRootUrl"];
            this.tokenAcquisition = tokenAcquisition;
        }

        public const string powerbiApiDefaultScope = "https://analysis.windows.net/powerbi/api/.default";

        // A method to get the Azure AD token (also known as 'access token')
        public string GetAccessToken() {
            return this.tokenAcquisition.GetAccessTokenForAppAsync(powerbiApiDefaultScope).Result;
        }

        public PowerBIClient GetPowerBiClient() {
            var tokenCredentials = new TokenCredentials(GetAccessToken(), "Bearer");
            return new PowerBIClient(new Uri(urlPowerBiServiceApiRoot), tokenCredentials);
        }

        public async Task<EmbeddedReportViewModel> GetReport(Guid WorkspaceId, Guid ReportId) {

            PowerBIClient pbiClient = GetPowerBiClient();

            // Call the Power BI service API to get the embedding data.
            var report = await pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

            // Generate a read-only embed token for the report.
            var datasetId = report.DatasetId;
            var tokenRequest = new GenerateTokenRequest(TokenAccessLevel.View, datasetId);
            var embedTokenResponse = await pbiClient.Reports.GenerateTokenAsync(WorkspaceId, ReportId, tokenRequest);
            var embedToken = embedTokenResponse.Token;

            // Return the report embedded data to caller.
            return new EmbeddedReportViewModel {
                Id = report.Id.ToString(),
                EmbedUrl = report.EmbedUrl,
                Name = report.Name,
                Token = embedToken
            };
        }

    }
}

Изменение файла HomeController.cs

В этом примере кода для изменения файла HomeController.cs используется внедрение зависимостей. Выполнив предыдущий шаг, вы настроили PowerBiServiceApi класс как службу, вызвав services.AddScoped метод ConfigureServices . С помощью этого кода в конструктор добавляется PowerBiServiceApi параметр, а среда выполнения .NET Core создает PowerBiServiceApi экземпляр и передает его конструктору.

В папке Controllers откройте файл HomeController.cs и добавьте в него следующий код:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using AppOwnsData.Models;
using AppOwnsData.Services;

namespace AppOwnsData.Controllers
{
    [Authorize]
    public class HomeController : Controller
    {
        private PowerBiServiceApi powerBiServiceApi;

        public HomeController(PowerBiServiceApi powerBiServiceApi)
        {
            this.powerBiServiceApi = powerBiServiceApi;
        }

        [AllowAnonymous]
        public IActionResult Index()
        {
            return View();
        }

        public async Task<IActionResult> Embed() {

            // Replace these two GUIDs with the workspace ID and report ID you recorded earlier.
            Guid workspaceId = new Guid("11111111-1111-1111-1111-111111111111");
            Guid reportId = new Guid("22222222-2222-2222-2222-222222222222");

            var viewModel = await powerBiServiceApi.GetReport(workspaceId, reportId);

            return View(viewModel);
        }

        [AllowAnonymous]
        [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
        public IActionResult Error()
        {
            return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
        }
    }
}

Шаг 5. Создание клиентской стороны приложения

Для реализации на стороне клиента необходимо создать или изменить файлы, перечисленные в следующей таблице:

Файл Использование
embed.js Содержит клиентский код JavaScript
Embed.cshtml Содержит объектную модель документа приложения (DOM) и DIV для внедрения отчета

Создание контейнера для внедренного отчета

В этом руководстве вы создадите файл Embedded.cshtml , который содержит элемент, который является div контейнером для внедренного отчета и тремя скриптами.

  1. В папке View/Home создайте файл с именем Embed.cshtml.

  2. Добавьте следующий код в файл Embed.cshtml .

    @model AppOwnsData.Services.EmbeddedReportViewModel;

<div id="embed-container" style="height:800px;"></div>

@section Scripts {

    <!-- powerbi.min.js is the JavaScript file that loads the client-side Power BI JavaScript API library.
    Make sure that you're working with the latest library version.
    You can check the latest library available in https://cdnjs.com/libraries/powerbi-client -->
    <script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.18.0/dist/powerbi.min.js"></script>

    <!-- This script creates a JavaScript object named viewModel which is accessible to the JavaScript code in embed.js. -->
    <script> 
        var viewModel = {
            reportId: "@Model.Id",
            embedUrl: "@Model.EmbedUrl",
            token: "@Model.Token"
        }; 
    </script>

    <!-- This script specifies the location of the embed.js file -->
    <script src="~/js/embed.js"></script>
}

Добавление JavaScript на стороне клиента для внедрения отчета

Чтобы внедрить содержимое Power BI, необходимо создать объект конфигурации. Дополнительные сведения о создании объекта конфигурации см. в статье "Внедрение отчета".

В этом руководстве вы создадите файл JavaScript с именем embed.js с объектом конфигурации для внедрения отчета, использующего переменную models.

Можно инициализировать models с помощью вызова window['powerbi-client'].models. Переменная models используется для задания значений конфигурации, таких как models.Permissions.All, models.TokenType.Aadи models.ViewMode.View.

Функция powerbi.embed использует models объект конфигурации для внедрения отчета.

  1. В папке wwwroot/js создайте файл с именем embed.js.

  2. Добавьте следующий код в файл embed.js .

    $(function () {

    // 1 - Get DOM object for the div that's the report container.
    var reportContainer = document.getElementById("embed-container");

    // 2 - Get the report embedding data from the view model.
    var reportId = window.viewModel.reportId;
    var embedUrl = window.viewModel.embedUrl;
    var token = window.viewModel.token

    // 3 - Embed the report by using the Power BI JavaScript API.
    var models = window['powerbi-client'].models;

    var config = {
      type: 'report',
      id: reportId,
      embedUrl: embedUrl,
      accessToken: token,
      permissions: models.Permissions.All,
      tokenType: models.TokenType.Embed,
      viewMode: models.ViewMode.View,
      settings: {
        panes: {
          filters: { expanded: false, visible: true },
          pageNavigation: { visible: false }
        }
      }
    };

    // Embed the report and display it within the div container.
    var report = powerbi.embed(reportContainer, config);

    // 4 - Add logic to resize the embed container on a window resize event.
    var heightBuffer = 12;
    var newHeight = $(window).height() - ($("header").height() + heightBuffer);
    $("#embed-container").height(newHeight);
    $(window).resize(function () {
      var newHeight = $(window).height() - ($("header").height() + heightBuffer);
      $("#embed-container").height(newHeight);
    });

  });

Шаг 6. Запуск приложения

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

Важно!

Если вы использовали бесплатные маркеры пробной версии для разработки, необходимо приобрести емкость для рабочей среды. Пока емкость не будет приобретена, баннер бесплатной пробной версии продолжает отображаться в верхней части внедренного отчета.

Когда приложение будет готово, вы можете переместить внедренное приложение в рабочую среду.

Связанный контент

Токены приложений встроенной аналитики

Перемещение внедренного приложения в рабочую среду

Емкость и номера SKU в встроенной аналитике Power BI

Планирование емкости в встроенной аналитике Power BI