使用 JavaScript API 与 Power BI 报表进行交互Interact with Power BI reports using the JavaScript API

Power BI JavaScript API 可以轻松将 Power BI 报表嵌入到应用程序中。The Power BI JavaScript API enables you to easily embed Power BI reports into your applications. 使用此 API,应用程序能够以编程方式与各种报表元素(例如页面和筛选器)进行交互。With the API, your applications can programmatically interact with different report elements like pages and filters. 这种交互这种交互性使 Power BI 报表与应用程序的集成更紧密。This interactivity makes Power BI reports a more integrated part of your application.

重要

Power BI 工作区集合已弃用,到 2018 年 6 月 或合同指示时可用。Power BI Workspace Collections is deprecated and is available until June 2018 or when your contract indicates. 建议你规划到 Power BI Embedded 的迁移以避免应用程序中断。You are encouraged to plan your migration to Power BI Embedded to avoid interruption in your application. 有关如何将数据迁移到 Power BI Embedded 的信息,请参阅如何将 Power BI 工作区集合内容迁移到 Power BI EmbeddedFor information on how to migrate your data to Power BI Embedded, see How to migrate Power BI Workspace Collections content to Power BI Embedded.

通过使用作为应用程序一部分托管的 IFrame,可将 Power BI 报表嵌入到应用程序中。You embed a Power BI report in your application by using an iframe that is hosted as part of the application. IFrame 充当应用程序和报表之间的边界,如下图所示:The iframe acts as a boundary between your application and the report, as you can see in the following image:

Power BI 工作区集合 iframe,无 Javascript API

iframe 使嵌入过程变得更容易,但是如果没有 JavaScript API,报表和应用程序相互之间无法进行交互。The iframe makes the embedding process a lot easier, but without the JavaScript API the report and your application can't interact with each other. 较少交互可能会让人感觉报表没有真正成为应用程序的一部分。This lack of interaction can make it feel like the report is not really part of the application. 报表和应用程序确实需要进行相互通信,如下图中所示:The report and application really need to communicate back and forth, as in the following image:

Power BI 工作区集合 iframe,有 Javascript API

使用 Power BI JavaScript API,可以编写能够安全地通过 iframe 边界的代码。The Power BI JavaScript API enables you to write code that can securely pass through the iframe boundary. 这使得应用程序能够以编程方式在报表中执行操作,侦听由于用户在报表中执行操作而发生的事件。This enables your application to programmatically perform an action in a report, and to listen for events from actions that users make within the report.

使用 Power BI JavaScript API 可以做什么?What can you do with the Power BI JavaScript API?

使用此 JavaScript API 可以管理报表、导航到报表中的页面、筛选报表以及处理嵌入的事件。With the JavaScript API you can manage reports, navigate to pages in a report, filter a report, and handle embedding events. 下图显示了此 API 的结构。The following diagram shows the structure of the API.

Power BI JavaScript API 图示

管理报表Manage reports

使用此 Javascript API 可以管理在报表和页面级别发生的行为:The Javascript API enables you to manage behavior at the report and page level:

了解有关嵌入报表的详细信息Learn more about embedding a report

JavaScript API 能发现报表中的所有页并设置当前页。The JavaScript API enables you to discover all pages in a report and to set the current page. 请尝试 导航演示应用程序Try the navigation demo application.

了解有关页面导航的详细信息Learn more about page navigation

筛选报表Filter a report

此 JavaScript API 针对嵌入的报表和报表页面提供了基本和高级筛选功能。The JavaScript API provides basic and advanced filtering capabilities for embedded reports and report pages. 请尝试 筛选演示应用程序,并查看此处的一些入门代码。Try the filtering demo application, and review some introductory code here.

基本筛选器Basic filters

基本筛选器置于列或层次结构级别,包含要包括或排除的值的列表。A basic filter is placed on a column or hierarchy level and contains a list of values to include or exclude.

const basicFilter: pbi.models.IBasicFilter = {
  $schema: "https://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1,2,3,4]
}

高级筛选器Advanced filters

高级筛选器使用逻辑运算符 AND 或 OR,接受一个或两个条件,每个条件都有其自己的运算符和值。Advanced filters use the logical operator AND or OR, and accept one or two conditions, each with their own operator and value. 支持的条件有:Supported conditions are:

  • None
  • LessThanLessThan
  • LessThanOrEqualLessThanOrEqual
  • GreaterThanGreaterThan
  • GreaterThanOrEqualGreaterThanOrEqual
  • ContainsContains
  • DoesNotContainDoesNotContain
  • StartsWithStartsWith
  • DoesNotStartWithDoesNotStartWith
  • IsIs
  • IsNotIsNot
  • IsBlankIsBlank
  • IsNotBlankIsNotBlank
const advancedFilter: pbi.models.IAdvancedFilter = {
  $schema: "https://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Name"
  },
  logicalOperator: "Or",
  conditions: [
    {
      operator: "Contains",
      value: "Wash"
    },
    {
      operator: "Contains",
      value: "Park"
    }
  ]
}

了解有关筛选的详细信息Learn more about filtering

处理事件Handling events

除了向 iframe 发送信息之外,应用程序还可以接收来自 iframe 的有关下列事件的信息:In addition to sending information into the iframe, your application can also receive information on the following events coming from the iframe:

  • 嵌入的元素Embed
    • loadedloaded
    • errorerror
  • 报告Reports
    • pageChangedpageChanged
    • dataSelected(即将推出)dataSelected (coming soon)

了解有关处理事件的详细信息Learn more about handling events

后续步骤Next steps

有关 Power BI JavaScript API 的详细信息,请查看以下链接:For more information about the Power BI JavaScript API, check out the following links: