Application des licences et de la transaction (préversion publique)

Lorsque vous créez des visuels Power BI à télécharger sur AppSource, vous pouvez désormais gérer et appliquer leurs licences à l’aide de systèmes Microsoft. L’utilisateur final affecte et gère les licences à l’aide d’outils familiers tels que Centre d'administration Microsoft 365, et l’API de gestion des licences vous permet d’appliquer ces licences et de s’assurer que seuls les utilisateurs sous licence peuvent afficher les visuels.

Processus d’application de licence

Le tableau suivant illustre les étapes de gestion de vos licences visuelles via Microsoft :

API de licence

L’API de gestion des licences permet aux développeurs visuels Power BI d’appliquer des licences visuelles Power BI. L’API prend en charge la récupération des informations sur les licences visuelles Power BI affectées à l’utilisateur Power BI. Il permet également de déclencher les notifications associées aux licences qui apparaissent sur le visuel Power BI et d’informer l’utilisateur qu’il doit acheter les licences manquantes. Le visuel ne doit pas afficher son propre expérience utilisateur de licence, à la place utiliser l’une des notifications prédéfinies prises en charge par Power BI, comme indiqué dans les sections suivantes.

En savoir plus sur la gestion des licences Power BI, consultez l’application des licences.

Récupérer les plans de service du visuel affectés à l’utilisateur actif

Pour obtenir les plans de service affectés, ajoutez un appel à getAvailableServicePlans (disponible via IVisualLicenseManager). Du point de vue des performances, essayez d’extraire les licences une seule fois, de préférence dans les constructorinit appels, puis enregistrez le résultat.
Une fois les licences récupérées, elles sont mises en cache côté hôte Power BI pendant la session Power BI et tous les autres appels au même retour des données mises en cache.

export interface IVisualLicenseManager {
        getAvailableServicePlans(): IPromise<powerbi.extensibility.visual.LicenseInfoResult>;
    }

La récupération des licences peut être une longue opération. Par conséquent, l’appel getAvailableServicePlans est un appel asynchrone et doit être géré comme tel dans votre code.
En réponse à l’appel de la méthode, LicenseInfoResult l’objet est retourné.

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

• plans : tableau de plans de service achetés par l’utilisateur actif pour ce visuel. (Les licences achetées pour d’autres visuels ne sont pas incluses dans la réponse.)
  Un ServicePlan contient l’identificateur de service (spIdentifier) et son état (ServicePlanState).

  • spIdentifier : la valeur de la chaîne de l'ID de service générée lorsque vous configurez les plans de votre offre dans Partner Center (voir l'exemple suivant)

  • state : énumération (ServicePlanState) qui représente l’état des plans affectés.
    États du plan de service pris en charge :

    State	Description
    Inactif	Indique que la licence n’est pas active et ne doit pas être utilisée pour les avantages de l’approvisionnement.
    Actif	Indique que la licence est active et peut être utilisée pour les avantages de l’approvisionnement.
    Avertissement	Indique que la licence est en période de grâce probablement en raison d’une violation de paiement.
    Interrompu	Indique que la licence est suspendue probablement en raison d'une violation de paiement.
    Unknown	Valeur Microsoft Sentinel.

    Seuls les états actifs et d’avertissement représentent une licence utilisable. Tous les autres états doivent être traités comme ne produisant pas de licence utilisable.

• isLicenseUnsupportedEnv : indique que le visuel est affiché dans un environnement Power BI qui ne prend pas en charge la gestion ou l’application des licences. Actuellement, les environnements Power BI suivants ne prennent pas en charge la gestion des licences ou l’application des licences :

  • Incorporé - Publier sur le web, incorporation PaaS
  • Clouds nationaux/régionaux (dépend de la prise en charge générale de la transaction dans les clouds nationaux/régionaux)
  • Serveur RS (aucune prise en charge planifiée)
  • Exportation (PDF\PPT) à l’aide de l’API REST

• isLicenseInfoAvailable - Indique si les informations de licence peuvent être récupérées. L’échec de la récupération des licences peut se produire si Power BI Desktop’utilisateur n’est pas connecté ou n’est pas connecté à Internet (hors connexion). Pour le web, la récupération des licences peut échouer en raison d’une panne de service temporaire.

Exemple d’appel getAvailableServicePlans pour récupérer les plans de service de l’utilisateur pour ce visuel :

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

Avertir l’utilisateur que les licences requises sont manquantes

La plateforme Power BI fournit plusieurs expériences prêtes à l’emploi qui peuvent être utilisées pour notifier :

• Les licences doivent être achetées pour bénéficier des fonctionnalités complètes du visuel
• La fonctionnalité d’un visuel particulier est bloquée en raison de licences manquantes
• L’intégralité du visuel est bloquée en raison de licences manquantes
• L’intégralité du visuel est bloquée, car l’environnement Power BI en cours d’utilisation ne prend pas en charge la gestion des licences\application

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

Exemple d’appel 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);
        });
}

Icône générale indiquant qu’une licence requise est manquante

Utilisez l’appel notifyLicenseRequired avec LicenseNotificationType.General pour afficher une icône dans le conteneur du visuel.
Une fois déclenchée, l’icône est conservée tout au long de la durée de vie du visuel jusqu’à ce notifyLicenseRequired qu’elle clearLicenseNotification soit appelée.

Exemple d’affichage visuel contenant l’icône générale « Licences requises » :

Superposer l’affichage du visuel avec une notification de licence manquante

Utilisez l’appel notifyLicenseRequired avec LicenseNotificationType.VisualIsBlocked pour superposer l’affichage du visuel avec une notification indiquant que le visuel est bloqué, car les licences requises ont été trouvées manquantes.
Une fois déclenchée, cette notification est conservée tout au long de la durée de vie du visuel jusqu’à ce notifyLicenseRequired qu’elle clearLicenseNotification soit appelée.

Exemple d’affichage visuel contenant la notification bloquée visuelle . Power BI Desktop affiche uniquement l’option Obtenir une licence :

Superposer l’affichage du visuel avec une notification d’environnement non prise en charge

Utilisez l’appel notifyLicenseRequired avec LicenseNotificationType.UnsupportedEnv pour superposer l’affichage du visuel avec une notification indiquant que le visuel est bloqué, car Power BI en cours d’utilisation ne prend pas en charge la gestion des licences\application.
Une fois déclenchée, l’icône est conservée tout au long de la durée de vie du visuel jusqu’à ce notifyLicenseRequired qu’elle clearLicenseNotification soit appelée.

Exemple d’affichage visuel contenant la notification « Environnement non pris en charge » :

Afficher une bannière indiquant que la fonctionnalité d’un visuel spécifique n’a pas pu être appliquée

Lors de l’application de la fonctionnalité d’un visuel spécifique nécessite des licences manquantes, vous pouvez utiliser l’appel notifyFeatureBlocked qui affiche une bannière contextuelle dans le cadre du conteneur du visuel. La bannière prend également en charge une info-bulle personnalisée que vous pouvez définir et utiliser pour fournir des informations supplémentaires sur la fonctionnalité qui a déclenché la notification.

Une fois déclenchée, la bannière est affichée pendant 10 secondes, ou jusqu’à ce que d’autres bannières « fonctionnalité bloquée » soient déclenchées, ou jusqu’à ce qu’elle clearLicenseNotification soit appelée (ce qui arrive en premier).

Exemple d’affichage visuel contenant la notification de bannière « caractéristique bloquée » :

Tester un visuel sous licence

Pour tester un visuel sous licence de bout en bout avant de le rendre public :

• Si vous créez une toute nouvelle offre, ajoutez le visuel en tant que plan privé pour un compte client de test. L’offre n’est visible que par ce compte de test pour l’achat. Utilisez ce compte pour valider l’offre avant de la rendre publique.
• Si votre visuel est déjà disponible dans AppSource et que vous souhaitez le mettre à niveau vers un visuel sous licence, vous ne pouvez pas le rendre privé , car cela masque le visuel à partir d’AppSource et vos utilisateurs existants n’ont pas accès à celui-ci. Il n’existe actuellement aucun moyen de tester un visuel publié de bout en bout. Testez-le de la même façon que vous avez testé le visuel d’origine sur AppSource, en imitant la valeur de l’API de licence pour vérifier les différentes possibilités.

Considérations et limitations

• L’info-bulle pour la bannière de fonctionnalité est limitée à 500 caractères.
• L’info-bulle pour la bannière de fonctionnalité nécessite la localisation.
• Le regroupement de licences (autrement dit, une licence qui couvre plusieurs offres du même éditeur) n’est pas encore prise en charge.

Contenu connexe

Publier un visuel personnalisé Power BI

D’autres questions ? Essayez d’interroger la communauté Power BI