授權與交易性強制執行 (公開預覽)

當您在 AppSource 上建立要下載的 Power BI 視覺效果時，您現在可以使用 Microsoft 系統來管理並強制執行其授權。 使用者會使用熟悉的工具指派和管理授權，例如 Microsoft 365 系統管理中心，而授權 API 可讓您強制執行這些授權，並確保只有授權的使用者才能轉譯視覺效果。

授權強制執行流程

下表說明透過 Microsoft 管理視覺授權所涉及的步驟：

Step	詳細資料
在合作夥伴中心建立供應項目 (部分機器翻譯)	選擇透過 Microsoft 商務系統進行交易。 啟用 Microsoft 來管理授權。 設定定價和可用性。
將授權強制執行新增至 Power BI 視覺效果套件	建立或重新設定套件以使用 Power BI 執行階段授權，此設定會根據每個使用者的存取權強制執行授權。
客戶會在 AppSource 中探索您的供應項目以及購買訂用帳戶	當客戶在 AppSource (英文) 中購買您的供應項目時，他們也會取得 Power BI 視覺效果的授權。
客戶管理其訂用帳戶並指派/取消指派使用者授權	客戶會在 Microsoft 365 系統管理中心管理訂閱，並指派這些視覺效果和供應專案的授權，就如同Office 或 Power BI 等其他訂用帳戶的設定方法。
強制執行運行時間檢查	使用我們現成的 API 在執行階段強制執行授權檢查，為客戶提供統一的體驗。
檢視報表 (部分機器翻譯) 以推動成長	深入了解收入、支付資訊，以及訂單和授權詳細資料。 依時間和地理位置來檢視關於授權的購買、更新和取消資訊。

授權 API

授權 API 可讓 Power BI 視覺效果開發人員強制執行 Power BI 視覺效果授權。 API 支援擷取 Power BI 使用者獲指派 Power BI 視覺效果授權的相關資訊。 該功能也可讓您觸發顯示於 Power BI 視覺效果上的授權相關通知，並告知使用者他們需要購買缺少的授權。 視覺效果不應該顯示自己的授權 UX，而是使用其中一個 Power BI 支援的預先定義通知，如下所述。

若想了解 Power BI 授權，請參閱授權強制執行 (部分機器翻譯)。

注意

授權 API 從 4.7 版開始支援。 若要了解您正在使用哪個版本，請檢查 pbiviz.json 檔案中的 apiVersion。

擷取指派給現用使用者的視覺效果服務方案

若要指派服務方案，請新增對 getAvailableServicePlans 的呼叫 (可透過 IVisualLicenseManager 取得)。 根據效能考量，請嘗試擷取授權一次 (建議在 constructor 或 init 中呼叫)，並儲存結果。
擷取授權之後，這些授權在 Power BI 工作階段期間會快取至 Power BI 主機端上，而後續對相同授權的任何呼叫都會傳回快取的資料。

export interface IVisualLicenseManager {
        getAvailableServicePlans(): IPromise<powerbi.extensibility.visual.LicenseInfoResult>;
    }

擷取授權的作業可能需要很長時間，因此 getAvailableServicePlans 呼叫採用異步呼叫，且應該在您的程式碼中進行相同處理。
作為呼叫方法的回應，將會傳回 LicenseInfoResult 物件。

export interface LicenseInfoResult {
        plans: ServicePlan[] | undefined;
        isLicenseUnsupportedEnv: boolean; 
        isLicenseInfoAvailable: boolean; 
    }

• plans - 此視覺效果現用使用者購買的服務方案陣列。 (針對任何其他視覺效果購買的授權不會包含在回應中。)
  ServicePlan 包含服務識別碼 (spIdentifier) 及其狀態 (ServicePlanState)。

  • spIdentifier：當您在合作夥伴中心設定供應項目方案時，所產生的服務識別碼字串值 (請參閱下列範例)

  • state – enum (ServicePlanState) 代表所指派方案的狀態。
    支援的服務方案狀態：

    State	描述
    非作用中	表示授權為非作用中，不應該用於佈建權益。
    使用中	表示授權為作用中，且可用於佈建權益。
    警告	表示授權可能因付款違規而處於寬限期。
    已暫停	表示授權因付款違規而暫停。
    Unknown	Sentinel 值。

    只有 active 和 warning 狀態代表授權可使用。 所有其他狀態都應視為無法產生可使用的授權。

• isLicenseUnsupportedEnv - 表示目前轉譯視覺效果的 Power BI 環境不支援授權管理或強制執行。 目前，下列 Power BI 環境不支持授權管理或授權強制執行：

  • 內嵌 - 發佈至 Web、PaaS 內嵌
  • 國家/地區雲端 (取決於國家/地區雲端的可交易性一般支援)
  • RS 伺服器 (未計劃支援)
  • 使用 REST API (部分機器翻譯) 匯出 (PDF\PPT)

• isLicenseInfoAvailable - 指出是否可以擷取授權資訊。 當 Power BI Desktop 使用者未登入或未連線到網際網路時，可能會導致授權擷取失敗。 針對 Web，授權擷取可能會因為暫時的服務中斷而失敗。

呼叫 getAvailableServicePlans 的範例 (使用上圖中的服務識別碼)：

this.licenseManager.getAvailableServicePlans().then((result: LicenseInfoResult) => {
            this.notificationType = result.isLicenseUnsupportedEnv ?  powerbi.LicenseNotificationType.UnsupportedEnv : powerbi.LicenseNotificationType.General;
            this.hasServicePlans = !!(result.plans && result.plans.length && result.plans[0].spIdentifier == "test_isvconnect1599092224747.powerbivisualtransact.plan1" && 
                ( result.plans[0].state == powerbi.ServicePlanState.Active ||  result.plans[0].state == powerbi.ServicePlanState.Warning));
            
            // display notification if the user doesn't have licenses
            if (!this.hasServicePlans) {
                this.licenseManager.notifyLicenseRequired(this.notificationType).then((value) => {
                    if (value) {
                        this.isIconDisplayed = true;
                    }
                }).catch((err) => {
                    console.log('ERROR', err);
                })
            }
        }).catch((err) => {
            this.hasServicePlans = undefined;
            console.log(err);
        });

通知使用者缺少必要的授權

Power BI 平台提供數個立即可用的體驗，可用來通知：

• 應購買授權，才能享有完整的視覺效果功能
• 特定的視覺效果功能因缺少授權而遭封鎖
• 由於缺少授權，已封鎖整個視覺效果
• 因為使用中的 Power BI 環境不支援授權管理\強制執行，因此已封鎖整個視覺效果

export interface IVisualLicenseManager {
        notifyLicenseRequired(notificationType: LicenseNotificationType): IPromise<boolean>;
        notifyFeatureBlocked(tooltip: string): IPromise<boolean>;
        clearLicenseNotification(): IPromise<boolean>;
    }

指出缺少必要授權的一般圖示

使用 notifyLicenseRequired 呼叫搭配 LicenseNotificationType.General，將圖示顯示為視覺效果容器的一部分。
觸發之後，圖示將會在整個視覺效果的存留期內保留，直到呼叫 clearLicenseNotification 或 notifyLicenseRequired 為止。

注意

只有同時符合下列兩個條件時，才會強制執行 LicenseNotificationType.General 通知：支援授權環境和 Power BI 編輯案例。 在不支援的環境中或報表處於閱讀模式或在儀錶板中呼叫此項目時，將不會套用圖示，並且會在呼叫的回應中傳回 false。

顯示包含「需要授權」一般圖示的視覺效果範例：

將視覺效果的顯示與「缺少授權」通知重疊

使用 notifyLicenseRequired 呼叫搭配 LicenseNotificationType.VisualIsBlocked 來重疊視覺效果的顯示，並顯示因發現缺少必要的授權而遭到封鎖的通知。
觸發之後，此通知將會在整個視覺效果的存留期內保留，直到呼叫 clearLicenseNotification 或 notifyLicenseRequired 為止。

顯示包含「視覺效果遭封鎖」通知的視覺效果範例。 Power BI Desktop 只會顯示 [取得授權] 選項：

將視覺效果的顯示與「不支援的環境」通知重疊

使用 notifyLicenseRequired 呼叫搭配 LicenseNotificationType.UnsupportedEnv，將視覺效果的顯示與視覺效果遭封鎖的通知重疊，因為使用中的 Power BI 不支援授權管理\強制執行。
觸發之後，圖示將會在整個視覺效果的存留期內保留，直到呼叫 clearLicenseNotification 或 notifyLicenseRequired 為止。

注意

只有在不支援授權環境的情況呼叫時，才會強制執行 LicenseNotificationType.UnsupportedEnv 通知。 在任何其他環境中呼叫此項目時，將不會套用通知，並且會在呼叫的回應中傳回 false。

顯示包含「不支援的環境」通知的視覺效果範例：

顯示橫幅以通知無法套用特定視覺效果的功能

在套用特定視覺效果的功能時，若發現缺少所需的授權，您可以使用 notifyFeatureBlocked 呼叫以在視覺效果容器中快顯橫幅。 橫幅也支援您可以設定的自訂工具提示，並用來提供觸發通知功能的其他資訊。

注意

只有在支援授權環境，且未套用封鎖重疊的情況下 (LicenseNotificationType.UnsupportedEnv、LicenseNotificationType.VisualIsBlocked)，才會強制執行功能遭封鎖通知。 在不支援的環境中呼叫此通知將不會套用通知，並且會在呼叫的回應中傳回 false。

注意

若要支援本地化的 Power BI 環境，建議您維護使用中工具提示的當地語系化版本。 請使用當地語系化 API 來擷取 Power BI 地區設定語言。

觸發之後，橫幅會顯示 10 秒，或直到觸發其他「功能遭封鎖」橫幅，或直到呼叫 clearLicenseNotification 為止 (以最早者為準)。

顯示包含「功能遭封鎖」橫幅通知的視覺效果範例：

測試授權的視覺效果

若要在公開發佈前，先對授權的視覺效果進行端對端測試：

• 如果您要建立全新的供應項目，請將視覺效果新增為測試客戶帳戶的私人方案。 供應項目只會向此測試帳戶顯示可供購買。 在公開供應項目之前，請先使用此帳戶驗證供應項目。
• 如果視覺效果已在 AppSource 中供應，而且您想要將其升級為授權的視覺效果，您無法將其設為私人方案，因為此操作會從 AppSource 隱藏該視覺效果，導致您現有的使用者無法存取。 目前無法對已發佈的視覺效果進行端到端測試。 使用在 AppSource 測試原始視覺效果的相同方式對其進行測試，透過模擬授權 API 值來檢查不同的可能性。

考量與限制

• 功能橫幅的工具提示上限為 500 個字元。
• 功能橫幅的工具提示需要當地語系化。
• 尚不支援授權組合 (亦即在單一授權中涵蓋相同發行者的多個供應項目)。

相關內容

發佈 Power BI 自訂視覺效果 (部分機器翻譯)

更多問題嗎？ 嘗試在 Power BI 社群提問