Partager via

Tutoriel : Incorporer un rapport Power BI dans une application pour vos clients

  • Article

Dans ce tutoriel, vous allez apprendre à incorporer un rapport Power BI dans une application .NET 5.0 dans le cadre de la solution Incorporer pour vos clients (également appelée L’application possède les données). Dans une solution Incorporer pour vos clients, les utilisateurs de votre application n’ont pas besoin de se connecter à Power BI ni de disposer d’une licence Power BI.

Dans ce tutoriel, vous apprenez à incorporer :

  • Un rapport Power BI.
  • Dans une application Incorporer pour vos clients.
  • En utilisant un principal de service.
  • En utilisant .NET 5.0.
  • Avec la bibliothèque Microsoft.Identity.Web (cette bibliothèque est également prise en charge dans .NET Core).

Notes

La solution complète utilisée dans ce tutoriel est disponible dans le dépôt GitHub DOTNET5-AppOwnsData-Tutorial.

Prérequis

Ressources

Dans ce tutoriel, vous utilisez :

Méthode

Pour incorporer du contenu Power BI dans une solution Incorporer pour vos clients, effectuez les étapes suivantes :

  1. Configurez votre application Microsoft Entra et votre principal de service.

  2. Obtenez les valeurs des paramètres d’incorporation.

  3. Ajoutez les packages NuGet nécessaires.

  4. Activer l’authentification côté serveur

  5. Générer le côté client de votre application

  6. Exécutez votre application.

Étape 1 : Configurez votre application Microsoft Entra et votre principal de service

Dans ce tutoriel, vous utilisez un principal de service pour authentifier votre application web sur Microsoft Entra ID. Vous avez également besoin d’une application Microsoft Entra, qui permet de générer un jeton Microsoft Entra. En utilisant le jeton Microsoft Entra, votre application web peut appeler des API REST Power BI et incorporer des éléments Power BI tels que des rapports, des tableaux de bord et des vignettes.

Suivez les instructions du principal de service pour créer une application Microsoft Entra et permettre au principal de service des applications d’utiliser votre contenu Power BI.

Étape 2 - Obtenir les valeurs des paramètres d’incorporation

Pour incorporer votre rapport, vous avez besoin des valeurs suivantes :

Domaine et ID de locataire

Si vous ne connaissez pas votre domaine ou votre ID de locataire, consultez Rechercher l’ID de locataire Microsoft Entra et le nom de domaine principal.

Remarque

Pour incorporer du contenu pour un utilisateur sur un autre locataire (un utilisateur invité), vous devez ajuster le paramètre authorityUri.

ID client

Pour obtenir le GUID de l’ID client (également appelé ID d’application), effectuez les étapes suivantes :

  1. Connectez-vous à Microsoft Azure.

  2. Recherchez Inscriptions d’applications, puis sélectionnez le lien Inscriptions d’applications.

  3. Sélectionnez l’application Microsoft Entra que vous utilisez pour incorporer votre contenu Power BI.

  4. Dans la section Vue d’ensemble, copiez le GUID ID d’application (client) .

Clé secrète client

Pour obtenir le secret client, effectuez les étapes suivantes :

  1. Connectez-vous à Microsoft Azure.

  2. Recherchez Inscriptions d’applications, puis sélectionnez le lien Inscriptions d’applications.

  3. Sélectionnez l’application Microsoft Entra que vous utilisez pour incorporer votre contenu Power BI.

  4. Sous Gérer, sélectionnez Certificats et secrets.

  5. Sous Secrets client, sélectionnez Nouveau secret client.

  6. Dans la fenêtre contextuelle Ajouter un secret client, spécifiez une description du secret de votre application, sélectionnez la date d’expiration du secret de l’application, puis sélectionnez Ajouter.

  7. Dans la section Secrets client, copiez la chaîne qui se trouve dans la colonne Valeur du secret de l’application nouvellement créé. La valeur du secret client est votre ID de client.

Notes

Veillez à copier la valeur du secret client dès qu’elle s’affiche pour la première fois. Après avoir quitté cette page, le secret client est masqué et vous ne pouvez pas récupérer sa valeur.

ID de l’espace de travail

Pour obtenir le GUID de l’ID d’espace de travail, effectuez les étapes suivantes :

  1. Connectez-vous au service Power BI.

  2. Ouvrez le rapport que vous voulez incorporer.

  3. Copiez le GUID à partir de l’URL. Le GUID est le nombre qui se trouve entre /groups/ et /reports/ .

    Capture d’écran montrant le GUID de l’ID d’espace de travail dans l’URL de service Power BI

Remarque

Pour obtenir l’ID de l’espace de travail par programmation, utilisez l’API Obtenir des groupes.

ID du rapport

Pour obtenir le GUID de l’ID de rapport, effectuez les étapes suivantes :

  1. Connectez-vous au service Power BI.

  2. Ouvrez le rapport que vous voulez incorporer.

  3. Copiez le GUID à partir de l’URL. Le GUID est le nombre qui se trouve entre /reports/ et /ReportSection/ .

    Capture d’écran montrant le GUID de l’ID de rapport dans l’URL du service Power BI

Notes

Pour obtenir l’ID du rapport par programmation, utilisez l’API Obtenir des rapports dans un groupe.

Étape 3 - Ajouter les packages NuGet nécessaires

Avant de commencer, vous devez ajouter les packages NuGet Microsoft.Identity.Web et Microsoft.PowerBI.Api à votre application.

Ajoutez les packages NuGet nécessaires à votre application :

  • Dans VS Code, ouvrez un terminal et entrez le code suivant.

  • Dans Visual Studio, accédez à Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package, puis saisissez le code suivant.

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

Étape 4 : Activer l’authentification côté serveur

Activez l’authentification côté serveur dans votre application en créant ou en modifiant les fichiers dans le tableau ci-dessous.

Fichier Utilisation
Startup.cs Initialiser le service d’authentification Microsoft.Identity.Web
appsettings.json Configurer les détails de l’authentification
PowerBiServiceApi.cs Obtenir le jeton Microsoft Entra et les métadonnées d’incorporation
HomeController.cs Passer les données d’incorporation en tant que modèle à la vue

Configurer votre fichier de démarrage pour prendre en charge Microsoft.Identity.Web

Modifiez le code dans Startup.cs pour initialiser correctement le service d’authentification fourni par Microsoft.Identity.Web.

Ajoutez le code suivant au fichier Startup.cs de votre application.

Notes

Le code dans ConfigureServices remplit plusieurs fonctions importantes :

  1. L’appel à AddMicrosoftWebAppCallsWebApi configure la bibliothèque d’authentification Microsoft de manière à obtenir des jetons d’accès (jetons Microsoft Entra).
  2. L’appel à AddInMemoryTokenCaches configure un cache de jeton que la bibliothèque d’authentification Microsoft utilise pour mettre en cache les jetons d’accès et les jetons d’actualisation en arrière-plan.
  3. L’appel à services.AddScoped(typeof(PowerBiServiceApi)) configure la classe PowerBiServiceApi en tant que classe de service pouvant être ajoutée à d’autres classes à l’aide de l’injection de dépendances.
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();
            });
        }
    }
}

Créer un fichier de détails d’authentification

Dans ce tutoriel, le fichier appsettings.json contient des informations sensibles telles que l’ID client et le secret client. Pour des raisons de sécurité, nous ne vous recommandons pas de conserver ces informations dans le fichier de paramètres. Quand vous incorporez dans votre application, envisagez un outil plus sécurisé comme Azure Key Vault pour conserver les informations sensibles.

  1. Dans votre projet, créez un fichier et nommez-le appsettings.json.

  2. Ajoutez le code suivant à 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. Renseignez les valeurs des paramètres d’incorporation obtenues à l’Étape 2 : Obtenir les valeurs des paramètres d’incorporation.

Notes

Dans le code précédent, le paramètre PowerBi:ServiceRootUrl est ajouté en tant que valeur de configuration personnalisée pour faire le suivi de l’URL de base jusqu’au service Power BI. Quand vous programmez sur le service Power BI dans le cloud public Microsoft, l’URL est https://api.powerbi.com/. Toutefois, l’URL racine du service Power BI est différente dans d’autres clouds tels que le cloud pour le secteur public. Par conséquent, la valeur de configuration personnalisée est stockée en tant que valeur de configuration de projet. Vous pouvez donc la modifier en fonction des besoins.

Obtenir le jeton d’accès Microsoft Entra et appeler le service Power BI

Pour incorporer du contenu Power BI (comme des rapports et des tableaux de bord), votre application doit obtenir un jeton Microsoft Entra. Pour obtenir le jeton, vous avez besoin d’un objet de configuration.

Le code de cette section utilise le modèle d’injection de dépendances .NET Core. Lorsque votre classe doit utiliser un service, vous pouvez ajouter un paramètre de constructeur pour ce service. Le runtime .NET Core se charge de transmettre l’instance de service au moment de l’exécution. Dans ce cas, le constructeur injecte une instance du service de configuration .NET Core à l’aide du paramètre IConfiguration, qui est utilisé pour récupérer la valeur de configuration PowerBi:ServiceRootUrl du fichier appsettings.json. Le paramètre ITokenAcquisition, nommé tokenAcquisition, contient une référence au service d’authentification Microsoft fourni par la bibliothèque Microsoft.Identity.Web. Le paramètre ITokenAcquisition est utilisé pour acquérir des jetons d’accès auprès de Microsoft Entra ID.

Le champ RequiredScopes contient un tableau de chaînes comprenant un ensemble d’autorisations déléguées prises en charge par l’API du service Power BI. Quand votre application passe des appels sur le réseau pour acquérir un jeton Microsoft Entra, elle passe cet ensemble d’autorisations déléguées afin que Microsoft Entra ID puisse les inclure dans le jeton d’accès qu’il retourne.

Remarque

Vérifiez que votre application Microsoft Entra est configurée avec les étendues exigées par votre application web. Pour plus d’informations, consultez Modifier les autorisations de votre application Microsoft Entra.

  1. Dans le projet de votre application, créez un dossier intitulé Services.

  2. Dans le dossier Services, créez un fichier intitulé PowerBiServiceApi.cs.

  3. Ajoutez le code suivant à 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
            };
        }

    }
}

Modifier le fichier HomeController.cs

Dans cet exemple de code, vous utilisez l’injection de dépendances pour modifier le fichier HomeController.cs . En suivant une des étapes précédentes, vous avez configuré la classe PowerBiServiceApi en tant que service en appelant services.AddScoped dans la méthode ConfigureServices. Avec ce code, vous ajoutez un paramètre PowerBiServiceApi au constructeur, et le runtime .NET Core crée une instance PowerBiServiceApi et la transmet au constructeur.

Dans le dossier Contrôleurs, ouvrez le fichier HomeController.cs et ajoutez-y l’extrait de code suivant :

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 });
        }
    }
}

Étape 5 : Générer le côté client de votre application

Pour l’implémentation côté client, vous devez créer ou modifier les fichiers énumérés dans le tableau suivant :

Fichier Utilisation
embed.js Contient le code JavaScript côté client
Embed.cshtml Contient le DOM (Document Object Model) de votre application et un DIV pour incorporer le rapport

Créer un conteneur pour votre rapport incorporé

Dans ce tutoriel, vous créez le fichier Embed.cshtml, qui contient un élément div comme conteneur pour votre rapport incorporé et trois scripts.

  1. Dans le dossier Affichage/Accueil, créez un fichier appelé Embed.cshtml.

  2. Ajoutez le code suivant au fichier 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>
}

Ajouter du code JavaScript côté client pour incorporer votre rapport

Pour incorporer du contenu Power BI, vous devez créer un objet de configuration. Pour en savoir plus sur la création de l’objet de configuration, consultez Incorporer un rapport.

Dans ce tutoriel, vous créez un fichier JavaScript nommé embed.js avec un objet de configuration pour incorporer votre rapport en utilisant la variable models.

Vous pouvez initialiser models à l’aide d’un appel à window['powerbi-client'].models. La variable models permet de définir des valeurs de configuration telles que models.Permissions.All, models.TokenType.Aad et models.ViewMode.View.

La fonction powerbi.embed utilise l’objet de configuration models pour incorporer votre rapport.

  1. Dans le dossier wwwroot/js, créez un fichier appelé embed.js.

  2. Ajoutez le code suivant au fichier 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);
    });

  });

Étape 6 : Exécuter votre application

Une fois que vous avez suivi toutes les étapes précédentes, vous êtes prêt à exécuter votre application. Essayez d’exécuter votre application et testez la façon dont votre rapport Power BI est incorporé. Vous pouvez utiliser les API clientes d’analytique incorporée Power BI pour améliorer votre application à l’aide d’API côté client.

Important

Si vous avez utilisé des jetons intégrés d’essai gratuits pour le développement, vous devez acheter une capacité de production. Tant qu’une capacité n’est pas achetée, la bannière Version d’évaluation gratuite continue d’apparaître en haut du rapport intégré.

Quand votre application est prête, vous pouvez faire passer votre application incorporée en production.

Contenu connexe