Erzwingen von Lizenzierung und Transaktionsfähigkeit (Public Preview)

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 der lizenzierungsbezogenen Benachrichtigungen, die im Power BI-Visual angezeigt werden, und informiert den Benutzer darüber, dass er die fehlenden Lizenzen erwerben muss. Das visuelle Element sollte keine eigene Lizenzierungs-UX anzeigen, sondern eine von Power BI unterstützte vordefinierte Benachrichtigungen verwenden, wie in den folgenden Abschnitten beschrieben.

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.
Sobald Lizenzen abgerufen wurden, werden sie während der Power BI-Sitzung auf der Power BI-Hostseite zwischengespeichert und alle weiteren Aufrufe desselben geben die zwischengespeicherten Daten zurück.

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

Das Abrufen der Lizenzen kann ein langer Vorgang sein, daher ist der getAvailableServicePlans Aufruf ein asynchroner Aufruf und sollte in Ihrem Code 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)

  • 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	Microsoft 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 getAvailableServicePlans zum Abrufen der Dienstpläne des Benutzers für dieses visuelle Element:

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

Hinweis

In diesem Beispiel wird nur veranschaulicht, wie sie überprüfen können, ob der Benutzer über gültige Pläne für dieses visuelle Element verfügt. Das plans Array kann unterschiedliche spIdentifier Werte enthalten, und jeder Bezeichner kann mehrmals mit unterschiedlichen Zuständen angezeigt werden.

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

Beispiel für einen Aufruf 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);
        });
}

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 visuellen Elements beibehalten, bis clearLicenseNotification es notifyLicenseRequired aufgerufen wird.

Hinweis

Die LicenseNotificationType.General Benachrichtigung wird nur aus einer Umgebung erzwungen, die die Lizenzierungsverwaltung und für Power BI-Bearbeitungsszenarien unterstützt. Wenn sie in einer nicht unterstützten Umgebung aufgerufen wird oder sich der Bericht im Lesemodus oder im Dashboard befindet, wird das Symbol nicht angewendet und in der Antwort des Anrufs zurückgegeben false .

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

Ü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 visuellen Elements beibehalten, bis clearLicenseNotification sie notifyLicenseRequired aufgerufen werden.

Beispiel für die Anzeige eines Visuals mit der Benachrichtigung über die Blockierung. Power BI Desktop zeigt nur die Option "Lizenz abrufen" an:

Ü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 visuellen Elements beibehalten, bis clearLicenseNotification es notifyLicenseRequired aufgerufen wird.

Hinweis

Die Benachrichtigung LicenseNotificationType.UnsupportedEnv wird nur erzwungen, wenn sie im Kontext einer Umgebung ohne Unterstützung für die Lizenzierung aufgerufen wird. Wenn Sie dies in einer anderen Umgebung aufrufen, wird die Benachrichtigung nicht angewendet und in der Antwort des Anrufs zurückgegeben false .

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

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

Bei der Anwendung der Funktionalität eines bestimmten visuellen Elements sind Lizenzen erforderlich, die nicht gefunden wurden, können Sie den Aufruf verwenden, der notifyFeatureBlocked ein Popupbanner als Teil des Containers des visuellen Elements anzeigt. Das Banner unterstützt auch eine benutzerdefinierte QuickInfo, die Sie festlegen und verwenden können, um zusätzliche Informationen zu dem Feature bereitzustellen, das die Benachrichtigung ausgelöst hat.

Hinweis

Das Feature wird nur erzwungen, wenn beide folgenden Bedingungen gelten:

• Es wird von einer unterstützten Lizenzierungsumgebung aufgerufen.
• Blockierungsüberlagerungen werden nicht angewendet (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

Wenn Sie diese Benachrichtigung in einer nicht unterstützten Umgebung aufrufen, wird die Benachrichtigung nicht angewendet und in der Antwort des Anrufs zurückgegeben false .

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.

Nach dem Auslösen wird das Banner 10 Sekunden lang oder bis ein anderes Banner "Feature blockiert" ausgelöst wird, oder bis clearLicenseNotification es aufgerufen wird (was zuerst kommt).

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

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 ist nur für dieses Testkonto für den Kauf sichtbar. Verwenden Sie dieses Konto, um das Angebot zu überprüfen, bevor Sie es veröffentlichen.
• Wenn Ihr visuelles Element bereits in AppSource verfügbar ist und Sie es auf ein lizenziertes visuelles Element aktualisieren möchten, können Sie es nicht zu einem privaten Plan machen, da das visuelle Element aus AppSource ausgeblendet wird und Ihre vorhandenen Benutzer keinen Zugriff darauf haben. 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.