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

В этом руководстве объясняется, как внедрить отчет Power BI в приложение .NET 5.0 в рамках внедрения для вашей организации (также известного как пользователь владеет данными). При внедрении решения организации пользователи приложения должны пройти проверку подлинности в Power BI с собственными учетными данными.

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

Предварительные требования

• Лицензия Power BI Pro или Premium Per User (PPU).

  Примечание.

  Встроенное решение для вашей организации не поддерживается на емкостях, основанных на SKU A. Номер SKU можно использовать только для встраивания решений для ваших клиентов.

• Рабочая область Power BI с отчетом.

• Собственный клиент Microsoft Entra.

• Приложение Microsoft Entra.

• Приложение контроллера представления модели .NET Core 5 (MVC).

• Пакет SDK для .NET Core 5 (или более поздней версии).

• Интегрированная среда разработки (IDE). Рекомендуется использовать одну из следующих сред:

  • Визуальная студия.
  • Visual Studio Code (с расширением C#).

Ресурсы

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

• 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

Когда веб-приложение вызывает Power BI, он требует маркера Microsoft Entra для вызова REST API Power BI и внедрения элементов Power BI, таких как отчеты, панели мониторинга или плитки.

Если у вас нет приложения Microsoft Entra, создайте его с помощью инструкций в разделе "Регистрация приложения Microsoft Entra для использования с Power BI".

Чтобы настроить приложение Microsoft Entra, следуйте инструкциям в разделе "Настройка приложения Microsoft Entra".

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

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

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

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

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

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

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

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

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

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

4. Из раздела «Обзор» скопируйте GUID идентификатор приложения (клиента).

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

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

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

   

Идентификатор отчета

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

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

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

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

   

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

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

Добавьте в приложение следующие пакеты NuGet:

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

• В Visual Studio перейдите в Инструменты>диспетчер пакетов NuGet>консоль диспетчера пакетов и введите следующий код.

dotnet add package Microsoft.Identity.Web -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

Если приложение ранее использовалось Microsoft.AspNetCore для проверки подлинности, удалите этот пакет из проекта, введя следующее:

dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI

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

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

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

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

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

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Identity.Web.UI;
using UserOwnsData.Services;

namespace UserOwnsData {

  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(PowerBiServiceApi.RequiredScopes)
        .AddInMemoryTokenCaches();

      services.AddScoped (typeof (PowerBiServiceApi));

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

      mvcBuilder.AddMicrosoftIdentityUI();

      services.AddRazorPages();

    }
  }
}

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

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

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

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

   {
       "AzureAd": {
           "Instance": "https://login.microsoftonline.com/",
           "Domain": "",
           "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. Получение значений параметров внедрения.

   • Domain - Идентификатор домена и клиента
   • TenantId - Идентификатор домена и клиента
   • ClientId - Идентификатор клиента
   • ClientSecret - Секрет клиента

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

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

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

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

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

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

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

   using Microsoft.Identity.Web;
   using Microsoft.PowerBI.Api;
   using Microsoft.PowerBI.Api.Models;
   using Microsoft.Rest;
   using Newtonsoft.Json;
   
   namespace UserOwnsData.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 static readonly string[] RequiredScopes = new string[] {
            "https://analysis.windows.net/powerbi/api/Report.Read.All"
        };
   
       // A method to get the Azure AD token (also known as 'access token')
        public string GetAccessToken() {
            return this.tokenAcquisition.GetAccessTokenForUserAsync(RequiredScopes).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 embedding data
      var report = await pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);
   
      // Return report embedding data to caller
      return new EmbeddedReportViewModel {
       Id = report.Id.ToString(),
       EmbedUrl = report.EmbedUrl,
       Name = report.Name,
       Token = GetAccessToken()
      };
     }
   
    }
   
   }
   

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

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

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

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using UserOwnsData.Models;
using UserOwnsData.Services;

namespace UserOwnsData.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() {
            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. Создание клиентской стороны приложения

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

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

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

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

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

   @model UserOwnsData.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.21.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 div that is report container
       let reportContainer = document.getElementById("embed-container");
   
       // 2 - Get report embedding data from view model
       let reportId = window.viewModel.reportId;
       let embedUrl = window.viewModel.embedUrl;
       let token = window.viewModel.token
   
       // 3 - Embed report using the Power BI JavaScript API.
       let models = window['powerbi-client'].models;
       let config = {
           type: 'report',
           id: reportId,
           embedUrl: embedUrl,
           accessToken: token,
           permissions: models.Permissions.All,
           tokenType: models.TokenType.Aad,
           viewMode: models.ViewMode.View,
           settings: {
               panes: {
                   filters: { expanded: false, visible: true },
                   pageNavigation: { visible: false }
               }
           }
       };
   
       // Embed the report and display it within the div container.
       let report = powerbi.embed(reportContainer, config);
   
       // 4 - Add logic to resize embed container on window resize event
       let heightBuffer = 12;
       let 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