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

當您在 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	Microsoft Sentinel 值。

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

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

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

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

呼叫 getAvailableServicePlans 以擷取此視覺效果之用戶服務方案的範例：

private currentUserValidPlans: ServicePlan[] | undefined;
private hasServicePlans: boolean | undefined;
private isLicenseUnsupportedEnv: boolean | undefined;

this.licenseManager.getAvailableServicePlans()
 .then(({ plans, isLicenseUnsupportedEnv, isLicenseInfoAvailable }: LicenseInfoResult) => {
  if (isLicenseInfoAvailable && !isLicenseUnsupportedEnv) {
   this.currentUserValidPlans = plans?.filter(({ spIdentifier, state }) => 
    (state === powerbi.ServicePlanState.Active || state === powerbi.ServicePlanState.Warning)
   );
   this.hasServicePlans = !!currentUserValidPlans?.length;
  }
  this.isLicenseUnsupportedEnv = isLicenseUnsupportedEnv;
 }).catch((err) => {
  this.currentUserValidPlans = undefined;
  this.hasServicePlans = undefined;
  console.log(err);
 });

注意

此範例只會示範如何驗證使用者是否具有此視覺效果的有效方案。 plans數位可能包含不同的spIdentifier值，而且每個標識元可以顯示多個具有不同狀態。

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

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

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

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

呼叫 notifyLicenseRequired的範例：

private defaultNotificationType: powerbi.LicenseNotificationType = powerbi.LicenseNotificationType.General;
private isNotificaitonDisplayed: boolean = false;

if (!this.isNotificaitonDisplayed) {
    const notificationType = this.isLicenseUnsupportedEnv ? powerbi.LicenseNotificationType.UnsupportedEnv : this.defaultNotificationType
    this.licenseManager.notifyLicenseRequired(this.getNotificationType())
        .then((value) => {
            this.isNotificaitonDisplayed = value;
        }).catch((err) => {
            console.log(err);
        });
}

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

使用 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 社群提問