Tutorial: Embed Power BI paginated reports into an application for your customers (preview)

With Power BI Embedded in Azure or Power BI embedding in Office, you can embed paginated reports into an application using app owns data. App owns data is about having an application that uses Power BI as its embedded analytics platform. As an ISV or a developer, you can create Power BI content that displays paginated reports in an application that is fully integrated and interactive, without requiring users to have a Power BI license. This tutorial demonstrates how to integrate a paginated report into an application using the Power BI .NET SDK with the Power BI JavaScript API.

Power BI Embed Report

In this tutorial, you learn how to:

  • Register an application in Azure.
  • Embed a Power BI paginated report into an application.

Prerequisites

To get started, you're required to have:

If you don’t have an Azure subscription, create a free account before you begin.

Set up your Power BI environment

Embedding a paginated report requires assigning a workspace to a dedicated capacity, and uploading the report to the workspace.

Create an app workspace

As you're using a service principal to sign into your application, you're required to use the new workspaces. As a service principal, you must also be an admin or member of the app workspaces involved with your application.

Create a dedicated capacity

Before you import or upload a paginated report to embed, the workspace containing the report must be assigned to at least an A4 or P1 capacity. There are two types of capacity you can choose from:

  • Power BI Premium - For embedding a paginated report, a P SKU capacity is required. When embedding Power BI content, this solution is referred to as Power BI embedding. For more information regarding this subscription, see What is Power BI Premium?
  • Azure Power BI Embedded - You can purchase a dedicated capacity from the Microsoft Azure portal. This subscription uses the A SKUs. For embedding paginated reports you need at least an A4 subscription. For details on how to create a Power BI Embedded capacity, see Create Power BI Embedded capacity in the Azure portal.

The table below describes the resources and limits of each SKU. To determine which capacity best fits your needs, see the which SKU should I purchase for my scenario table.

Capacity Nodes Total v-cores Backend v-cores RAM (GB) Frontend v-cores
P1/A4 8 4 25 4
P2/A5 16 8 50 8
P3/A6 32 16 100 16

Assign an app workspace to a dedicated capacity

Once you create a dedicated capacity, you can assign your app workspace to that dedicated capacity.

To assign a dedicated capacity to a workspace using service principal, use the Power BI REST API. When you are using the Power BI REST APIs, make sure to use the service principal object ID.

Create and upload your paginated reports

You can create your paginated report using Power BI Report Builder, and then upload the report to the service.

You can import paginated reports into the new workspaces using the Power BI REST APIs.

Embed content using the sample application

This sample is deliberately kept simple for demonstration purposes. It's up to you or your developers to protect the application secret.

Follow the steps below to start embedding your content using the sample application.

  1. Download Visual Studio (version 2013 or later). Make sure to download the latest NuGet package.

  2. Download the App Owns Data sample from GitHub to get started.

    App Owns Data application sample

  3. Open the Web.config file in the sample application. There are fields you need to fill in to run the application. Choose ServicePrincipal for the AuthenticationType.

    Fill in the following fields:

    Note

    The default AuthenticationType in this sample is MasterUser. Make sure you change it to ServicePrincipal.

    Web Config file

Application ID

Fill in the applicationId information with the Application ID from Azure. The applicationId is used by the application to identify itself to the users from which you're requesting permissions.

To get the applicationId, follow these steps:

  1. Sign into the Azure portal.

  2. In the left-hand nav pane, select All Services, and search for App Registrations.

    App registration search

  3. Select the application that needs the applicationId.

    Choosing App

  4. There's an Application ID that is listed as a GUID. Use this Application ID as the applicationId for the application.

    applicationId

Workspace ID

Fill in the workspaceId information with the app workspace (group) GUID from Power BI. You can get this information either from the URL when signed into the Power BI service or using Powershell.

URL

workspaceId

Powershell

Get-PowerBIworkspace -name "Paginated Report Embed"

workspaceId from powershell

Report ID

Fill in the reportId information with the report GUID from Power BI. You can get this information either from the URL when signed into the Power BI service or using Powershell.

URL

reportId

Powershell

Get-PowerBIworkspace -name "Paginated Report Embed" | Get-PowerBIReport

reportId from powershell

Application secret

Fill in the ApplicationSecret information from the Keys section of your App registrations section in Azure.

To get the ApplicationSecret, follow these steps:

  1. Sign in to the Azure portal.

  2. In the left-hand nav pane, select All services and search for App registrations.

    App registration search

  3. Select the application that needs to use the ApplicationSecret.

    Choosing App

  4. Select Certificates and secrets under Manage.

  5. Select New client secrets.

  6. Enter a name in the Description box and select a duration. Then select Save to get the Value for your application. When you close the Keys pane after saving the key value, the value field shows only as hidden. At that point, you aren't able to retrieve the key value. If you lose the key value, create a new one in the Azure portal.

    Key value

Tenant

Fill in the tenant information with your azure tenant ID. You can get this information from the Azure AD admin center when signed into the Power BI service or by using Powershell.

Run the application

  1. Select Run in Visual Studio.

    Run the application

  2. Then select Embed Report.

    Select a content

  3. Now you can view the report in the sample application.

    View application

Embed Power BI paginated reports within your application

Even though the steps to embed your Power BI paginated reports are done with the Power BI REST APIs, the example codes described in this article are made with the .NET SDK.

Embedding Power BI paginated reports for your customers within your application, requires you to have an Azure AD service principal and get an Azure AD access token for your Power BI application, before you make calls to the Power BI REST APIs.

To create the Power BI Client with your access token, create a Power BI client object, which allows you to interact with the Power BI REST APIs. You create the Power BI client object by wrapping the AccessToken with a Microsoft.Rest.TokenCredentials object.

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI Client object. it's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code to embed items.
}

Get the paginated report you want to embed

You can use the Power BI client object to retrieve a reference to the item you want to embed.

Here is a code sample of how to retrieve the first report from a given workspace.

A sample of getting a content item whether it's a report, dashboard, or tile that you want to embed is available within the Services\EmbedService.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// You need to provide the workspaceId where the dashboard resides.
ODataResponseListReport reports = await client.Reports.GetReportsInGroupAsync(workspaceId);

// Get the first report in the group.
Report report = reports.Value.FirstOrDefault();

Create the embed token

Generate an embed token, which can be used from the JavaScript API. To create an embedded token for embedding Power BI paginated reports, use the Reports GenerateTokenForCreateInGroup API.

A sample of creating an embed token is available within the Services\EmbedService.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Generate Embed Token.
var generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");
EmbedToken tokenResponse = client.Reports.GenerateTokenInGroup(workspaceId, report.Id, generateTokenRequestParameters);

// Generate Embed Configuration.
var embedConfig = new EmbedConfig()
{
    EmbedToken = tokenResponse,
    EmbedUrl = report.EmbedUrl,
    Id = report.Id
};

Load an item using JavaScript

You can use JavaScript to load a paginated report into a div element on your web page.

For a full sample of using the JavaScript API, you can use the Playground tool. The Playground tool is a quick way to play with different types of Power BI Embedded samples. You can also get more Information about the JavaScript API by visiting the PowerBI-JavaScript wiki page.

Next steps

In this tutorial, you've learned how to embed Power BI paginated reports into an application for your customers. You can also try to embed Power BI content for your organization.

More questions? Try asking the Power BI Community