简介

  • 12 分钟

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

注意

若要了解 Power BI 客户端 API 的基础知识以及如何使用它们嵌入 Power BI 内容，请参阅“嵌入 Power BI 内容”模块。

除了嵌入 Power BI 内容之外，客户端 API 还允许应用：

  • 将操作应用于内容，例如添加报表筛选器。
  • 处理事件，以便应用可以响应在报表中执行的用户操作，例如按钮选择。
  • 与书签交互，即应用书签或创建新书签。
  • 生成动态报表布局，这些布局提供控件，以便用户可以自定义报表体验。
  • 创建个性化报表视觉对象。
  • 驱动上下文中的分析工作流。

应用操作

应用可以将多个操作应用于嵌入的内容。 这些操作包括常规操作，例如重新加载或刷新报表。 还可进入或退出全屏模式，或在首次嵌入内容时重新使用应用在配置对象中使用的设置。

除了常规操作之外，还可进行页面导航操作。 此外，还可进行筛选器和切片器操作，以允许应用确定或设置筛选器/切片器状态。 其他实用操作包括允许导出视觉对象数据的数据操作，以及使用新的自定义命令扩展菜单的菜单操作。

你可通过转到 Power BI 嵌入式分析操场并按照以下说明操作来体验一些操作。

注意

Power BI 嵌入式分析操场是一个有助于学习、探索和试验 Power BI 嵌入式分析的网站。 它包括用于实践的开发人员沙盒，使用包含示例 Power BI 内容或你自己的内容的客户端 API。 代码片段和展示也可供你浏览。

有关详细信息，请参阅什么是 Power BI 嵌入式分析操场？

在左窗格中，选择“开发人员沙盒”。

显示左窗格的图像，其中突出显示了“开发人员沙盒”选项。

出现提示时，选择“使用示例”按钮以开始使用示例报表。

显示“使用示例报表”对话框的图像，其中突出显示了“使用示例”按钮。

提示

还可以选择你自己的报表（源自 Power BI 服务），或者可以使用开发应用生成的嵌入令牌。 在此活动中，继续使用示例报表。

操场嵌入示例报表，报表上方是代码窗格，其中包含嵌入、加载和呈现报表所需的代码。

在“嵌入式报表 API”窗格中，展开“常规操作”组。

显示“嵌入式报表 API”窗格的图像，其中已展开“常规操作”组。

若要更新代码，请从“嵌入式报表 API”窗格中拖动“全屏”操作，并将其放置在代码窗格中的最后一行（第 94 行）。

图像显示“全屏”操作，其中箭头指示在代码窗格中放置它的位置。

查看添加到代码窗格的代码片段。 然后，若要运行代码，请在代码窗格上方的菜单栏上，选择“运行”。

显示菜单栏的图像，其中突出显示了“运行”菜单选项。

报表以全屏模式呈现。 若要退出全屏模式，请按 Esc 键。

现在，让我们以编程方式修改报表的日期切片器。 在“嵌入式报表 API”窗格中，展开“筛选器和切片器”组。

显示“嵌入式报表 API”窗格的图像，其中已展开“筛选器和切片器”组。

将“设置切片器状态”操作拖动到代码窗格中，将其放置在最后一个代码行下方。 然后查看添加到代码窗格的 43 个代码行。 运行代码，可以看到报表继续以全屏模式打开。 “日期”切片器日期范围应设置为 2014 年 10 月 12 日 - 2014 年 11 月 27 日。

显示“日期”切片器和新日期范围的图像。

若要退出全屏模式，请按 Esc 键。

提示

操场提供了一种毫不费力的方式来发现操作并评估它们，而无需开发应用。 请记住，可以使用示例报表或你自己的报表浏览这些操作。

处理可订阅事件

事件在嵌入的 Power BI 内容与应用之间通信。 应用可以引发事件，以响应自动操作（例如报表呈现）或用户操作（例如按钮选择）。

这也意味着，当报表加载（引发 loaded 事件）或呈现（rendered 事件）时，应用可以采用有意义的方式做出响应。 有关详细信息，请参阅使用分阶段嵌入。

当用户与嵌入式 Power BI 报表交互时，应用可以做出响应。 以下用户操作引发应用可以订阅的事件：

  • 选择报表按钮（buttonClicked 事件）
  • 选择命令扩展，这是应用添加到上下文菜单的自定义命令（commandTriggered 事件）
  • 选择超链接（dataHyperlinkClicked 事件）
  • 选择数据点，如柱形图视觉对象中的一个柱形（dataSelected 事件）
  • 选择报表视觉对象（visualClicked 事件）
  • 报表页面更改（pageChanged 事件）

请考虑增强应用的潜力。 在 Tailspin Toys 中，他们的销售应用可以将感兴趣的客户注释写回应用数据库。 当用户选择报表按钮时，应用将打开一个对话框窗口，提示他们输入注释。 应用保留输入的数据，然后刷新报表以显示报表视觉对象中表示的新数据。

本模块后面几个单元演示应用如何响应各种事件。

此外，其他事件可用于仪表板、仪表板磁贴、问答体验和嵌入移动视图的报表。 有关详细信息，请参阅如何处理事件。

与书签交互

书签允许用户捕获 Power BI 报表页面的状态，包括筛选器和报表元素的可见性状态。 应用后，书签会将捕获的状态还原到报表页面。 可以播放一系列书签（如幻灯片放映），当向观众展示时，它可以是一种有用的故事讲述设备。

在应用中，可以编程方式控制添加书签体验，可在其中：

  • 通过应用、捕获或播放书签对其进行管理。
  • 应用书签或返回到当前查看会话。
  • 输入或退出书签幻灯片放映模式。
  • 显示或隐藏“书签”窗格。
  • 检索书签列表。
  • 访问书签及其属性，也许是为了在下拉列表中呈现它们。

下图显示了可以在 Power BI 嵌入式分析操场中浏览的书签操作。

显示操场中可用的书签操作的图像，与之前列出的体验保持一致。

在 Tailspin Toys 中，其销售应用允许用户将嵌入式报表页面的当前状态捕获为“个人书签”。 个人书签仅对创建该书签的用户可见，并允许他们返回到感兴趣的特定视图。 应用在应用数据库中保留个人书签元数据，并显示个人书签的下拉列表，以便用户可以重新应用它们。

本模块后面的单元演示应用如何使用书签。

有关详细信息，请参阅增强用户使用书签的体验。

生成动态报表布局

可以使用布局 API 允许用户选择要查看的视觉对象和布局。

下图显示了可以在 Power BI 嵌入式分析操场中浏览的布局操作。

显示布局操作的图像，其中包括“应用自定义布局”、“检查布局”、“隐藏所有视觉对象标题”、“显示所有视觉对象标题”和“隐藏单个视觉对象标题”。

在 Tailspin Toys 中，销售应用允许用户定义页面大小、画布缩放和页面布局。 在页面布局中，应用用户可以为每个视觉对象指定视觉对象布局。 它还允许它们显示感兴趣的视觉对象或调整其大小，并隐藏其他视觉对象。

本模块后面的单元演示应用如何个性化报表布局。

有关详细信息，请参阅个性化报表布局。

创建个性化报表视觉对象

Power BI 客户端 API 包括 powerbi-report-authoring 包。 此包是 powerbi-client 库的扩展，用于以编程方式创建和个性化视觉对象，并在加载 Power BI 报表后对其进行编写。 它还允许应用编辑嵌入式 Power BI 报表。

使用 addPage 函数添加创作页面，使用 createVisual 函数将具有默认布局的新视觉对象添加到创作页面。

下图显示了可以在 Power BI 嵌入式分析操场中浏览的创作操作。

显示创作操作的图像，其中包括“创建创作页面”和“创建视觉对象”等等。

在 Tailspin Toys 中，销售应用提供引导式体验，允许用户设置和个性化新视觉对象。

本模块后面的单元演示应用如何允许用户创建个性化视觉对象。

有关详细信息，请参阅报表创作概述。

驱动上下文中的分析工作流

应用在 div 元素中嵌入 Power BI 内容，在 iframe 元素中托管内容。 iframe 元素在应用与嵌入内容之间创建分隔，确保提高数据安全性。 客户端 API 始终在应用与嵌入内容之间通信。 由于通信是双向的，因此应用可以驱动上下文中的分析工作流：

  1. 用户在应用中导航。
  2. 应用显示针对特定视图筛选的 Power BI 报表。
  3. 用户以交互方式筛选报表中的数据。
  4. 用户选择要执行操作的按钮。
  5. 应用通过运行某些代码做出响应。

图像显示上下文中的分析工作流，如上一个步骤中所述。