教程:使用“为客户嵌入内容”示例应用程序嵌入 Power BI 内容

适用范围:️ 应用拥有数据 用户拥有数据

通过“嵌入式分析”和“Power BI Embedded”,可以将 Power BI 内容(例如报表、仪表板和磁贴)嵌入到应用程序中 。

本教程介绍以下操作:

  • 设置嵌入式环境。
  • 配置“为客户嵌入内容”(也称为“应用拥有数据”)示例应用程序 。

用户无需登录到 Power BI 或拥有 Power BI 许可证即可使用应用程序。

如果你是独立软件供应商 (ISV) 或开发人员,并希望为第三方创建应用程序,建议你使用“为客户嵌入内容”方法来嵌入 Power BI 内容。

重要

如果要为国家/地区云嵌入内容,本教程的前几步会有所不同。 有关详细信息,请参阅国家/地区云的嵌入内容

代码示例规范

本教程说明了如何采用下列框架之一配置“为客户嵌入内容”示例应用程序:

  • .NET framework
  • .NET Core
  • Java
  • Node JS
  • Python

代码示例支持下列浏览器:

  • Microsoft Edge
  • Google Chrome
  • Mozilla Firefox

先决条件

开始学习本教程之前,请确认你具有下方列出的 Power BI 和代码依赖项:

  • Power BI 依赖项

  • 代码依赖项

方法

若要创建“为客户嵌入内容”示例应用,请执行以下步骤:

  1. 选择身份验证方法

  2. 注册 Microsoft Entra 应用程序

  3. 创建 Power BI 工作区

  4. 创建并发布 Power BI 报表

  5. 获取嵌入的参数值

  6. 服务主体 API 访问

  7. 启用工作区访问

  8. 嵌入内容

步骤 1 - 选择身份验证方法

嵌入式解决方案将因所选的身份验证方法而异。 因此,请先了解身份验证方法之间的区别,然后再确定最适合你的解决方案的方法。

下表描述了服务主体与主用户身份验证方法之间的一些主要差异。

注意事项 服务主体 主用户
机制 Microsoft Entra 应用的服务主体对象允许 Microsoft Entra ID 向 Power BI 对嵌入式解决方案应用进行身份验证。 Microsoft Entra 应用使用 Power BI 用户的凭据(用户名和密码)向 Power BI 进行身份验证。
安全性 服务主体是 Microsoft Entra ID 推荐的授权方法。 如果使用服务主体,则可使用应用程序机密或证书进行身份验证。

本教程仅介绍如何将服务主体与应用程序机密结合使用。 若要使用服务主体和证书嵌入内容,请参阅服务主体和证书一文 。
此身份验证方法不如使用服务主体安全。 你必须警惕主用户凭据(用户名和密码)。 例如,不要在嵌入的应用程序中公开它们,而应经常更改密码。
Microsoft Entra ID 委托的权限 不需要。 你的主用户或管理员必须授予你的应用访问 Power BI REST API 权限(也称为范围)的许可。 例如 Report.ReadWrite.All。
Power BI 服务的访问 无法使用服务主体访问 Power BI 服务。 可使用主用户凭据访问 Power BI 服务。
许可证 不需要 Pro 许可证。 可使用任何工作区中的内容(如果你是该工作区的成员或管理员)。 需要 Power BI Pro 或 Premium Per User (PPU) 许可证。

步骤 2 - 注册 Microsoft Entra 应用程序

向 Microsoft Entra ID 注册应用程序可以:

若要向 Microsoft Entra ID 注册应用程序,请按照注册应用程序中的说明进行操作。

注意

注册应用程序之前,需要确定要使用的身份验证方法、服务主体或主用户 。

步骤 3 - 创建 Power BI 工作区

Power BI 将报表、仪表板和磁贴存储在工作区中。 若要嵌入这些项,需要创建它们并将其上传到工作区。

提示

如果你已具有工作区,则可跳过此步骤。

若要创建工作区,请执行以下操作:

  1. 登录到 Power BI。

  2. 选择“工作区”。

  3. 选择“创建工作区”。

  4. 为工作区命名,然后选择“保存”。

步骤 4 - 创建并发布 Power BI 报表

下一步是创建报表并将其上传到工作区。 你可使用 Power BI Desktop 创建自己的报表,然后将其发布到工作区。 也可将示例报表上传到你的工作区。

提示

如果你的工作区中已有一个报表,则可跳过此步骤。

若要下载示例报表并将其发布到工作区,请执行以下步骤:

  1. 打开 GitHub Power BI Desktop 示例文件夹。

  2. 选择“代码”,再选择“下载 zip” 。

    A screenshot showing the ZIP download option in the Power B I desktop samples GitHub

  3. 提取已下载的 ZIP 并导航到“Samples Reports”文件夹。

  4. 选择要嵌入的报表,并将其发布到工作区。

步骤 5 - 获取嵌入的参数值

若要嵌入内容,需要获取某些参数值。 下表显示了所需的值并指出了它们是适用于服务主体身份验证方法、主用户身份验证方法还是同时适用于这两种方法 。

嵌入内容之前,请确保你具有下方列出的所有值。 某些值将有所不同,具体取决于所使用的身份验证方法:

参数 服务主体 主用户
客户端 ID Applies to. Applies to.
工作区 ID Applies to. Applies to.
报表 ID Applies to. Applies to.
客户端机密 Applies to. Does not apply to.
租户 ID Applies to. 仅对于 Node JS 是必需的
Power BI 用户名 Does not apply to. Applies to.
Power BI 密码 Does not apply to. Applies to.

客户端 ID

提示

适用范围:Applies to.服务主体Applies to.主用户

若要获取客户端 ID GUID(也称为“应用程序 ID”),请执行以下步骤:

  1. 登录 Microsoft Azure

  2. 搜索“应用程序注册”,然后选择“应用程序注册”链接。

  3. 选择用于嵌入 Power BI 内容的 Microsoft Entra 应用。

  4. 从“概述”部分,复制“应用程序(客户端) ID”GUID 。

工作区 ID

提示

适用范围:Applies to.服务主体Applies to.主用户

若要获取工作区 ID GUID,请执行以下步骤:

  1. 登录 Power BI 服务。

  2. 打开要嵌入的报表。

  3. 复制 URL 中的 GUID。 GUID 是 /groups/ 和 /reports/ 之间的数字 。

    A screenshot showing workspace ID GUID in the Power B I service U R L

或者,通过选择工作区名称旁边的“详细信息”可以在“管理门户”设置中查找工作区 ID。

A screenshot showing how to find the workspace I D from the admin settings.

报表 ID

提示

适用范围:Applies to.服务主体Applies to.主用户

若要获取报表 ID GUID,请执行以下步骤:

  1. 登录 Power BI 服务。

  2. 打开要嵌入的报表。

  3. 复制 URL 中的 GUID。 GUID 是 /reports/ 和 /ReportSection 之间的数字 。

    A screenshot showing report ID GUID in the Power B I service U R L

客户端机密

提示

适用范围:Applies to.服务主体Does not apply to.主用户

若要获取客户端机密,请执行下列步骤:

  1. 登录 Microsoft Azure

  2. 搜索“应用程序注册”,然后选择“应用程序注册”链接。

  3. 选择用于嵌入 Power BI 内容的 Microsoft Entra 应用。

  4. 在“管理”下,选择“证书和机密”

  5. 在“客户端机密”下,选择“新建客户端密钥” 。

  6. 在“添加客户端机密”弹出窗口中,提供应用程序机密的说明,选择应用程序机密过期时间,然后选择“添加” 。

  7. 从“客户端机密”部分,复制新创建的应用程序机密的“值”列中的字符串 。 客户端机密值为你的客户端 ID。

注意

请确保在第一次出现客户端密码值时复制它。 在你离开此页面后,客户端密码值将会隐藏起来,你将无法检索它。

租户 ID

提示

适用范围:Applies to.服务主体Does not apply to.主用户

若要获取租户 ID GUID,请执行以下步骤:

  1. 登录 Microsoft Azure

  2. 搜索“应用程序注册”,然后选择“应用程序注册”链接。

  3. 选择用于嵌入 Power BI 内容的 Microsoft Entra 应用。

  4. 从“概述”部分,复制“目录(租户) ID”GUID 。

Power BI 用户名和密码

提示

适用范围:Does not apply to.服务主体Applies to.主用户

获取用作主用户的 Power BI 用户的用户名和密码 。 此用户与用于创建工作区并将报表上传到 Power BI 服务的用户相同。

步骤 6 - 服务主体 API 访问

提示

适用范围:Applies to.服务主体Does not apply to.主用户

仅当使用服务主体身份验证方法时,此步骤才适用。 如果使用主用户,请跳过此步骤,并继续执行步骤 7(启用工作区访问)。

为了让 Microsoft Entra 应用程序能够访问 Power BI 内容和 API,Power BI 管理员必须在 Power BI 管理门户中启用服务主体访问权限。 如果你不是租户的管理员,请让租户的管理员为你启用“租户设置”。

  1. 在 Power BI 服务中,选择“设置”>“设置”>“管理员门户” 。

    A screenshot showing the admin settings menu option in the Power B I service settings menu.

  2. 选择“租户设置”,然后向下滚动到“开发人员设置”部分 。

  3. 展开“允许服务主体使用 Power BI API”,然后启用此选项。

    A screenshot showing how to enable the developer settings option, in the tenant settings menu option, in Power B I service.

注意

使用服务主体时,建议使用安全组限制对租户设置的访问 。 若要了解有关此功能的详细信息,请参阅服务主体文章中的以下部分:

步骤 7 - 启用工作区访问

要使 Microsoft Entra 应用能够访问 Power BI 服务中的对象(如报表、仪表板和语义模型),请以成员管理员身份将服务主体主用户添加到工作区。

  1. 登录 Power BI 服务。

  2. 滚动到要能够访问的工作区,然后选择“更多”菜单中的“工作区访问”。

    Screenshot showing the workspace access button in the more menu of a Power B I workspace.

  3. 在“访问”窗格中,根据所使用的身份验证方法,将服务主体或主用户复制到“输入电子邮件地址”文本框中 。

    注意

    如果使用的是服务主体,则服务主体的名称就是你为 Microsoft Entra 应用指定的名称。

  4. 选择 添加

步骤 8 - 嵌入内容

使用 Power BI Embedded 示例应用程序,可以创建“为客户嵌入内容”Power BI 应用。

请按照以下步骤来修改“为客户嵌入内容”示例应用程序,以便嵌入 Power BI 报表。

  1. 打开 Power BI 开发人员示例文件夹。

  2. 选择“代码”,再选择“下载 zip” 。

    A screenshot showing the ZIP download option in the Power B I developer samples GitHub

  3. 提取已下载的 ZIP 并导航到“PowerBI-Developer-Samples-master”文件夹。

  1. 根据你希望应用使用的语言,打开以下文件夹之一:

    • .NET Core
    • .NET Framework
    • Java
    • Node JS
    • Python

    注意

    “为客户嵌入内容”示例应用程序仅支持上面列出的框架。 “React”示例应用程序仅支持为组织嵌入内容解决方案 。

  2. 打开“Embed for your customers”文件夹。

  1. 使用以下方法之一打开“为客户嵌入内容”示例应用:

  2. 打开 appsettings.json。

  3. 根据身份验证方法,填写以下参数值:

    参数 服务主体 主用户
    AuthenticationMode 服务主体 MasterUser
    ClientId Microsoft Entra 应用客户端 ID Microsoft Entra 应用客户端 ID
    TenantId Microsoft Entra 租户 ID 空值
    PbiUsername 空值 主用户的用户名,请参阅 Power BI 用户名和密码
    PbiPassword 空值 主用户的密码,请参阅 Power BI 用户名和密码
    ClientSecret Microsoft Entra ID 客户端密码 不可用
    WorkspaceId 包含嵌入报表的工作区的 ID,请参阅工作区 ID 包含嵌入报表的工作区的 ID,请参阅工作区 ID
    ReportId 要嵌入的报表的 ID,请参阅报表 ID 要嵌入的报表的 ID,请参阅报表 ID
  4. 通过选择适当的选项来运行项目:

    • 如果使用 Visual Studio,请选择“IIS Express”(播放) 。

    • 如果使用 Visual Studio Code,请选择“运行”>“启动调试”。

开发应用程序

配置并运行“为客户嵌入内容”示例应用程序后,可以开始开发自己的应用程序。

试用 Power BI 嵌入式分析操场,开始开发并跟进所有新的 Power BI Embedded 功能和更新。

准备就绪后,请查看迁移到生产环境要求。 还需要容量,并应查看容量计划一文,创建最能满足你需求的 SKU。

重要

如果使用免费嵌入试用令牌进行开发,则必须购买生产容量。 在购买容量之前,“免费试用版”横幅将继续显示在嵌入式报表顶部。

更多问题? 在 Power BI 社区提问