Принудительное применение лицензий и транзакций (общедоступная предварительная версия)

При создании визуальных элементов Power BI для скачивания в AppSource теперь можно управлять и применять свои лицензии с помощью систем Майкрософт. Конечный пользователь назначает лицензии и управляет ими с помощью знакомых инструментов, таких как Центр администрирования Microsoft 365, и API лицензирования позволяет применять эти лицензии и гарантировать, что только лицензированные пользователи могут отображать визуальные элементы.

Процесс принудительного применения лицензий

В следующей таблице показаны шаги, связанные с управлением визуальными лицензиями через Корпорацию Майкрософт:

Этап	Сведения
Создание предложения в Центре партнеров	Выберите транзакцию через систему коммерции Майкрософт. Разрешить корпорации Майкрософт управлять лицензиями. Задайте цены и доступность.
Добавление принудительного применения лицензий в визуальный пакет 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 и уведомляют пользователя о том, что им нужно приобрести отсутствующие лицензии. Визуальный элемент не должен отображать собственный пользовательский интерфейс лицензирования, а использовать одно из поддерживаемых предварительно определенных уведомлений Power BI, как описано в следующих разделах.

Дополнительные сведения о лицензировании Power BI см. в статье о применении лицензий.

Примечание.

API лицензирования доступен в версии 4.7. Чтобы узнать, какая версия используется, проверьте apiVersion файл pbiviz.json .

Получение планов обслуживания визуального элемента, назначенных активному пользователю

Чтобы получить назначенные планы обслуживания, добавьте вызов 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: строковое значение идентификатора службы, созданного при настройке планов предложения в Центре партнеров (см. следующий пример).

  • состояние — перечисление (ServicePlanState), представляющее состояние назначенных планов.
    Поддерживаемые состояния плана обслуживания:

    State	Description
    Неактивное	Указывает, что лицензия не активна и не должна использоваться для получения преимуществ подготовки.
    Активно	Указывает, что лицензия активна и может использоваться для получения преимуществ подготовки.
    Предупреждение	Указывает, что лицензия находится в льготном периоде, вероятно, из-за нарушения оплаты.
    Приостановлена	Указывает, что лицензия приостановлена, скорее всего, из-за нарушения оплаты.
    Неизвестно	Значение Microsoft Sentinel.

    Только активные и предупреждающие состояния представляют собой доступную лицензию. Все остальные государства должны рассматриваться как не связанные с использованием лицензии.

• isLicenseUnsupportedEnv — указывает, что визуальный элемент отрисовывается в среде Power BI, которая не поддерживает управление лицензиями или принудительное применение. В настоящее время следующие среды Power BI не поддерживают управление лицензиями или применение лицензий.

  • Embedded — публикация в Интернете, внедрение PaaS
  • Национальные или региональные облака (зависит от общей поддержки трансактируемости в национальных или региональных облаках)
  • RS Server (без плановой поддержки)
  • Экспорт (PDF\PPT) с помощью REST API

• isLicenseInfoAvailable — указывает, можно ли получить сведения о лицензиях. Сбой при получении лицензий может произойти, если пользователь Power BI Desktop не вошел в систему или не подключен к Интернету (в автономном режиме). Для интернета получение лицензий может завершиться сбоем из-за временного сбоя службы.

Пример вызова 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.