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 liées aux licences qui s’affichent 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é ci-dessous.

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 que les licences sont récupérées, elles sont mises en cache côté hôte Power BI pendant la session Power BI et tous les appels ultérieurs à la même opération retournent les 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. L’appel getAvailableServicePlans est donc 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 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 (à l’aide de l’ID de service de l’image ci-dessus) :

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

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

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 qu’elle clearLicenseNotification soit appelée.notifyLicenseRequired

Notes

La LicenseNotificationType.General notification est appliquée uniquement lorsque les deux s’appliquent : prise en charge pour l’environnement de licence et 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, la notification est conservée tout au long de la durée de vie du visuel jusqu’à ce que clearLicenseNotification ou notifyLicenseRequired 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 qu’elle clearLicenseNotification soit appelée.notifyLicenseRequired

Notes

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

Lorsque vous appliquez la fonctionnalité d’un visuel spécifique nécessite des licences manquantes, vous pouvez utiliser l’appel notifyFeatureBlocked qui affiche une bannière dans le conteneur du visuel. La bannière prend également en charge une info-bulle personnalisée qui peut être définie par vous et utilisée pour fournir des informations supplémentaires sur la fonctionnalité qui a déclenché la notification.

Notes

La fonctionnalité est bloquée notification est appliquée uniquement lorsqu’elle est appelée dans le contexte de l’environnement de licence pris en charge et en cas de blocage des superpositions ne sont pas appliquées (LicenseNotificationType.UnsupportedEnv,LicenseNotificationType.VisualIsBlocked ). L’appel dans un autre environnement n’applique pas la notification et retourne false la réponse de l’appel.

Notes

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 s’affiche pendant 10 secondes, ou jusqu’à ce que d’autres bannières « bloquées » soient déclenchées, ou jusqu’à ce qu’elle clearLicenseNotification soit appelée (ce qui vient 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 est uniquement visible sur ce compte de test pour un 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 en faire un plan privé, car cette action masque le visuel d’AppSource et vos utilisateurs existants n’y ont pas accès. 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 (c’est-à-dire une licence qui couvre plusieurs offres du même éditeur) n’est pas encore pris en charge.

Contenu connexe

Publier un visuel personnalisé Power BI

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