教程：使用客户应用程序的示例嵌入嵌入 Power BI 内容

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

通过嵌入式分析和 Power BI Embedded（Azure 套餐），可以将 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 依赖项

  • 你自己的 Microsoft Entra 租户。

  • 要向 Power BI 对应用进行身份验证，需要以下内容之一：

    • 服务主体 - 允许 Microsoft Entra ID 对应用进行身份验证的 Microsoft Entra 服务主体对象。

    • Power BI Pro 许可证 - 这是你的主用户，你的应用将使用它来向 Power BI 进行身份验证。

    • Power BI Premium 每用户 (PPU) 许可证 - 这是你的主用户，你的应用将使用它来向 Power BI 进行身份验证。

    注意

    若要迁移到生产环境，则需要容量。

• 代码依赖项

.NET Core

• .NET Core 3.1 SDK（或更高版本）

• 集成开发环境 (IDE)。 建议使用以下环境之一：

  • Visual Studio

  • Visual Studio Code

.NET Framework

• .NET Framework 4.8

• Visual Studio

Java

• JDK（或 JRE）

• Eclipse IDE - 确认具有 Eclipse for Java EE Developers（企业版）

• Apache Tomcat Binary Distributions

Node JS

• Node.js

• 集成开发环境 (IDE)。 建议使用以下环境之一：

  • Visual Studio

  • Visual Studio Code

Python

• Python 3（或更高版本）

  注意

  • 如果是首次安装 Python，请选择“将 Python 添加到 PATH”选项，以将安装添加到 PATH 变量。
  • 如果已安装 Python，请确认 PATH 变量包括其安装路径。 有关详细信息，请参阅附录：设置环境变量 Python 文档（此链接指的是 Python 3）。

• 集成开发环境 (IDE)。 建议使用以下环境之一：

  • Visual Studio

  • Visual Studio Code

方法

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

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 注册应用程序可以：

• 为应用创建标识
• 让你的应用访问 Power BI REST API
• 如果使用主用户：请指定应用的 Power BI REST 权限

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

注意

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

步骤 3 - 创建 Power BI 工作区

Microsoft Fabric 将报表、仪表板和磁贴保留在工作区中。 若要嵌入这些项目，需要创建这些项并将其上传到工作区中。

提示

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

若要创建工作区，请执行以下操作：

1. 登录到 Fabric。

2. 选择“工作区”。

3. 选择“ + 新建工作区”。

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

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

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

提示

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

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

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

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

   

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

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

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

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

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

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

客户端 ID

提示

适用于：服务主体主用户

若要获取客户端 ID GUID（也称为“应用程序 ID”），请执行以下步骤：

1. 登录 Microsoft Azure。

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

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

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

工作区 ID

提示

适用于：服务主体主用户

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

1. 登录 Power BI 服务。

2. 打开要嵌入的报表。

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

   

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

报表 ID

提示

适用于：服务主体主用户

若要获取报表 ID GUID，请执行以下步骤：

1. 登录 Power BI 服务。

2. 打开要嵌入的报表。

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

   

客户端机密

提示

适用于：服务主体主用户

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

1. 登录 Microsoft Azure。

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

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

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

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

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

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

注意

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

租户 ID

提示

适用于：服务主体主用户

若要获取租户 ID GUID，请执行以下步骤：

1. 登录 Microsoft Azure。

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

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

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

Power BI 用户名和密码

提示

适用于：服务主体主用户

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

步骤 6 - 服务主体 API 访问

提示

适用于：服务主体主用户

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

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

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

   

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

3. 展开“服务主体可以使用 Fabric API”，并启用此选项。

   

注意

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

• 创建 Microsoft Entra 安全组
• 启用 Power BI 服务管理设置

步骤 7 - 启用工作区访问

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

1. 登录到 Fabric。

2. 滚动到要为其启用访问权限的工作区，然后选择“ 管理访问权限”。

   

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

   注意

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

4. 选择 添加 。

步骤 8 - 嵌入内容

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

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

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

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

   

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

4. 根据你希望应用使用的语言，打开以下文件夹之一：

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

   注意

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

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

.NET Core

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

   • 如果使用 Visual Studio，请打开 AppOwnsData.sln 文件。

   • 如果使用 Visual Studio Code，请打开“AppOwnsData”文件夹。

7. 打开 appsettings.json。

8. 根据身份验证方法，填写以下参数值：

   参数	服务主体	主用户
   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

9. 通过选择适当的选项来运行项目：

   • 如果使用 Visual Studio，请选择“IIS Express”（播放）。

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

.NET Framework

6. 如果使用 Visual Studio，请打开 AppOwnsData.sln 文件。

7. 打开 Web.config。

8. 根据身份验证方法，填写以下参数值：

   参数	服务主体	主用户
   authenticationType	服务主体	MasterUser
   applicationId	Microsoft Entra 应用客户端 ID	Microsoft Entra 应用客户端 ID
   workspaceId	包含嵌入报表的工作区的 ID，请参阅工作区 ID	包含嵌入报表的工作区的 ID，请参阅工作区 ID
   reportId	要嵌入的报表的 ID，请参阅报表 ID	要嵌入的报表的 ID，请参阅报表 ID
   pbiUsername	不适用	主用户的用户名，请参阅 Power BI 用户名和密码
   pbiPassword	不适用	主用户的密码，请参阅 Power BI 用户名和密码
   applicationSecret	Microsoft Entra ID 客户端密码	不可用
   tenant	Microsoft Entra 租户 ID	不可用

9. 通过选择“IIS Express”（播放）来运行项目。

Java

6. 打开 Eclipse 并按照下方的说明进行操作。

   注意

   有关“为客户嵌入内容”的 Java 示例应用说明，请参阅 Eclipse IDE for Java EE Developers（企业版）。 如果使用的是其他应用程序，则必须自行设置。

7. 将 Tomcat 服务器添加到 Eclipse：

   a. 选择“窗口”>“显示视图”>“服务器”。

   b. 在“服务器”选项卡中，选择“无可用服务器。请单击此链接创建新服务。”

   c. 在“定义新服务器”窗口中，展开 Apache，然后选择要在计算机上运行的 Tomcat 服务器。 例如 Tomcat v9.0 服务器。

   d. 选择“下一步”。

   e. 在“Tomcat 服务器”窗口中，选择“浏览”并导航到包含 Tomcat 服务器的文件夹。

   f. 在“Tomcat 服务器”窗口中，选择“安装的 JRE”。

   g. 在“安装的 JRE”窗口中，选择可用的 JRE，然后选择“应用并关闭”。

   h. 在“Tomcat 服务器”窗口中，选择“完成” 。 可以在“服务器”选项卡中看到 Tomcat 服务器。

8. 在 Eclipse 中打开项目：

   重要

   如果路径名称太长，Eclipse 可能会遇到问题。 若要避免此问题，请确认示例应用的文件夹在计算机的文件夹结构中未嵌入太深。

   a. 选择“文件”，然后选择“从文件系统打开项目”。

   b. 在“从文件系统或存档中导入项目”窗口中，选择“目录”并打开 AppOwnsData 文件夹。

   c. 选择“完成”。

9. 将 Tomcat 服务器添加到项目：

   a. 在“包资源管理器”窗格中，右键单击 AppOwnsData，然后选择“属性”。

   b. 在“AppOwnsData 的属性”窗口中，选择“目标运行时”，然后选择“Apache Tomcat”。 此选择包括你正在使用的 Apache Tomcat 版本，例如 Apache Tomcat v9.0。

   c. 选择“应用并关闭”。

10. 填写必填参数

    a. 在“包资源管理器”中，展开 AppOwnsData 项目。

    b. 展开“Java 资源”。

    c. 展开 src。

    d. 展开 com.embedsample.appoensdata.config。

    e. 打开 Config.java。

    f. 根据身份验证方法，填写以下参数值：

    参数	服务主体	主用户
    authenticationType	服务主体	MasterUser
    workspaceId	包含嵌入报表的工作区的 ID，请参阅工作区 ID	包含嵌入报表的工作区的 ID，请参阅工作区 ID
    reportId	要嵌入的报表的 ID，请参阅报表 ID	要嵌入的报表的 ID，请参阅报表 ID
    clientId	Microsoft Entra 应用客户端 ID	Microsoft Entra 应用客户端 ID
    pbiUsername	不可用	主用户的用户名，请参阅 Power BI 用户名和密码
    pbiPassword	不适用	主用户的密码，请参阅 Power BI 用户名和密码
    tenantId	Microsoft Entra 租户 ID	不可用
    appSecret	Microsoft Entra ID 客户端密码	不可用

11. 运行项目

    a. 在包资源管理器中，右键单击 AppOwnesData。

    b. 选择“运行方式”>“在服务器上运行”。

    c. 在“在服务器上运行”窗口中，选择“选择现有服务器”，再选择 Tomcat 服务器。

    d. 选择“完成”。

Node JS

6. 使用首选的 IDE 打开“App Owns Data”文件夹。 建议使用以下项之一：

   • Visual Studio

   • Visual Studio Code

7. 通过执行以下操作打开终端并安装所需的依赖项：npm install。

8. 展开 Config 文件夹，然后打开 config.json。

9. 根据身份验证方法，填写以下参数值：

   参数	服务主体	主用户
   authenticationMode	服务主体	MasterUser
   clientId	Microsoft Entra 应用客户端 ID	Microsoft Entra 应用客户端 ID
   workspaceId	包含嵌入报表的工作区的 ID，请参阅工作区 ID	包含嵌入报表的工作区的 ID，请参阅工作区 ID
   reportId	要嵌入的报表的 ID，请参阅报表 ID	要嵌入的报表的 ID，请参阅报表 ID
   pbiUsername	不适用	主用户的用户名，请参阅 Power BI 用户名和密码
   pbiPassword	不适用	主用户的密码，请参阅 Power BI 用户名和密码
   clientSecret	Microsoft Entra ID 客户端密码	不可用
   tenantId	Microsoft Entra 租户 ID	Microsoft Entra 租户 ID

10. 通过执行以下操作运行项目：

    a. 在 IDE 终端中执行 npm start。

    b. 在浏览器中打开新选项卡并导航到 http://localhost:5300。

Python

6. 打开 PowerShell 或命令提示符。

7. 确认你处于 Python >“Embed for your customers”文件夹中，并且该文件夹还包括 requirements.txt 文件，然后运行 pip3 install -r requirements.txt。

8. 使用首选的 IDE 打开“App Owns Data”文件夹。 建议使用以下环境之一：

   • Visual Studio

   • Visual Studio Code

9. 打开 config.py。

10. 根据身份验证方法，填写以下参数值：

    参数	服务主体	主用户
    AUTHENTICATION_MODE	服务主体	MasterUser
    WORKSPACE_ID	包含嵌入报表的工作区的 ID，请参阅工作区 ID	包含嵌入报表的工作区的 ID，请参阅工作区 ID
    REPORT_ID	要嵌入的报表的 ID，请参阅报表 ID	要嵌入的报表的 ID，请参阅报表 ID
    TENANT_ID	Microsoft Entra 租户 ID	不可用
    CLIENT_ID	Microsoft Entra 应用客户端 ID	Microsoft Entra 应用客户端 ID
    CLIENT_SECRET	Microsoft Entra ID 客户端密码	空值
    POWER_BI_USER	不适用	主用户的用户名，请参阅 Power BI 用户名和密码
    POWER_BI_PASS	不适用	主用户的密码，请参阅 Power BI 用户名和密码

11. 保存文件。

12. 通过执行以下步骤运行项目：

    a. 在 PowerShell 或命令提示符中，导航到 Python >“Embed for your customers”>“AppOwnesData”文件夹，并执行 flask run。

    b. 在浏览器中打开新选项卡并导航到 http://localhost:5000。

开发应用程序

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

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

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

重要

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

相关内容

• 转移到生产环境
• 为组织嵌入内容
• 嵌入分页报表

更多问题？ 在 Power BI 社区提问。