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

  • Статья

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

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

  • Отчет Power BI
  • Внедрение приложения организации
  • Использование .NET 5.0
  • С библиотекой Microsoft.Identity.Web (эта библиотека также поддерживается в .NET Core)

Примечание.

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

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

  • Лицензия Power BI Pro или Premium на пользователя (PPU).

    Примечание.

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

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

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

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

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

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

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

Ресурсы

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

  • 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 и основным доменным именем.

Примечание.

Чтобы внедрить содержимое для пользователя в другой клиент (гостевой пользователь), необходимо настроить 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 -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. Включение проверки подлинности на стороне сервера

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

Файл Использование
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 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. Получение значений параметров внедрения.

Примечание.

В предыдущем фрагменте 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 библиотекой, и используется для получения маркеров доступа из идентификатора Microsoft Entra.

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

Примечание.

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

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

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

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

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

Создайте 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