许可证和可效用性强制实施（公共预览版）
在 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)，表示已分配计划的状态。
支持的服务计划状态：状态 描述 非活动 指示许可证未激活，不得用于预配权益。 活动 指示许可证已激活，可用于预配权益。 警告 指示许可证可能因付款违规而处于宽限期。 已挂起 指示许可证可能因付款违规而处于挂起状态。 未知 Microsoft Sentinel 值。 只有“活动”状态和“警告”状态表示许可证可用。 所有其他状态都应被视为不产生可用的许可证。
isLicenseUnsupportedEnv- 指示视觉对象正在不支持许可证管理或强制实施的 Power BI 环境中呈现。 目前，以下 Power BI 环境不支持许可证管理或许可证强制实施：- Embedded - 发布到 Web、PaaS 嵌入
- 国家/区域云（取决于对国家/区域云中效用性的一般支持）
- RS Server（无计划内支持）
- 使用 REST API 导出 (PDF\PPT)
isLicenseInfoAvailable- 指示是否可以检索许可证信息。 如果 Power BI Desktop 用户未登录或未连接到 Internet（脱机），则许可证检索可能会失败。 对于 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);
});
}
指示缺少必需许可证的常规图标
在 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 社区