上一篇

下一步

简介

已完成

若要在应用中嵌入 Power BI 内容，需要完成以下开发任务。

1. 添加客户端库以编程方式控制嵌入。
2. 添加客户端库。
3. 添加嵌入容器。
4. 输出服务器端生成的事实。
5. 设置配置对象。
6. 嵌入 Power BI 内容。

添加客户端库

使用 Power BI 客户端 API 通过 JavaScript 或 TypeScript 嵌入 Power BI 内容。 它是一个客户端库，它提供对整个嵌入体验的编程控制。

API 包括三个包：

• powerbi-client - 包括嵌入内容的所有 API（在 powerbi-report-authoring 库中找到的 API 除外）。
• powerbi-models - 包含对象模型。 每个模型都有一个 TypeScript 接口、一个 JSON 架构定义和一个验证函数，以确保给定对象是有效的模型。
• powerbi-report-authoring - 一个扩展，用于创建和个性化视觉对象，并在加载 Power BI 报表后对其进行创作。 它还允许应用以编程方式编辑嵌入的 Power BI 报表。

可以使用 NuGet 或 npm 安装 Power BI 客户端 API 库。

有关详细信息，请参阅什么是 Power BI 嵌入式分析客户端 API？。

添加客户端库

应用必须包含用于获取客户端库的 script 元素。

<script src="/powerbi-client/dist/powerbi.js"></script>

还可以从内容分发网络 (CDN) 获取客户端库。 有关示例，请参阅 JSDelivr powerbi-client。

<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.22.3/dist/powerbi.min.js"></script>

直接包含时，客户端库公开为名为 powerbi-client 的全局实例。 还有另一个名为 powerbi 的全局实例，它是 Power BI 服务的实例。

添加嵌入容器

应用必须包含 div 元素，该元素充当嵌入容器。

<div id="embedContainer"></div>

应用在 div 元素中嵌入 Power BI 内容，在 iframe 元素中托管内容。 iframe 元素在应用与嵌入内容之间创建分隔，确保数据安全。 客户端 API 始终在应用与嵌入内容之间安全通信。

请观看以下视频，该视频演示客户端库的工作原理。

输出服务器端生成的事实

应用必须获取在客户端输出的访问令牌。 此外，应用必须在客户端输出特定 Power BI 项目属性。

提示

若要了解如何获取访问令牌和检索 Power BI 项目属性，请参阅设置权限以嵌入 Power BI 内容模块。

以下 script 元素包含三个变量。 accessToken 变量存储服务器端生成的访问令牌。 reports 和 datatsets 变量存储可嵌入的项目的 JSON 表示形式。 在此示例中，项目类型是报表和数据集。 具体而言，变量存储项目 ID 和嵌入 URL 属性，这些必须在客户端提供才能支持嵌入。 它还包括 name 属性，这样应用可以以友好的方式向用户显示项目名称，就像在菜单中那样。

<script>
    var accessToken = "@Model.AccessToken";
    var reports = @Html.Raw(Model.ReportsJson)
    var datasets = @Html.Raw(Model.DatasetsJson)
</script>

设置配置对象

应用必须创建配置对象才能提供嵌入 Power BI 内容所需的所有信息。 必须设置配置对象的以下五个属性：

• tokenType - 基于以下方案之一设置值：
  • 针对组织：访问令牌是 Azure AD 令牌。 将值设置为 models.TokenType.Aad。
  • 针对客户：访问令牌是嵌入令牌。 将值设置为 models.TokenType.Embed。
• accessToken - 服务器端生成的访问令牌。
• type - 设置为以下值之一。 第 2 和第 3 单元介绍如何嵌入 Power BI 内容的每个类型。
  • report：对于 Power BI 报表或分页报表。
  • visual：对于 Power BI 报表视觉对象。
  • dashboard：对于仪表板。
  • tile：对于仪表板磁贴。
  • qna：适用于 Q&A 体验。
• id - Power BI 项目 ID。
• embedUrl - Power BI 项目嵌入 URL。 此 URL 将成为托管嵌入项目的 iframe 元素的源。 具体而言，API 将 URL 分配给 iframe 元素的 src 属性。

以下代码演示如何使用“针对客户”方案创建配置对象以嵌入 Power BI 报表。 models 是对客户端库模型的引用，其中包含有用的枚举类型（枚举）。

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

可以设置更多特定于内容的配置属性。 第 2 和第 3 单元对此进行了描述。

嵌入 Power BI 内容

使用 powerbi.embed(embedContainer, config) 函数嵌入 Power BI 内容。

以下代码演示如何嵌入 Power BI 报表。 embedContainer 变量存储对嵌入容器（div 元素）的引用，而 config 变量存储为特定 Power BI 报表设置的配置对象。 最后一个语句通过传入嵌入容器和配置对象来执行嵌入。 report 变量存储对嵌入报表的引用。

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Get a reference to the embedding container.
let embedContainer = $('#embedContainer')[0];

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

// Embed the report in the embedding container.
report = powerbi.embed(embedContainer, config);

在下一个单元中，你将了解如何嵌入 Power BI 报表，这是最常见的 Power BI 内容类型。

继续