Erzwingen von Lizenzierung und Transaktionsfähigkeit (Public Preview)

  • Artikel

Wenn Sie Power BI-Visualisierungen zum Herunterladen in AppSource erstellen, können Sie deren Lizenzen jetzt mithilfe von Microsoft-Systemen verwalten und erzwingen. Endbenutzer*innen nutzen für das Zuweisen und Verwalten von Lizenzen vertraute Tools wie das Microsoft 365 Admin Center, und mit der Lizenzierungs-API können Sie diese Lizenzen erzwingen und damit sicherstellen, dass nur lizenzierte Benutzer*innen die Visuals rendern können.

Prozess der Lizenzerzwingung

In der folgenden Tabelle werden die Schritte gezeigt, die beim Verwalten der Lizenzen Ihrer Visuals über Microsoft erforderlich sind:

Schritt Details
Erstellen eines Angebots im Partner Center Wählen Sie die Transaktion über das Microsoft Commerce-System aus. Aktivieren Sie die Lizenzverwaltung über Microsoft. Legen Sie die Preise und Verfügbarkeit fest.
Hinzufügen der Lizenzerzwingung zu Ihrem Power BI-Visualpaket Erstellen Sie Ihr Paket, oder konfigurieren Sie es neu, um die Power BI-Laufzeitlizenz zu verwenden, mit der die Lizenzierung entsprechend dem Zugriff aller Benutzer*innen erzwungen wird.
Kund*innen entdecken Ihr Angebot in AppSource und erwerben ein Abonnement Wenn Kund*innen Ihr Angebot in AppSource erwerben, erhalten sie auch Lizenzen für das Power BI-Visual.
Kund*innen verwalten ihre Abonnements und weisen Benutzerlizenzen zu bzw. heben die Zuweisung auf Kund*innen verwalten Abonnements und weisen Lizenzen für diese Visuals und Angebote im Microsoft 365 Admin Center zu. Die Vorgehensweise ist mit der für alle anderen Abonnements wie Office oder Power BI identisch.
Erzwingen von Laufzeitüberprüfungen Bieten Sie Ihren Kunden eine einheitliche Erfahrung, indem Sie unsere vordefinierten APIs verwenden, um zur Laufzeit Lizenzüberprüfungen zu erzwingen.
Anzeigen von Berichten zum Fördern des Wachstums Sammeln Sie Erkenntnisse zu Einnahmen, Auszahlungsinformationen und Bestell- und Lizenzdetails. Zeigen Sie Informationen zu Lizenzen und Bestellungen an, die im Lauf der Zeit und nach Geografie erworben, erneuert und storniert wurden.

Lizenzierungs-API

Die Lizenzierungs-API ermöglicht Entwickler*innen von Power BI-Visuals, Power BI-Visuallizenzen zu erzwingen. Die API unterstützt das Abrufen von Informationen zu Power BI-Visuallizenzen, die Power BI-Benutzer*innen zugewiesen sind. Sie ermöglicht außerdem das Auslösen von Benachrichtigungen zur Lizenz, die im Power BI-Visual angezeigt werden und Benutzer*innen darüber informieren, dass fehlende Lizenzen erworben werden müssen. Das Visual sollte keine eigene Benutzeroberfläche für die Lizenzierung anzeigen, sondern stattdessen von Power BI unterstützte vordefinierte Benachrichtigungen wie unten beschrieben verwenden.

Weitere Informationen zur Power BI-Lizenzierung finden Sie unter Lizenzerzwingung.

Hinweis

Die Lizenzierungs-API ist ab Version 4.7 verfügbar. Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die apiVersion in der Datei pbiviz.json.

Abrufen von Dienstplänen für Visuals, die der oder dem aktiven Benutzer*in zugewiesen sind

Um Dienstpläne zuzuweisen, fügen Sie einen Anruf von getAvailableServicePlans hinzu (verfügbar über IVisualLicenseManager). Aus Gründen der Leistung sollten Sie versuchen, die Lizenzen nur einmal abzurufen, vorzugsweise in den Aufrufen von constructor oder init, und das Ergebnis dann zu speichern.
Nachdem die Lizenzen abgerufen wurden, werden sie während der Power BI-Sitzung auf dem Power BI-Host zwischengespeichert. Bei nachfolgenden identischen Aufrufen werden dann die zwischengespeicherten Daten zurückgegeben.

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

Das Abrufen der Lizenzen kann sehr lange dauern, daher ist der Aufruf von getAvailableServicePlans asynchron und sollte in Ihrem Code auch so behandelt werden.
Als Antwort auf das Aufrufen der Methode wird das LicenseInfoResult-Objekt zurückgegeben.

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

  • plans ist ein Array von Dienstplänen (ServicePlan), die von dem oder der aktiven Benutzer*in für dieses Visual erworben wurden. (Lizenzen, die für andere Visuals erworben wurden, sind nicht in der Antwort enthalten.)
    Ein Dienstplan enthält den Dienstbezeichner (spIdentifier) und seinen Status (ServicePlanState).

    • spIdentifier: Der Zeichenfolgenwert der Dienst-ID, die generiert wird, wenn Sie die Pläne Ihres Angebots im Partner Center konfigurieren (siehe das folgende Beispiel) Screenshot showing an example of a Service ID string.

    • state ist eine Enumeration (ServicePlanState), die den Status der zugewiesenen Pläne angibt.
      Unterstützte Dienstplanzustände:

      State Beschreibung
      Inaktiv Gibt an, dass die Lizenz nicht aktiv ist und nicht für die Bereitstellung verwendet werden sollte.
      Aktiv Gibt an, dass die Lizenz aktiv ist und für die Bereitstellung verwendet werden kann.
      Warnung Gibt an, dass die Lizenz wahrscheinlich aufgrund eines Zahlungsverstoßes in der Karenzzeit liegt.
      Ausgesetzt Gibt an, dass die Lizenz wahrscheinlich aufgrund eines Zahlungsverstoßes deaktiviert ist.
      Unbekannt Sentinel-Wert.

      Nur die Zustände Aktiv und Warnung stellen eine verwendbare Lizenz dar. Bei allen anderen Zustände sollte die Lizenz als nicht verwendbar behandelt werden.

  • isLicenseUnsupportedEnv gibt an, dass das Visual in einer Power BI-Umgebung gerendert wird, die keine Verwaltung oder Erzwingung von Lizenzen unterstützt. Derzeit unterstützen die folgenden Power BI-Umgebungen keine Lizenzverwaltung oder -erzwingung:

    • Eingebettet: „Im Web veröffentlichen“, PaaS-Einbettung
    • Nationale/regionale Clouds (hängt von der allgemeinen Unterstützung für die Transaktionsfähigkeit in nationalen/regionalen Clouds ab)
    • RS-Server (keine Unterstützung geplant)
    • Exportieren (PDF/PPT) mithilfe der REST-API

  • isLicenseInfoAvailable gibt an, ob die Lizenzinformationen abgerufen werden können. Fehler beim Abrufen von Lizenzen können auftreten, wenn die Power BI Desktop-Benutzer*innen nicht angemeldet oder nicht mit dem Internet verbunden (offline) ist. Bei Weblizenzen kann der Abruf aufgrund eines temporären Dienstausfalls zu Fehlern führen.

Beispiel für den Aufruf von getAvailableServicePlans (Dienst-ID aus der obigen Abbildung):

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

Benachrichtigen von Benutzer*innen über das Fehlen erforderlicher Lizenzen

Die Power BI-Plattform bietet mehrere vordefinierte Möglichkeiten für Benachrichtigungen:

  • Lizenzen sollten erworben werden, um alle Funktionen des Visuals nutzen zu können.
  • Ein Feature eines bestimmten Visuals wird aufgrund fehlender Lizenzen blockiert.
  • Ein vollständiges Visual wird aufgrund fehlender Lizenzen blockiert.
  • Ein vollständiges Visual wird blockiert, da die verwendete Power BI-Umgebung die Lizenzverwaltung\-erzwingung nicht unterstützt.
export interface IVisualLicenseManager {
        notifyLicenseRequired(notificationType: LicenseNotificationType): IPromise<boolean>;
        notifyFeatureBlocked(tooltip: string): IPromise<boolean>;
        clearLicenseNotification(): IPromise<boolean>;
    }

Allgemeines Symbol für das Fehlen einer erforderlichen Lizenz

Verwenden Sie einen Aufruf von notifyLicenseRequired mit LicenseNotificationType.General, um ein Symbol als Teil des Visualcontainers anzuzeigen.
Nach dem Auslösen wird das Symbol während der gesamten Lebensdauer des Visuals beibehalten, bis clearLicenseNotification oder notifyLicenseRequired aufgerufen werden.

Hinweis

Die Benachrichtigung LicenseNotificationType.General wird nur erzwungen, wenn die beiden folgenden Bedingungen erfüllt sind: eine Lizenzierungsumgebung und Power BI-Bearbeitungsszenarien werden unterstützt. Wenn der Aufruf in einer nicht unterstützten Umgebung erfolgt oder wenn sich der Bericht im Lesemodus oder im Dashboard befindet, wird das Symbol nicht angewandt, und in der Antwort auf den Aufruf wird false zurückgegeben.

Beispiel für ein Visual mit dem allgemeinen Symbol für erforderliche Lizenzen:

visual display containing the

visual display containing the

Überlagern der Anzeige von Visuals mit einer Benachrichtigung über fehlende Lizenzen

Verwenden Sie einen Aufruf von notifyLicenseRequired mit LicenseNotificationType.VisualIsBlocked, um die Anzeige eines Visuals mit einer Benachrichtigung zu überlagern, dass das Visual blockiert wird, da erforderliche Lizenzen fehlen.
Nach dem Auslösen wird diese Benachrichtigung während der gesamten Lebensdauer des Visuals beibehalten, bis clearLicenseNotification oder notifyLicenseRequired aufgerufen werden.

Beispiel für die Anzeige eines Visuals mit der Benachrichtigung über die Blockierung. In Power BI Desktop wird nur die Option Lizenz erwerben angezeigt:

Visual display containing the *visual blocked* notification.

Überlagern der Anzeige von Visuals mit einer Benachrichtigung über eine nicht unterstützte Umgebung

Verwenden Sie einen Aufruf von notifyLicenseRequired mit LicenseNotificationType.UnsupportedEnv, um die Anzeige eines Visuals mit einer Benachrichtigung zu überlagern, dass das Visual blockiert wird, da die verwendete Power BI-Version nicht das Verwalten\Erzwingen von Lizenzen unterstützt.
Nach dem Auslösen wird das Symbol während der gesamten Lebensdauer des Visuals beibehalten, bis clearLicenseNotification oder notifyLicenseRequired aufgerufen werden.

Hinweis

Die Benachrichtigung LicenseNotificationType.UnsupportedEnv wird nur erzwungen, wenn sie im Kontext einer Umgebung ohne Unterstützung für die Lizenzierung aufgerufen wird. Bei einem Aufruf in einer anderen Umgebung wird die Benachrichtigung nicht angewandt, und in der Antwort auf den Aufruf wird false zurückgegeben.

Beispiel für die Anzeige eines Visuals mit der Benachrichtigung über eine „nicht unterstützte Umgebung“:

visual display containing the

Anzeigen eines Banners mit der Benachrichtigung, dass die Funktionalität eines bestimmten Visuals nicht angewandt werden konnte

Wenn beim Anwenden der Funktionalität eines bestimmten Visuals erforderliche Lizenzen nicht gefunden wurden, können Sie einen von Aufruf notifyFeatureBlocked verwenden, um ein Banner als Teil des Visualcontainers anzuzeigen. Das Banner unterstützt auch eine benutzerdefinierte QuickInfo, die von Ihnen festgelegt werden kann, um zusätzliche Informationen zu dem Feature bereitzustellen, das die Benachrichtigung ausgelöst hat.

Hinweis

Die Benachrichtigung über ein blockiertes Feature wird nur erzwungen, wenn der Aufruf in einer Umgebung mit Unterstützung für die Lizenzierung erfolgt und in Fällen, in denen Überlagerungen zur Blockierung nicht angewandt werden (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked). Bei einem Aufruf dieser Benachrichtigung in einer nicht unterstützten Umgebung wird sie nicht angewandt, und in der Antwort auf den Aufruf wird false zurückgegeben.

Hinweis

Für die Unterstützung lokalisierter Power BI-Umgebung wird empfohlen, lokalisierte Versionen der QuickInfos bereitzustellen. Verwenden Sie die Lokalisierungs-API, um die Sprache des Power BI-Gebietsschemas abzurufen.

Nachdem das Banner ausgelöst wurde, wird es für 10 Sekunden angezeigt oder bis ein anderes Banner für ein blockiertes Feature ausgelöst wird oder bis clearLicenseNotification aufgerufen wird (je nachdem, was zuerst eintritt).

Beispiel für die Anzeige eines Visuals mit einer Bannerbenachrichtigung über ein blockiertes Feature:

visual display containing the

Testen eines lizenzierten Visuals

So testen Sie ein lizenziertes Visual Ende-zu-Ende, bevor Sie es öffentlich verfügbar machen:

  • Wenn Sie ein brandneues Angebot erstellen, fügen Sie das Visual als privaten Plan für ein Testkundenkonto hinzu. Das Angebot wird nur für dieses Testkonto sichtbar sein. Verwenden Sie dieses Konto, um das Angebot zu überprüfen, bevor Sie es veröffentlichen.
  • Wenn Ihr Visual bereits in AppSource verfügbar ist und Sie es zu einem lizenzierten Visual upgraden möchten, können Sie es nicht zu einem privaten Plan machen, denn dann wird das Visual vor AppSource versteckt und Ihre bestehenden Benutzer haben keinen Zugriff darauf. Es gibt derzeit keine Möglichkeit, ein veröffentlichtes Visual Ende-zu-Ende zu testen. Testen Sie es auf dieselbe Weise, wie Sie das ursprüngliche Visual für AppSource getestet haben, indem Sie den Wert der Lizenzierungs-API nachbilden, um die verschiedenen Möglichkeiten zu prüfen.

Überlegungen und Einschränkungen

  • Die QuickInfo für Featurebanner ist auf 500 Zeichen begrenzt.
  • Die QuickInfo für Featurebanner erfordert eine Lokalisierung.
  • Lizenzbündelung (d. h. eine Lizenz, die mehrere Angebote desselben Herausgebers abdeckt) wird noch nicht unterstützt.

Zugehöriger Inhalt

Erstellen eines benutzerdefinierten Visuals für Power BI

Weitere Fragen? Stellen Sie Ihre Frage in der Power BI-Community.