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 :

Étape	Détails
Créer une offre dans l’Espace partenaires	Choisissez d’effectuer des transactions via le système de commerce Microsoft. Permettre à Microsoft de gérer les licences. Définir la tarification et la disponibilité.
Ajouter l’application des licences à votre package visuel Power BI	Créez ou reconfigurez votre package pour utiliser la licence d’exécution Power BI, qui applique la licence en fonction de l’accès de chaque utilisateur.
Les clients découvrent votre offre dans AppSource et achètent un abonnement	Lorsque les clients achètent votre offre dans AppSource, ils obtiennent également des licences pour le visuel Power BI.
Les clients gèrent leurs abonnements et attribuent/annulent l’attribution de licences utilisateur	Les clients gèrent les abonnements et attribuent des licences pour ces visuels et offres dans le Centre d'administration Microsoft 365, comme ils le font pour n’importe quel autre abonnement tel qu’Office ou Power BI.
Appliquer des vérifications d’exécution	Offrez à vos clients une expérience uniforme en utilisant nos API prêtes à l’emploi pour appliquer des vérifications de licence d’exécution.
Afficher les rapports sur la croissance du carburant	Obtenez des informations sur les revenus, les informations de paiement et les détails de la commande et de la licence. Affichez des informations sur les licences et commandes achetées, renouvelées et annulées au fil du temps et par zone géographique.

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.

Notes

L’API d’autorisation est disponible à compter de la version 4.7. Pour savoir quelle version vous utilisez, consultez le apiVersion fichier pbiviz.json .

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

Remarque

Cet exemple montre uniquement comment vérifier si l’utilisateur a des plans valides pour ce visuel. Le plans tableau peut contenir des valeurs différentes spIdentifier , et chaque identificateur peut apparaître plusieurs fois avec des états différents.

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.

Remarque

La LicenseNotificationType.General notification est appliquée uniquement à partir d’un environnement qui prend en charge la gestion des licences et pour les scénarios de modification Power BI. L’appel dans un environnement non pris en charge ou lorsque le rapport est en mode Lecture ou dans le tableau de bord n’applique pas l’icône et retourne false dans la réponse de l’appel.

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.

Remarque

La notification LicenseNotificationType.UnsupportedEnv est appliquée uniquement lorsqu’elle est appelée dans le contexte d’un environnement de licence non pris en charge. L’appel dans un autre environnement n’applique pas la notification et retourne false la réponse de l’appel.

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.

Remarque

La fonctionnalité est bloquée notification est appliquée uniquement lorsque les deux conditions suivantes s’appliquent :

• Elle est appelée à partir d’un environnement de licence pris en charge
• Les superpositions bloquantes ne sont pas appliquées (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

L’appel de cette notification dans un environnement non pris en charge n’applique pas la notification et retourne false dans la réponse de l’appel.

Remarque

Pour prendre en charge l’environnement Power BI localisé, nous vous recommandons de maintenir les versions localisées des info-bulles utilisées. Utilisez l’API de localisation pour récupérer la langue des paramètres régionaux Power BI.

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