许可证和可效用性强制实施（公共预览版）

在 AppSource 上创建 Power BI 视觉对象以供下载时，现在可以使用 Microsoft 系统管理和强制执行其许可证。 最终用户可使用 Microsoft 365 管理中心等熟悉的工具分配和管理许可证，使用许可 API可以强制执行这些许可证，并确保只有获得许可的用户才能呈现视觉效果。

许可证强制实施过程

下表说明了通过 Microsoft 管理视觉对象许可证所涉及的步骤：

许可 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 主机端，并且对同一许可证的任何进一步调用都将返回缓存的数据。

TypeScript复制

export interface IVisualLicenseManager {
        getAvailableServicePlans(): IPromise;
    }

检索许可证操作可能需要较长的时间，因此 getAvailableServicePlans 调用是异步调用，应在代码中处理。
调用此方法，将返回 LicenseInfoResult 对象。

TypeScript复制

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

• plans - 活动用户为此视觉对象购买的一系列服务计划。 （响应中不包括为任何其他视觉对象购买的许可证。）
  ServicePlan 包含服务标识符 (spIdentifier) 及其状态 (ServicePlanState)。

• spIdentifier：在合作伙伴中心配置套餐计划时生成的服务 ID 的字符串值（请参阅以下示例）

• state - 枚举 (ServicePlanState)，表示已分配计划的状态。
  支持的服务计划状态：

  状态	描述
  非活动	指示许可证未激活，不得用于预配权益。
  活动	指示许可证已激活，可用于预配权益。
  警告	指示许可证可能因付款违规而处于宽限期。
  已挂起	指示许可证可能因付款违规而处于挂起状态。
  未知	Sentinel 值。

  只有“活动”状态和“警告”状态表示许可证可用。 所有其他状态都应被视为不产生可用的许可证。

• isLicenseUnsupportedEnv - 指示视觉对象正在不支持许可证管理或强制实施的 Power BI 环境中呈现。 目前，以下 Power BI 环境不支持许可证管理或许可证强制实施：

• Embedded - 发布到 Web、PaaS 嵌入

• 国家云（取决于对国家云中效用性的一般支持）

• RS Server（无计划内支持）

• 使用 REST API 导出 (PDF\PPT)

• isLicenseInfoAvailable - 指示是否可以检索许可证信息。 如果 Power BI Desktop 用户未登录或未连接到 Internet（脱机），则许可证检索可能会失败。 对于 Web，许可证检索可能会因临时服务中断而失败。

调用 getAvailableServicePlans 的示例（使用上图中的服务 ID）：

TypeScript复制

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 环境不支持许可证管理\强制实施

TypeScript复制

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

指示缺少必需许可证的常规图标

在 LicenseNotificationType.General 中调用 notifyLicenseRequired，以便将图标显示为视觉对象容器的一部分。
触发后，图标将在整个视觉对象的生存期内保留，直到 clearLicenseNotification 或 notifyLicenseRequired 被调用为止。

备注

LicenseNotificationType.General 通知仅在同时支持许可环境和 Power BI 编辑方案时，才强制实施。 在不支持的环境中或报表处于“读取”模式或仪表板中时，进行这种调用不会应用图标，并且将在调用的响应中返回 false。

包含“必需提供许可证”常规图标的视觉对象显示示例：

使用“缺少许可证”通知覆盖视觉对象显示

在 LicenseNotificationType.VisualIsBlocked 中调用 notifyLicenseRequired 来覆盖视觉对象的显示，并通知由于缺少必需的许可证而阻止了视觉对象。
触发后，通知将在整个视觉对象的生存期内保留，直到 clearLicenseNotification 或 notifyLicenseRequired 被调用为止。

包含“视觉对象被阻止”通知的视觉对象显示示例。 Power BI Desktop 将仅显示“获取许可证”选项：

使用“不受支持的环境”通知覆盖视觉对象的显示

在 LicenseNotificationType.UnsupportedEnv 中调用 notifyLicenseRequired 来覆盖视觉对象的显示，并通知视觉对象被阻止，因为正在使用的 Power BI 不支持许可证管理\强制实施。
触发后，图标将在整个视觉对象的生存期内保留，直到 clearLicenseNotification 或 notifyLicenseRequired 被调用为止。

备注

LicenseNotificationType.UnsupportedEnv 通知仅在许可环境不受支持的上下文中调用时才会强制执行。 在任何其他环境中进行此调用将不会应用通知，会在调用的响应中返回 false。

包含“不受支持的环境”通知的视觉对象显示示例：

显示通知无法应用特定视觉对象功能的横幅

应用特定视觉对象的功能需要缺少的许可证时，可以使用会弹出横幅的 notifyFeatureBlocked 调用作为视觉对象容器的一部分。 横幅还支持自定义工具提示，该工具提示可由你设置并用于提供有关触发通知的功能的其他信息。

备注

仅在以下情况下强制实施“功能被阻止”通知：在许可环境支持的上下文中调用此功能；未应用阻止覆盖（LicenseNotificationType.UnsupportedEnv、LicenseNotificationType.VisualIsBlocked）。 在不受支持的环境中进行此调用将不会应用通知，会在调用的响应中返回 false。

备注

为了支持本地化的 Power BI 环境，我们建议维护正在使用的工具提示的本地化版本。 请使用本地化 API 检索 Power BI 区域设置语言。

触发后，横幅将显示 10 秒，或者直到触发其他“功能被阻止”横幅，或者直到调用 clearLicenseNotification（以先发生者为准）。

包含“功能被阻止”横幅通知的视觉对象显示示例：

测试许可的视觉对象

若要在公开发布某个许可的视觉对象之前对其进行端到端测试，请执行以下操作：

• 如果你要创建全新的产品/服务，请将该视觉对象添加为测试客户帐户的专用计划。 只会在此测试帐户中显示该产品/服务供客户购买。 在公开发布该产品/服务之前使用此帐户对其进行验证。

• 如果视觉对象已在 AppSource 中提供，而你想要将其升级为许可的视觉对象，则不能将其设为专用计划，因为这会在 AppSource 中隐藏该视觉对象，现有用户无法访问它。 目前无法端到端测试已发布的视觉对象。 可以通过模拟许可 API 值以检查不同的可能性，像测试 AppSource 中的原始视觉对象一样测试已发布的视觉对象。

注意事项和限制

• 功能横幅的工具提示限制为 500 个字符。

• 功能横幅的工具提示需要本地化。