Embed a report visual

  • Artikel

Tip

Try embedding a report visual or experiment with our client APIs in the Explore our APIs section of the Power BI Embedded Analytics Playground.

This article covers the steps for embedding a visual in your application. Learn more about visuals in Visuals in Power BI.

How to embed a visual

When you embed Power BI content in an app, you use a configuration object to define the content that you're embedding and to specify the content's settings. Then you pass that object to the API.

When you embed a visual, use a configuration object of type IVisualLoadConfiguration:

interface IVisualLoadConfiguration {
    accessToken?: string;
    embedUrl?: string;
    id?: string;
    pageName: string;
    tokenType?: models.TokenType;
    type: string;
    visualName: string;
}

This interface includes these properties:

  • accessToken - The token that gives you access to the Power BI data that you're embedding. See Understand the different embedding solutions to learn more about access tokens.

  • embedUrl - The URL of the report that contains the visual that you're embedding. This URL becomes the source of the HTML iframe element that contains the embedded visual. Specifically, the API assigns the URL to the src attribute of the iframe. You can use a Report API to obtain this URL. Two examples are:

  • id - The ID of the Power BI report that contains the visual that you're embedding.

  • pageName - The name of the page that contains the visual that you're embedding. You can use the Report getPages method to obtain the pages in a report.

  • tokenType - The kind of token that gives you access to the Power BI data that you're embedding.

    • Use models.TokenType.Aad if you're embedding for your organization (the user owns the data).
    • Use models.TokenType.Embed if you're embedding for your customers (the app owns the data).

    See Understand the different embedding solutions for more information.

  • type - The kind of content that you're embedding. Use 'visual' for a visual.

  • visualName - The name of the visual that you're embedding. You can use the Page getVisuals method to obtain the visuals in a page.

Example

The following example shows you how to embed a single visual:

// Set up the configuration object that determines what to embed and how to embed it.
let embedConfiguration = {
    accessToken: anAccessToken,
    embedUrl: anEmbedUrl,
    id: aReportId,
    pageName: aPageName,
    tokenType: aTokenType,
    type: 'visual',
    visualName: aVisualName
};
 
// Get a reference to the HTML element that contains the embedded report.
let embedContainer = $('#embedContainer')[0];
 
// Embed the visual.
let visual = powerbi.embed(embedContainer, embedConfiguration);

Filters

By default the updateFilters API will apply visual level filters when embedding a single report visual. This can cause a conflict with filters applied in the embed configuration object, as these are applied at the report level. To fix this issue, you can set the filters level with the API:

await visual.updateFilters(FiltersOperations.Add, filters, FiltersLevel.Report);

Learn more about filters in Control report filters.

Next steps

Embed a report

Embed a paginated report

Embed a standalone Q&A visual

Use bootstrap for better performance