通过

模板应用安装的自动配置

模板应用是客户开始从其数据中获取见解的好方法。 模板应用通过将模板应用连接到其数据来快速启动和运行它们。 模板应用为他们提供预生成的报表，他们可以根据需要对其进行自定义。

客户并不总是熟悉如何连接到其数据的详细信息。 安装模板应用时，必须提供这些详细信息，这对他们来说是一个难题。

如果你是数据服务提供商，并且已经创建了一个模板应用来帮助客户开始使用其服务中的数据，则可以更轻松地安装模板应用。 可以自动配置模板应用的参数。 当客户登录到门户时，他们选择已准备好的特殊链接。 此链接：

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

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

此处演示了客户体验。

自动化模板应用安装流的屏幕截图，其中显示了 ISV 门户、配置步骤和 Power BI 重定向过程。

本文介绍基本流、先决条件、主要步骤以及自动配置模板应用安装所需的 API。 如果您想直接深入并开始，可以跳到 教程，在该教程中，您将使用我们准备的一个利用 Azure 函数的简单示例应用程序来自动进行模板应用程序安装配置。

自动化配置的基本流

自动配置模板应用安装的基本流程将按如下所示进行：

  1. 用户登录到 ISV 的门户并选择提供的链接。 此操作启动自动化流。 在此阶段，ISV 门户为用户准备特定的配置。
  2. ISV 基于注册在 ISV 租户中的服务主体（app-only token），获取应用专用令牌。
  3. 使用 Power BI REST API，ISV 将创建 安装票证，其中包含 ISV 准备的用户特定参数配置。
  4. ISV 使用 POST 包含安装票证的重定向方法将用户重定向到 Power BI。
  5. 用户使用安装凭证被重定向到其 Power BI 帐户，并收到安装模板应用的提示。 当用户选择 “安装”时，会为其安装模板应用。

注释

虽然在创建安装票证的过程中由 ISV 配置参数值，但数据源相关的凭据仅由用户在安装的最后阶段提供。 这种安排可防止它们向第三方公开，并确保用户与模板应用数据源之间建立安全连接。

先决条件

若要为模板应用提供预配置的安装体验，需要满足以下先决条件：

  • Power BI Pro 许可证。 如果未注册 Power BI Pro， 请先注册免费试用版 ，然后再开始。

  • 你自己的 Microsoft Entra 租户设置。 有关如何设置一个租户的说明，请参阅 创建Microsoft Entra 租户。

  • 在前述租户中注册的 服务主体（应用程序专用令牌）。 有关详细信息，请参阅 使用服务主体和应用机密嵌入 Power BI 内容。 请确保将应用程序注册为 服务器端 Web 应用程序 应用。 注册服务器端 Web 应用程序以创建应用程序机密。 在此过程中，需要保存 应用程序 ID （ClientID）和 应用程序机密 （ClientSecret），以便执行后续步骤。

  • 已准备好安装的参数化模板应用。 模板应用必须在注册应用程序Microsoft Entra ID 的同一租户中创建。 有关详细信息，请参阅 模板应用提示 或在 Power BI 中创建模板应用。 在模板应用中，需要记下后续步骤的以下信息：

    • 应用 ID、 包密钥和 所有者 ID ，因为它们在创建应用时 在定义模板应用属性 的过程结束时显示在安装 URL 中。 还可以通过在模板应用的“发布管理”窗格中选择“获取”链接来获取相同的链接。
    • 参数名称 是按照模板应用的语义模型定义的。 参数名称是区分大小写的字符串，在定义模板应用的属性或 Power BI 中的语义模型设置时，也可以从“参数设置”选项卡检索。

  • 若要能够测试自动化工作流，请将服务主体作为管理员添加到模板应用工作区。

    注释

    如果模板应用已准备好安装，则可以在模板应用中测试预配置的安装应用程序，即使它尚未在 AppSource 上公开发布。 若要使租户外部的用户能够使用自动安装应用程序来安装模板应用，模板应用必须在 AppSource 中公开可用。 在使用创建的自动安装应用程序分发模板应用之前，请务必 将其发布到合作伙伴中心。

主要步骤和 API

以下各节介绍了自动配置模板应用安装以及所需的 API 的主要步骤。 虽然大部分步骤都是使用 Power BI REST API 完成的，但此处所述的代码示例是使用 .NET SDK 完成的。

步骤 1：创建 Power BI 客户端对象

使用 Power BI REST API 需要从 Microsoft Entra ID 获取服务主体的访问令牌。 在调用 Power BI REST API 之前，需要获取 Power BI 应用程序的 Microsoft Entra 访问令牌。 若要使用访问令牌创建 Power BI 客户端，需要创建 Power BI 客户端对象，以便与 Power BI REST API 进行交互。 通过使用 Microsoft.Rest.TokenCredentials 对象包装 AccessToken 来创建 Power BI 客户端对象。

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI client object. It's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code goes here.
}

步骤 2：创建安装票证

创建安装票证，用于将用户重定向到 Power BI。 用于此作的 API 是 CreateInstallTicket API。

示例应用程序中的 InstallTemplateApp/InstallAppFunction.cs 文件中提供了如何为模板应用安装和配置创建安装票证 的示例。

以下代码示例演示如何使用模板应用 CreateInstallTicket REST API。

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
    InstallDetails = new List<TemplateAppInstallDetails>()
    {
        new TemplateAppInstallDetails()
        {
            AppId = Guid.Parse(AppId),
            PackageKey = PackageKey,
            OwnerTenantId = Guid.Parse(OwnerId),
            Config = new TemplateAppConfigurationRequest()
            {
                Configuration = Parameters
                                    .GroupBy(p => p.Name)
                                    .ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
            }
        }
    }
};

// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);

步骤 3：使用票证将用户重定向到 Power BI

创建安装票证后，可以使用它将用户重定向到 Power BI 以继续模板应用安装和配置。 使用 POST 方法重定向到模板应用的安装 URL，其请求正文中包含安装票据。

有多种方法记录如何使用 POST 请求进行重定向。 选择一个或多个取决于方案以及用户与门户或服务的交互方式。

一个简单的示例，主要用于测试目的，使用包含隐藏字段的表单，在加载时自动提交自身。

<html>
    <body onload='document.forms["form"].submit()'>
        <!-- form method is POST and action is the app install URL -->
        <form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
            <!-- value should be the new install ticket -->
            <input type='hidden' name='ticket' value='H4sI....AAA='>
        </form>
    </body>
</html>

以下示例中，示例应用程序的响应包含安装票证，并自动将用户重定向到 Power BI。 此 Azure 函数的响应与我们在前面的 HTML 示例中看到的自动自提交表单相同。

...
    return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}

...

public static string RedirectWithData(string url, string ticket)
{
    StringBuilder s = new StringBuilder();
    s.Append("<html>");
    s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
    s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
    s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
    s.Append("</form></body></html>");
    return s.ToString();
}

注释

浏览器重定向有多种使用方法 POST 。 应始终使用最安全的方法，具体取决于服务需求和限制。 请记住，某些形式的不安全重定向可能会导致用户或服务面临安全问题。

步骤 4：将自动化移动到生产环境

请务必在你设计的自动化准备就绪后，将其发布到生产环境。

相关内容

  • Last updated on