通过

教程：使用 Azure Function 自动配置模板应用安装

  • 项目

模板应用有助于客户开始从其数据中获取见解。 模板应用通过将其连接到数据来快速启动并运行。 模板应用为客户提供预先生成的报表，客户可以根据需要对其进行自定义。

客户并不总是熟悉如何连接到其数据的细节。 如果让他们在安装模板应用时提供这些细节对他们来说可能比较困难。

如果你是数据服务提供商，并且创建了一个模板应用来帮助客户在你的服务上开始使用他们的数据，那么可让客户更容易安装模板应用。 你可以自动配置模板应用的参数。

当客户登录到门户时，他们可选择你准备好的特殊链接。 可通过该连接执行以下操作：

  • 启动自动化，收集所需的信息。
  • 预配置模板应用参数。
  • 将客户重定向到可在其中安装应用的 Power BI 帐户。

他们只需选择“安装”并对其数据源进行身份验证就可以了！

此客户体验如下所示。

Illustration of user experience with an auto-installation application.

本教程将使用我们创建的自动安装 Azure Functions 示例来预配置和安装模板应用。 为了便于演示，故意采用简单的示例。 该示例封装了 Azure Functions 的设置，以利用 Power BI API 来为用户自动安装模板应用并配置它。

有关常规自动化流及其使用的 API 的详细信息，请参阅自动配置模板应用安装

我们的简单应用程序使用 Azure Function。 有关 Azure Functions 的详细信息，请参阅 Azure Functions 文档。

基本流程

下面是客户通过选择门户上的链接来启动应用程序时，应用程序执行的基本流程列表。

  1. 用户登录 ISV 的门户并选择提供的链接。 此操作将启动流。 ISV 的门户在此阶段准备了用户特定的配置。

  2. ISV 根据在 ISV 的租户中注册的服务主体（仅限应用的令牌）获取“仅限应用”令牌。

  3. 使用 Power BI REST API，ISV 将创建“安装票证”，其中包含由 ISV 准备的用户特定参数配置。

  4. ISV 使用包含安装票证的 POST 重定向方法将用户重定向到 Power BI。

  5. 通过安装票证将用户重定向到其 Power BI 帐户，并提示他们安装模板应用。 当用户选择“安装”时，将会为其安装模板应用。

注意

尽管在创建安装票证的过程中由 ISV 配置参数值，但在安装的最后阶段，只能由用户提供与数据源相关的凭据。 这种安排是为了防止将它们公开给第三方，从而确保用户和模板应用数据源之间的连接安全。

先决条件

设置模板应用自动化开发环境

在继续设置应用程序之前，请按照快速入门：使用 Azure 应用程序配置创建 Azure Functions 应用中的说明开发 Azure Function 以及 Azure 应用程序配置。 按照本文中的说明创建应用程序配置。

在 Microsoft Entra ID 中注册应用程序

请按照使用服务主体和应用程序密码嵌入 Power BI 内容中所述创建服务主体。

请务必将应用程序注册为“服务器端 Web 应用程序”应用。 注册服务器端 Web 应用程序以创建应用程序密码。

保存“应用程序 ID”（客户端 ID）和“应用程序机密”（客户端机密），以便执行后续步骤 。

可通过嵌入安装程序工具快速开始创建应用注册。 如果你使用的是 Power BI 应用注册工具，请选择“为客户嵌入内容”选项。

以管理员身份将服务主体添加到模板应用工作区中，以便能够测试自动化工作流。

模板应用准备

创建模板应用并准备好进行安装后，请保存以下信息以执行后续步骤：

  • 应用 ID、包密钥和所有者 ID，这些信息显示在创建应用时定义模板应用的属性过程最后一步的安装 URL 中 。

    还可选择模板应用的“发布管理”窗格中的“获取链接”，获取相同的链接。

  • 在模板应用的语义模型中定义的参数名称。 参数名称是区分大小写的字符串。 也可在定义模板应用的属性时从“参数设置”选项卡中检索它们，或者从 Power BI 中的语义模型设置中进行检索。

注意

如果模板应用已准备好安装，则可在模板应用上测试预配置的安装应用程序，即使该应用尚未在 AppSource 上公开提供。 为了让租户外部的用户能够使用自动化安装应用程序来安装模板应用，模板应用必须在 Power BI 应用市场中公开提供。 在使用所创建的自动化安装应用程序分发模板应用之前，请务必将其发布到合作伙伴中心。

安装和配置模板应用

本节将使用我们创建的自动安装 Azure Functions 示例来预配置和安装模板应用。 为了便于演示，故意采用简单的示例。 它使你可以利用 Azure Functions 和 Azure 应用程序配置来轻松部署和使用适用于你的模板应用的自动安装 API。

下载 Visual Studio（版本 2017 或更高版本）

下载 Visual Studio（2017 版或更高版本）。 请务必下载最新版 NuGet 包。

下载自动安装 Azure Functions 示例

若要开始，请从 GitHub 下载自动安装 Azure Functions 示例。

Screenshot that shows the automated installation Azure Functions sample.

设置 Azure 应用程序配置

若要运行此示例，需要使用如下所述的值和键设置 Azure 应用程序配置。 键为“应用程序 ID”、“应用程序机密”以及模板应用的“AppId”、“PackageKey”和“OwnerId”值 。 有关如何获取这些值的信息，请参阅以下各节。

这些键还在 Constants.cs 文件中进行了定义。

配置密钥 含义
TemplateAppInstall:Application:AppId 安装 URL 中的 AppId
TemplateAppInstall:Application:PackageKey 安装 URL 中的 PackageKey
TemplateAppInstall:Application:OwnerId 安装 URL 中的 OwnerId
TemplateAppInstall:ServicePrincipal:ClientId 服务主体应用程序 ID
TemplateAppInstall:ServicePrincipal:ClientSecret 服务主体应用程序机密

Constants.cs 文件如下所示：

Screenshot that shows the Constant.cs file.

获取模板应用属性

填写创建应用时定义的所有相关模板应用属性。 这些属性是模板应用的“AppId”、“PackageKey”和“OwnerId”值 。

若要获取上述值，请执行以下步骤：

  1. 登录 Power BI。

  2. 转到应用程序的原始工作区。

  3. 打开“发布管理”窗格。

    Screenshot that shows the Release Management pane.

  4. 选择应用版本并获取其安装链接。

    Screenshot that shows the Release Management button.

  5. 将链接复制到剪贴板。

    Screenshot that shows the Get link button.

  6. 此安装 URL 包含需要其值的 3 个 URL 参数。 使用应用程序的“appId”、“packageKey”“ownerId”值 。 示例 URL 与下面显示的内容相似。

    https://app.powerbi.com/Redirect?action=InstallApp&appId=3c386...16bf71c67&packageKey=b2df4b...dLpHIUnum2pr6k&ownerId=72f9...1db47&buildVersion=5

获取应用程序 ID

将 Azure 中的“应用 ID”填入“ApplicationID”字段。 应用使用“applicationId”值对你向其请求获取权限的用户标识自身。

若要获取应用程序 ID，请按以下步骤操作：

  1. 登录 Azure 门户。

  2. 在左窗格中，选择“所有服务”>“应用注册” 。

    Screenshot that shows app registrations search.

  3. 选择需要应用程序 ID 的应用程序。

    Screenshot that shows choosing an app.

  4. 存在列为 GUID 的应用程序 ID。 使用此应用程序 ID 作为应用程序的“applicationID”值。

    Screenshot that shows the applicationId value.

获取应用程序密码

将 Azure 的“应用注册”部分中的“密钥”部分信息填入“ApplicationSecret”字段 。 使用服务主体时，此属性适用。

若要获取应用程序密码，请按以下步骤操作：

  1. 登录 Azure 门户。

  2. 在左窗格中，选择“所有服务”>“应用注册” 。

    Screenshot that shows App registration search.

  3. 选择需要使用应用程序机密的应用。

    Screenshot shows choosing an app.

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

  5. 选择“新的客户端密码”。

  6. 在“说明”框中输入一个名称并选择持续时间。 然后选择“保存”为应用程序获取值。 如果在保存密钥值后关闭“密钥”窗格，“值”字段会仅显示为隐藏状态 。 此时，你无法检索密钥值。 如果忘记了密钥值，请在 Azure 门户中新建密钥值。

    Screenshot that shows the key value.

在本地测试函数

按照在本地运行函数中所述的步骤运行函数。

配置门户以向函数的 URL 发出 POST 请求。 示例为 POST http://localhost:7071/api/install。 请求正文应为描述键值对的 JSON 对象。 键是 Power BI Desktop 中定义的参数名称。 值是要为模板应用中的每个参数设置的所需值。

注意

在生产中，将根据门户的预期逻辑推导每个用户的参数值。

所需的流应为：

  1. 门户按用户或会话准备请求。
  2. 向 Azure Function 发出 POST /api/install 请求。 请求正文包含键值对。 键是参数名称。 值是要设置的所需值。
  3. 如果正确进行了所有配置，浏览器应会自动重定向到客户的 Power BI 帐户并显示自动安装流。
  4. 安装后，将按照步骤 1 和 2 中的配置设置参数值。

相关内容

将项目发布到 Azure

若要将项目发布到 Azure，请按照 Azure Functions 文档中的说明进行操作。 然后，可以将模板应用自动安装 API 集成到产品中，并开始在生产环境中对其进行测试。