チュートリアル: 組織向けのアプリケーションに Power BI レポートを埋め込む
このチュートリアルでは、組織向けの埋め込み (ユーザー所有データ とも言う) ソリューションの一部として、Power BI レポートを .NET 5.0 アプリケーションに埋め込む方法について学習します。 ''組織向けの埋め込み'' ソリューションでは、アプリ ユーザーは独自の資格情報を使用して Power BI に対して認証を行う必要があります。
このチュートリアルでは、埋め込み方法を学習します。
- Power BI レポート
- "組織向けの埋め込み" アプリで
- .NET 5.0 を使用する
Microsoft.Identity.Webライブラリを使用する (このライブラリは .Net Core でもサポートされています)
注意
このチュートリアルで使用される完全なソリューションは、DOTNET5-UserOwnsData-Tutorial GitHub リポジトリから入手できます。
必須コンポーネント
Power BI Pro または Premium Per User (PPU) のライセンス。
注意
''組織向けの埋め込み'' は、A SKU に基づく容量ではサポートされていません。 A SKU を使用できるのは、''顧客向けの埋め込み'' ソリューションでのみです。
レポートを含む Power BI ワークスペース。
独自の Microsoft Entra テナント。
.NET Core 5 モデル ビュー コントローラー (MVC) アプリ。
.NET Core 5 SDK (またはそれ以降)。
統合開発環境 (IDE)。 次のいずれかの環境を使用することをお勧めします。
リソース
このチュートリアルでは、次のものを使います。
- Power BI REST Reports API - URL を埋め込み、埋め込みトークンを取得できます。
- Microsoft Identity Web 認証ライブラリ。
- Power BI 埋め込み分析のクライアント API - レポートを埋め込むことができます。
Method
''組織向けの埋め込み'' ソリューションに Power BI コンテンツを埋め込むには、これらの手順に従います。
- Microsoft Entra アプリを構成する
- 埋め込みパラメーター値を取得する
- 必要な NuGet パッケージを追加します
- サーバー側の認証を有効にする
- アプリのクライアント側をビルドする
- アプリケーションを実行します
手順 1 - Microsoft Entra アプリを構成する
Web アプリで Power BI を呼び出す場合、Power BI REST API を呼び出し、Power BI 項目 (レポート、ダッシュボード、タイルなど) を埋め込むために Microsoft Entra トークンが必要です。
Microsoft Entra アプリをお持ちでない場合は、「Power BI で使用する Microsoft Entra アプリケーションを登録する」の手順に従って作成してください。
Microsoft Entra アプリを構成するには、「Microsoft Entra アプリを構成する」の手順に従ってください。
手順 2 - 埋め込みパラメーター値を取得する
レポートを埋め込むには、次の値が必要です。
ドメインとテナント ID
ドメインやテナント ID が不明な場合は、Microsoft Entra テナント ID とプライマリ ドメイン名の検索に関する説明を参照してください。
Note
別のテナントのユーザー用にコンテンツを埋め込むには (ゲスト ユーザー)、authorityUri パラメーターを調整する必要があります。
クライアント ID
クライアント ID GUID ("アプリケーション ID" とも呼ばれます) を取得するには、これらの手順に従います。
Microsoft Azure にログインします。
[アプリの登録] を検索し、 [アプリの登録] リンクを選択します。
Power BI コンテンツを埋め込むために使用する Microsoft Entra アプリを選択します。
[概要] セクションで、 [アプリケーション (クライアント) ID] の GUID をコピーします。
クライアント シークレット
クライアント シークレットを取得するには、これらの手順に従います。
Microsoft Azure にログインします。
[アプリの登録] を検索し、 [アプリの登録] リンクを選択します。
Power BI コンテンツを埋め込むために使用する Microsoft Entra アプリを選択します。
[管理] で、[証明書とシークレット] を選択します。
[クライアント シークレット] で、 [新しいクライアント シークレット] を選択します。
[クライアント シークレットの追加] ポップアップ ウィンドウで、アプリケーション シークレットの説明を入力し、アプリケーション シークレットの有効期限を選択し、 [追加] を選択します。
[クライアント シークレット] セクションで、新しく作成されたアプリケーション シークレットの [値] 列にある文字列をコピーします。 そのクライアント シークレットの値が "クライアント ID" です。
注意
クライアント シークレットの値が最初に表示されときに、必ずそれをコピーしてください。 このページから移動すると、クライアント シークレットは表示されなくなり、その値を取得できなくなります。
ワークスペース ID
ワークスペース ID の GUID を取得するには、これらの手順に従います。
Power BI サービスにサインインします。
埋め込むレポートを開きます。
URL から GUID をコピーします。 GUID は /groups/ と /reports/ の間にある数値です。
Note
プログラムでワークスペース ID を取得するには、Get Groups API を使用します。
レポート ID
テナント ID GUID を取得するには、次の手順に従います。
Power BI サービスにサインインします。
埋め込むレポートを開きます。
URL から GUID をコピーします。 GUID は /reports/ と /ReportSection の間にある数値です。
注意
プログラムでレポート ID を取得するには、Get Reports In Group API を使用します。
手順 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 - サーバー側の認証を有効にする
以下の表のファイルを作成または変更して、アプリでサーバー側の認証を有効にします。
| ファイル | 使用 |
|---|---|
| Startup.cs | Microsoft.Identity.Web 認証サービスを初期化する |
| appsettings.json | 認証の詳細 |
| PowerBiServiceApi.cs | Microsoft Entra トークンと埋め込みメタデータを取得する |
| HomeController.cs | モデルとして埋め込みデータをビューに渡す |
Microsoft.Identity.Web をサポートするようにスタートアップ ファイルを構成する
Startup.cs 内のコードを変更し、Microsoft.Identity.Web によって提供される認証サービスを適切に初期化します。
次のコード スニペットをアプリの Startup.cs ファイルに追加します。
Note
ConfigureServices のコードでは、次のいくつかの重要な処理を行います。
AddMicrosoftWebAppCallsWebApiを呼び出して、アクセス トークン (Microsoft Entra トークン) を取得するように Microsoft 認証ライブラリを構成します。AddInMemoryTokenCachesを呼び出し、Microsoft 認証ライブラリでアクセス トークンをキャッシュしてバックグラウンドでトークンを更新するために使用されるトークン キャッシュを構成します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 ファイルに、''クライアント ID'' や ''クライアント シークレット'' などの機密情報が含まれています。 セキュリティ上の理由から、この情報を設定ファイルに保持することはお勧めしません。 アプリケーションに埋め込む場合は、この情報を保存するための Azure Key Vault などのより安全な方法を検討してください。
プロジェクトで、新しいファイルを作成し、appsettings.json という名前を付けます。
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": "*" }「手順 2 - 埋め込みパラメーター値を取得する」で取得した埋め込みパラメーター値を入力します。
Domain- ドメインとテナント IDTenantId- ドメインとテナント IDClientId- クライアント IDClientSecret- クライアント シークレット
Note
前のコード スニペットでは、Power BI サービスのベース URL を追跡するために PowerBi:ServiceRootUrl パラメーターがカスタム構成値として追加されています。 Microsoft のパブリック クラウドの Power BI サービスに対してプログラミングする場合、URL は https://api.powerbi.com/ になります。 しかし、政府機関向けクラウドなどの他のクラウドでは Power BI サービスのルート URL が異なります。 したがって、この値はプロジェクト構成値として格納されるため、必要に応じて簡単に変更できます。
Microsoft Entra アクセス トークンを取得し、Power BI サービスを呼び出す
Power BI コンテンツ (レポートやダッシュボードなど) を埋め込むには、アプリで Microsoft Entra トークンを取得する必要があります。 トークンを取得するには、構成オブジェクトが必要になります。
このセクションのコードでは、.NET Core の依存関係の挿入パターンを使用します。 クラスでサービスを使用する必要がある場合は、そのサービスのコンストラクター パラメーターを追加することができます。実行時にサービス インスタンスを渡す作業は .NET Core ランタイムによって行われます。 この場合、コンストラクターでは IConfiguration パラメーターを使用して .NET Core 構成サービスのインスタンスを挿入します。これは、appsettings.json から PowerBi:ServiceRootUrl 構成値を取得するために使用されます。 tokenAcquisition という名前の ITokenAcquisition パラメーターでは、Microsoft.Identity.Web ライブラリによって提供される Microsoft 認証サービスへの参照を保持します。このパラメーターは、Microsoft Entra からアクセス トークンを取得するために使用されます。
RequiredScopes フィールドでは、Power BI サービス API によってサポートされる一連の委任されたアクセス許可を含む文字列配列を保持します。 アプリケーションで Microsoft Entra トークンを取得するためにネットワーク経由で呼び出しを行うときに、この委任されたアクセス許可のセットを渡すと、Microsoft Entra ID は送り返すアクセス トークンにそれらを含めることができます。
Note
''Microsoft Entra アプリ'' がご利用の Web アプリに必要なスコープで構成されていることをご確認ください。 詳細については、「Microsoft Entra アプリのアクセス許可を変更する」を参照してください。
アプリのプロジェクトで、Services というタイトルの新しいフォルダーを作成します。
その Services フォルダー内に、PowerBiServiceApi.cs というタイトルの新しいファイルを作成します。
以下のコードを 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 ファイルを変更する
このコード例では、依存関係の挿入を使用します。 ConfigureServices メソッドで services.AddScoped を呼び出して、サービスとして PowerBiServiceApi クラスを登録したので、 コンストラクターに PowerBiServiceApi パラメーターを追加することができます。PowerBiServiceApi インスタンスを作成し、それをコンストラクターに渡す作業は .NET Core ランタイムによって行われます。
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 が含まれます |
埋め込みレポートのコンテナーを作成する
埋め込みレポートのコンテナーとして使用される div 要素と、3 つのスクリプトを含む Embed.cshtml ファイル作成します。
View>Home フォルダーに、Embed.cshtml というファイルを作成します。
次のコード スニペットをその 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 コンテンツを埋め込むには、構成オブジェクトを作成する必要があります。 構成オブジェクトの作成の詳細については、「レポートを埋め込む」を参照してください。
このセクションでは、models 変数を使用して、レポートを埋め込むための構成オブジェクトを含む embed.js という名前の JavaScript ファイルを作成します。
models は、window['powerbi-client'].models の呼び出しを使用して初期化されます。 models 変数は、models.Permissions.All、models.TokenType.Aad、models.ViewMode.View などの構成値を設定するために使用されます。
powerbi.embed 関数では、models 構成オブジェクトを使用してレポートを埋め込みます。
wwwroot>js フォルダー内に、embed.js というファイルを作成します。
次のコード スニペットをその 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 レポートの埋め込み方法を試してみます。 Power BI 埋め込み分析のクライアント API を使い、クライアント側の API を使用してアプリを強化することができます。
アプリの準備ができたら、埋め込みアプリを運用環境に移行することができます。