自動設定範本應用程式安裝

發行項
12/22/2023

範本應用程式是客戶開始從其數據取得見解的絕佳方式。範本應用程式透過將其連線到其數據，讓應用程式快速啟動並執行。範本應用程式會提供預先建置的報表，讓他們可以視需要自定義這些報表。

客戶不一定會熟悉如何連線到其數據的詳細數據。安裝範本應用程式時，必須提供這些詳細數據，可能是它們的痛點。

如果您是數據服務提供者，並已建立範本應用程式，以協助您的客戶開始使用其服務上的資料，您可以更輕鬆地安裝範本應用程式。您可以將範本應用程式參數的設定自動化。當客戶登入入口網站時，他們會選取您已準備的特殊連結。此連結：

啟動自動化，其會收集所需的資訊。
預先設定範本應用程式參數。
將客戶重新導向至可安裝應用程式的Power BI 帳戶。

他們必須做的就是選取 [針對其數據源進行安裝和 驗證]，而且他們很適合去！

此處說明客戶體驗。

Illustration of user experience with an auto-installation application.

本文說明基本流程、必要條件，以及自動化範本應用程式安裝設定所需的主要步驟和 API。如果您想要深入探討並開始使用，您可以跳到教學課程，透過我們準備的簡單範例應用程式來使用 Azure 函式，將範本應用程式安裝設定自動化。

基本流程

自動化範本應用程式安裝設定的基本流程如下：

使用者登入ISV的入口網站，並選取提供的連結。此動作會起始自動化流程。 ISV 的入口網站會在此階段準備使用者特定的設定。
ISV 會根據ISV租用戶中註冊的服務主體（僅限應用程式令牌）取得僅限應用程式令牌。
使用 Power BI REST API，ISV 會 建立安裝票證，其中包含 ISV 所準備的使用者特定參數位態。
ISV 會使用 POST 包含安裝票證的重新導向方法，將使用者重新導向至 Power BI。
系統會使用安裝票證將使用者重新導向至其Power BI帳戶，並提示您安裝範本應用程式。當使用者選取 [ 安裝] 時，會為其安裝範本應用程式。

注意

雖然ISV會在建立安裝票證的過程中設定參數值，但數據源相關認證只會由使用者在安裝的最後階段提供。此安排可防止他們向第三方公開，並確保使用者與範本應用程式數據源之間的安全連線。

必要條件

若要為您的樣本應用程式提供預先設定的安裝體驗，需要下列必要條件：

Power BI Pro 授權。如果您尚未註冊 Power BI Pro，請在開始之前註冊免費試用。
已設定您自己的 Microsoft Entra 租使用者。如需如何設定的指示，請參閱建立 Microsoft Entra 租使用者。
在上述租用戶中註冊的服務主體（僅限應用程式令牌）。 如需詳細資訊，請參閱使用服務主體和應用程式秘密內嵌PowerBI內容。請務必將應用程式註冊為 伺服器端 Web 應用程式 應用程式。您註冊伺服器端 Web 應用程式以建立應用程式秘密。在此程式中，您必須儲存 應用程式識別碼 （ClientID）和 應用程式秘密 （ClientSecret），以取得後續步驟。
已準備好進行安裝的參數化範本應用程式。範本應用程式必須建立在您在 Microsoft Entra ID 中註冊應用程式的相同租使用者中。如需詳細資訊，請參閱在Power BI 中建立範本應用程式秘訣或建立範本應用程式。從範本應用程式，您必須記下後續步驟的下列資訊：
- 應用程式識別碼、套件密鑰和擁有者識別碼，在建立應用程式時定義範本應用程式屬性的程式結尾，出現在安裝 URL 中。您也可以在範本應用程式的 [發行管理] 窗格中選取 [取得連結]，以取得相同的連結。
- 參數名稱 定義於範本應用程式的語意模型中。當您定義範本應用程式的屬性或 Power BI 中的語意模型設定時，參數名稱會區分大小寫的字串，也可以從 [參數設定] 索引卷標擷取。
若要能夠測試您的自動化工作流程，請將服務主體新增至範本應用程式工作區作為管理員。

注意

如果範本應用程式已準備好進行安裝，則您可以在範本應用程式上測試預先設定的安裝應用程式，即使 AppSource 尚未公開提供。若要讓租使用者外部的用戶能夠使用自動化安裝應用程式來安裝範本應用程式，必須在Power BI 應用程式市集中公開提供範本應用程式。使用所建立的自動化安裝應用程式散發範本應用程式之前，請務必將其發佈至合作夥伴中心。

主要步驟和 API

下列各節說明將範本應用程式安裝設定自動化的主要步驟，以及您需要的 API。雖然大部分的步驟都是使用 Power BI REST API完成，但此處所述的程式代碼範例是使用 .NET SDK 所建立。

步驟 1：建立 Power BI 客戶端物件

使用 Power BI REST API 需要您從 Microsoft Entra ID 取得服務主體的存取令牌。您必須先取得 Power BI 應用程式的 Microsoft Entra 存取令牌，才能呼叫 Power BI REST API。若要使用存取令牌建立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。

Template Apps CreateInstallTicket

您可以從範例應用程式中的 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：將自動化移至生產環境

當您設計的自動化準備就緒時，請務必將其移至生產環境。

試用我們的教學課程，其使用簡單的 Azure 函式來自動設定範本應用程式安裝。
更多問題嗎？請嘗試詢問 Power BI 社群。