Wymuszanie licencjonowania i transakcji (publiczna wersja zapoznawcza)

Podczas tworzenia wizualizacji usługi Power BI do pobrania w usłudze AppSource możesz teraz zarządzać licencjami i wymuszać je przy użyciu systemów firmy Microsoft. Użytkownik końcowy przypisuje licencje i zarządza nimi przy użyciu znanych narzędzi, takich jak Centrum administracyjne platformy Microsoft 365, a interfejs API licencjonowania umożliwia wymuszanie tych licencji i zapewnienie, że tylko licencjonowani użytkownicy mogą renderować wizualizacje.

Proces wymuszania licencji

W poniższej tabeli przedstawiono kroki związane z zarządzaniem licencjami wizualnymi za pośrednictwem firmy Microsoft:

Krok	Szczegóły
Tworzenie oferty w Centrum partnerskim	Wybierz transakcję za pośrednictwem systemu handlowego firmy Microsoft. Włącz firmie Microsoft zarządzanie licencjami. Ustawianie cen i dostępności.
Dodawanie wymuszania licencji do pakietu wizualizacji usługi Power BI	Utwórz lub skonfiguruj ponownie pakiet do korzystania z licencji środowiska uruchomieniowego usługi Power BI, która wymusza licencjonowanie zgodnie z dostępem każdego użytkownika.
Klienci odkrywają ofertę w usłudze AppSource i kupują subskrypcję	Gdy klienci kupują ofertę w usłudze AppSource, otrzymują również licencje dla wizualizacji usługi Power BI.
Klienci zarządzają swoimi subskrypcjami i przypisują/nieprzypisują licencjiużytkownika	Klienci zarządzają subskrypcjami i przypisują licencje dla tych wizualizacji i ofert w Centrum administracyjne platformy Microsoft 365, podobnie jak w przypadku innych subskrypcji, takich jak Office lub Power BI.
Wymuszanie kontroli środowiska uruchomieniowego	Zapewnij klientom jednolite środowisko, korzystając z naszych wbudowanych interfejsów API, aby wymusić kontrole licencji środowiska uruchomieniowego.
Wyświetlanie raportów w celu podsycania wzrostu	Uzyskaj wgląd w przychody, informacje o wypłatach oraz szczegóły zamówienia i licencji. Wyświetl informacje o licencjach i zamówieniach zakupionych, odnowionych i anulowanych w czasie oraz według lokalizacji geograficznej.

Interfejs API licencjonowania

Interfejs API licencjonowania umożliwia deweloperom wizualizacji usługi Power BI wymuszanie licencji wizualizacji usługi Power BI. Interfejs API obsługuje pobieranie informacji na temat licencji wizualizacji usługi Power BI przypisanych do użytkownika usługi Power BI. Umożliwia również wyzwalanie powiadomień związanych z licencjonowaniem wyświetlanych w wizualizacji usługi Power BI i informowanie użytkownika o konieczności zakupu brakujących licencji. Wizualizacja nie powinna wyświetlać własnego środowiska użytkownika licencjonowania, zamiast tego należy użyć jednego z wstępnie zdefiniowanych powiadomień usługi Power BI zgodnie z opisem w poniższych sekcjach.

Dowiedz się więcej o licencjonowaniu usługi Power BI, zobacz Wymuszanie licencji.

Uwaga

Interfejs API licencjonowania jest dostępny w wersji 4.7. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion plik pbiviz.json .

Pobieranie planów usługi wizualizacji przypisanych do aktywnego użytkownika

Aby uzyskać przypisane plany usług, dodaj wywołanie usługi getAvailableServicePlans (dostępne za pośrednictwem polecenia IVisualLicenseManager). Z perspektywy wydajności spróbuj pobrać licencje raz, najlepiej w constructor wywołaniach lub init i zapisz wynik.
Po pobraniu licencji są one buforowane po stronie hosta usługi Power BI podczas sesji usługi Power BI i wszelkie dalsze wywołania w celu zwrócenia tych samych danych w pamięci podręcznej.

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

Pobieranie licencji może być długotrwałą operacją, dlatego getAvailableServicePlans wywołanie jest wywołaniem asynchronicznym i powinno być obsługiwane jako takie w kodzie.
W odpowiedzi na wywołanie metody LicenseInfoResult zwracany jest obiekt.

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

• plans — tablica planów usług zakupionych przez aktywnego użytkownika dla tej wizualizacji. (Licencje zakupione dla innych wizualizacji nie są uwzględnione w odpowiedzi).
  Element ServicePlan zawiera identyfikator usługi (spIdentifier) i jego stan (ServicePlanState).

  • spIdentifier: wartość ciągu identyfikatora usługi wygenerowanego podczas konfigurowania planów oferty w Centrum partnerskim (zobacz poniższy przykład)

  • state — wyliczenie (ServicePlanState), które reprezentuje stan przypisanych planów.
    Obsługiwane stany planu usługi:

    Stan	opis
    Nieaktywny	Wskazuje, że licencja nie jest aktywna i nie powinna być używana do aprowizacji korzyści.
    Aktywne	Wskazuje, że licencja jest aktywna i może być używana do aprowizacji korzyści.
    Ostrzeżenie	Wskazuje, że licencja jest w okresie prolongaty prawdopodobnie z powodu naruszenia płatności.
    Suspended	Wskazuje, że licencja jest zawieszona prawdopodobnie z powodu naruszenia płatności.
    Nieznane	Wartość usługi Microsoft Sentinel.

    Tylko stany aktywne i ostrzegawcze reprezentują licencję do użycia. Wszystkie inne stany powinny być traktowane jako nieużywalne licencje.

• isLicenseUnsupportedEnv — wskazuje, że wizualizacja jest renderowana w środowisku usługi Power BI, które nie obsługuje zarządzania licencjami ani wymuszania. Obecnie następujące środowiska usługi Power BI nie obsługują zarządzania licencjami ani wymuszania licencji:

  • Embedded — publikowanie w Sieci Web, osadzanie paaS
  • Chmury krajowe/regionalne (zależy od ogólnej obsługi transakcji w chmurach krajowych/regionalnych)
  • Serwer RS (brak planowanej pomocy technicznej)
  • Eksportowanie (PDF\PPT) przy użyciu interfejsu API REST

• isLicenseInfoAvailable — wskazuje, czy można pobrać informacje o licencjach. Niepowodzenie pobierania licencji może wystąpić w przypadku, gdy użytkownik programu Power BI Desktop nie jest zalogowany lub nie jest połączony z Internetem (offline). W przypadku sieci Web pobieranie licencji może zakończyć się niepowodzeniem z powodu tymczasowej awarii usługi.

Przykład wywołania w getAvailableServicePlans celu pobrania planów usługi użytkownika dla tej wizualizacji:

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

Uwaga

W tym przykładzie pokazano tylko, jak sprawdzić, czy użytkownik ma prawidłowe plany dla tej wizualizacji. Tablica plans może zawierać różne spIdentifier wartości, a każdy identyfikator może być wyświetlany wiele razy z różnymi stanami.

Powiadamianie użytkownika o braku wymaganych licencji

Platforma Power BI udostępnia kilka środowisk gotowe do użycia, które mogą służyć do powiadamiania:

• Licencje powinny być kupowane w celu korzystania z możliwości pełnej wizualizacji
• Funkcja określonej wizualizacji jest zablokowana z powodu brakujących licencji
• Cała wizualizacja jest zablokowana z powodu brakujących licencji
• Cała wizualizacja jest zablokowana, ponieważ używane środowisko usługi Power BI nie obsługuje zarządzania licencjami\wymuszania

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

Przykład wywołania metody 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);
        });
}

Ikona ogólna wskazująca brak wymaganej licencji

Użyj notifyLicenseRequired wywołania z LicenseNotificationType.General , aby wyświetlić ikonę jako część kontenera wizualizacji.
Po wyzwoleniu ikona jest zachowywana przez cały okres istnienia wizualizacji do momentu clearLicenseNotification wywołania lub notifyLicenseRequired wywołania.

Uwaga

Powiadomienie LicenseNotificationType.General jest wymuszane tylko ze środowiska obsługującego zarządzanie licencjonowaniem i scenariuszy edycji usługi Power BI. Wywołanie tej funkcji w nieobsługiwanym środowisku lub gdy raport jest w trybie odczytu lub na pulpicie nawigacyjnym nie stosuje ikony i zwraca wartość false w odpowiedzi wywołania.

Przykład wyświetlania wizualizacji zawierającej ikonę ogólną "licencje są wymagane":

Nakładanie wyświetlania wizualizacji z brakującym powiadomieniem o licencji

Użyj notifyLicenseRequired wywołania z LicenseNotificationType.VisualIsBlocked , aby nakładać wyświetlanie wizualizacji z powiadomieniem, że wizualizacja jest zablokowana, ponieważ brakuje wymaganych licencji.
Po wyzwoleniu to powiadomienie jest zachowywane przez cały okres istnienia wizualizacji do momentu clearLicenseNotification wywołania lub notifyLicenseRequired wywołania.

Przykład wyświetlania wizualizacji zawierającej powiadomienie o zablokowaniu wizualizacji. Program Power BI Desktop wyświetla tylko opcję Pobierz licencję :

Nakładanie wyświetlania wizualizacji z nieobsługiwanym powiadomieniem o środowisku

Użyj notifyLicenseRequired wywołania z LicenseNotificationType.UnsupportedEnv , aby nakładać wyświetlanie wizualizacji z powiadomieniem, że wizualizacja jest zablokowana, ponieważ usługa Power BI w użyciu nie obsługuje zarządzania licencjami\wymuszania.
Po wyzwoleniu ikona jest zachowywana przez cały okres istnienia wizualizacji do momentu clearLicenseNotification wywołania lub notifyLicenseRequired wywołania.

Uwaga

Powiadomienie LicenseNotificationType.UnsupportedEnv jest wymuszane tylko wtedy, gdy jest wywoływane w kontekście nieobsługiwanego środowiska licencjonowania. Wywołanie tej funkcji w innym środowisku nie stosuje powiadomienia i zwraca je false w odpowiedzi wywołania.

Przykład wyświetlania wizualizacji zawierającej powiadomienie "Nieobsługiwane środowisko":

Wyświetl baner z powiadomieniem, że nie można zastosować funkcji określonej wizualizacji

W przypadku stosowania funkcji określonej wizualizacji wymagane są brakujące licencje, można użyć notifyFeatureBlocked wywołania, które wyświetla baner podręczny w ramach kontenera wizualizacji. Baner obsługuje również niestandardową etykietkę narzędzia, którą można ustawić i użyć, aby podać dodatkowe informacje na temat funkcji, która wyzwoliła powiadomienie.

Uwaga

Powiadomienie o zablokowaniu funkcji jest wymuszane tylko wtedy, gdy obowiązują oba następujące warunki:

• Jest wywoływana z obsługiwanego środowiska licencjonowania
• Nakładanie blokujące nie jest stosowane (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

Wywołanie tego powiadomienia w nieobsługiwanym środowisku nie stosuje powiadomienia i zwraca je false w odpowiedzi wywołania.

Uwaga

Aby obsługiwać zlokalizowane środowisko usługi Power BI, zalecamy obsługę zlokalizowanych wersji etykietek narzędzi w użyciu. Użyj interfejsu API lokalizacji, aby pobrać język ustawień regionalnych usługi Power BI.

Po wyzwoleniu baner jest wyświetlany przez 10 sekund lub do momentu wyzwolenia innego baneru "blokada funkcji" lub do momentu clearLicenseNotification wywołania (cokolwiek nastąpi wcześniej).

Przykład wyświetlania wizualizacji zawierającej powiadomienie baneru "funkcja zablokowana":

Testowanie licencjonowanej wizualizacji

Aby przetestować licencjonowany element wizualny przed udostępnieniem jej publicznie:

• Jeśli tworzysz zupełnie nową ofertę, dodaj wizualizację jako prywatny plan dla testowego konta klienta. Oferta jest widoczna tylko dla tego konta testowego do zakupu. Użyj tego konta, aby zweryfikować ofertę przed jej upublicznienie.
• Jeśli wizualizacja jest już dostępna w usłudze AppSource i chcesz ją uaktualnić do licencjonowanej wizualizacji, nie możesz ustawić go jako planu prywatnego, ponieważ powoduje to ukrycie wizualizacji z usługi AppSource, a istniejący użytkownicy nie będą mieli do niej dostępu. Obecnie nie ma możliwości przetestowania opublikowanej wizualizacji. Przetestuj ją w taki sam sposób, jak w przypadku testowania oryginalnej wizualizacji w usłudze AppSource, wyśmiewając wartość interfejsu API licencjonowania, aby sprawdzić różne możliwości.

Rozważania i ograniczenia

• Etykietka narzędzia dla baneru funkcji jest ograniczona o 500 znaków.
• Etykietka narzędzia dla baneru funkcji wymaga lokalizacji.
• Tworzenie pakietów licencji (czyli jedna licencja obejmująca wiele ofert od tego samego wydawcy) nie jest jeszcze obsługiwana.

Powiązana zawartość

Publikowanie wizualizacji niestandardowej usługi Power BI

Masz więcej pytań? Spróbuj zadać Społeczność usługi Power BI