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

  • Статья

При создании визуальных элементов 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: строковое значение идентификатора службы, созданного при настройке планов предложения в Центре партнеров (см. следующий пример). Screenshot showing an example of a Service ID string.

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

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

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

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

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

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

Пример вызова getAvailableServicePlans (с помощью идентификатора службы из приведенного выше изображения):

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

Общий значок, указывающий на отсутствие требуемой лицензии

Используйте notifyLicenseRequired вызов для LicenseNotificationType.General отображения значка в составе контейнера визуального элемента.
После активации значок будет сохранен на протяжении всего времени существования визуального элемента до clearLicenseNotification вызова или notifyLicenseRequired вызова.

Примечание.

Уведомление LicenseNotificationType.General применяется только при применении обоих вариантов: поддерживается для среды лицензирования и сценариев редактирования Power BI. Вызов этого в неподдерживаемой среде или когда отчет находится в режиме чтения или на панели мониторинга, не будет применять значок и возвращается false в ответе вызова.

Пример визуального отображения, содержащего общий значок "лицензии являются обязательными":

visual display containing the

visual display containing the

Наложение отображения визуального элемента с уведомлением о отсутствующих лицензиях

Используйте notifyLicenseRequired вызов для LicenseNotificationType.VisualIsBlocked наложения отображения визуального элемента с уведомлением о том, что визуальный элемент заблокирован, так как необходимые лицензии не найдены.
После активации это уведомление будет сохранено на протяжении всего времени существования визуального элемента до clearLicenseNotification вызова или notifyLicenseRequired вызова.

Пример визуального отображения, содержащего визуальное заблокированное уведомление. Power BI Desktop отображает только параметр "Получить лицензию ":

Visual display containing the *visual blocked* notification.

Наложение отображения визуального элемента с уведомлением о неподдерживаемой среде

Используйте notifyLicenseRequired вызов для LicenseNotificationType.UnsupportedEnv наложения отображения визуального элемента с уведомлением о том, что визуальный элемент заблокирован, так как Power BI в использовании не поддерживает управление лицензиями\принудительное применение.
После активации значок будет сохранен на протяжении всего времени существования визуального элемента до clearLicenseNotification вызова или notifyLicenseRequired вызова.

Примечание.

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

Пример визуального отображения, содержащего уведомление "Неподдерживаемая среда":

visual display containing the

Отображение баннера, уведомляющего о том, что не удалось применить функциональные возможности конкретного визуального элемента

При применении функциональных возможностей конкретного визуального элемента требуются отсутствующие лицензии, можно использовать notifyFeatureBlocked вызов, который будет всплывать баннер в составе контейнера визуального элемента. Баннер также поддерживает настраиваемую подсказку, которую можно задать и использовать для предоставления дополнительных сведений о функции, которая активировала уведомление.

Примечание.

Функция блокируется только при вызове в контексте поддерживаемой среды лицензирования и в случае, если блокировка наложений не применяется (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked). Вызов этого уведомления в неподдерживаемой среде не будет применять уведомление и возвращается false в ответе вызова.

Примечание.

Для поддержки локализованной среды Power BI рекомендуется поддерживать локализованные версии подсказки. Используйте API локализации для получения языка языкового стандарта Power BI.

После активации баннер будет отображаться в течение 10 секунд или до тех пор, пока не будет активирован другой баннер "функция заблокирован" или пока clearLicenseNotification не будет вызван (независимо от того, что происходит первым).

Пример визуального отображения, содержащего уведомление о "заблокированных функциях":

visual display containing the

Тестирование лицензированного визуального элемента

Чтобы протестировать лицензированный визуальный элемент перед тем, как сделать его общедоступным, выполните приведенные выше действия.

  • Если вы создаете новое предложение, добавьте визуальный элемент в качестве частного плана для тестовой учетной записи клиента. Предложение будет отображаться только для этой тестовой учетной записи для приобретения. Используйте эту учетную запись для проверки предложения перед тем, как сделать его общедоступным.
  • Если визуальный элемент уже доступен в AppSource и вы хотите обновить его до лицензированного визуального элемента, вы не можете сделать его частным планом , так как это будет скрывать визуальный элемент из AppSource, и у существующих пользователей нет доступа к нему. В настоящее время нет способа проверить опубликованный визуальный конец. Проверьте его так же, как вы проверили исходный визуальный элемент в AppSource, издеваясь над значением API лицензирования, чтобы проверка различных возможностей.

Рекомендации и ограничения

  • Подсказка для баннера функций ограничена 500 символами.
  • Подсказка для баннера компонентов требует локализации.
  • Объединение лицензий (т. е. одна лицензия, которая охватывает несколько предложений от одного издателя) пока не поддерживается.

Связанный контент

Публикация пользовательского визуального элемента Power BI

Есть еще вопросы? Задайте их в сообществе Power BI.