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

範本應用程式是客戶開始從資料中取得見解的好方法。範本應用程式可將它們連線至其資料，以快速啟動並執行它們。範本應用程式為他們提供預先建置的報告，如果他們願意，他們可以自訂這些報告。

客戶並不總是熟悉如何連線到其資料的詳細資訊。在安裝模板應用程序時必須提供這些詳細信息可能是他們的痛點。

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

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

他們所要做的就是選取 [安裝] 並針對其資料來源進行驗證，然後就可以開始了！

此處說明客戶體驗。

自動化範本應用程式安裝流程的螢幕擷取畫面，顯示 ISV 入口網站、設定步驟和 Power BI 重新導向程式。

本文說明基本流程、必要條件、主要步驟，以及自動化設定範本應用程式安裝所需的 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 租用戶。
在前一個租用戶中註冊的服務主體（僅限應用程式權杖）。 如需詳細資訊，請參閱使用服務主體和應用程式密碼內嵌 Power BI 內容。請務必將應用程式註冊為 伺服器端 Web 應用程式 應用程式。您可以註冊伺服器端 Web 應用程式以建立應用程式密碼。在此程式中，您必須儲存 應用程式識別碼 （ClientID）和 應用程式密碼 （ClientSecret），以供後續步驟使用。
已準備好安裝的 參數化範本應用程式 。範本應用程式必須在您在 Microsoft Entra ID 中註冊應用程式的相同租用戶中建立。如需詳細資訊，請參閱範本應用程式提示或在 Power BI 中建立範本應用程式。在範本應用程式中，您需要記下下列資訊，以進行後續步驟：
- 應用程式識別碼、 套件金鑰和 擁有者識別碼 ，它們會在建立應用程式時定義範本應用程式屬性的程式結束時，顯示在安裝 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 應用程式的 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。

範本應用程式 - 建立安裝票證

如何建立範本應用程式安裝和設定的安裝票證的範例，可從範例應用程式的 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 社群提問。 (英文)

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-29