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

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

许可证强制实施过程

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

步骤	详细信息
在合作伙伴中心创建套餐	选择通过 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：在合作伙伴中心配置套餐计划时生成的服务 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）：

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>;
    }

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

在 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 个字符。
• 功能横幅的工具提示需要本地化。
• 尚不支持许可证捆绑（即一个许可证涵盖同一发布者的多个产品/服务）。

相关内容

发布 Power BI 自定义视觉对象

更多问题？ 尝试咨询 Power BI 社区