Imposizione delle licenze e della transazioni (anteprima pubblica)

Quando si creano oggetti visivi di Power BI per il download in AppSource, è ora possibile gestire e applicare le licenze usando i sistemi Microsoft. L'utente finale assegna e gestisce le licenze usando strumenti familiari come l'interfaccia di amministrazione di Microsoft 365 e l'API delle licenze consente di applicare queste licenze e di garantire che solo gli utenti con licenza possano eseguire il rendering degli oggetti visivi.

Processo di imposizione delle licenze

La tabella seguente illustra i passaggi necessari per la gestione delle licenze visive tramite Microsoft:

Procedi	Dettagli
Creare un'offerta nel Centro per i partner	Scegliere di eseguire transazioni tramite il sistema commerciale Microsoft. Abilitare Microsoft per gestire le licenze. Impostare prezzi e disponibilità.
Aggiungere l'imposizione delle licenze al pacchetto visivo di Power BI	Creare o riconfigurare il pacchetto per usare la licenza di runtime di Power BI, che applica le licenze in base all'accesso di ogni utente.
I clienti individuano l'offerta in AppSource e acquistano una sottoscrizione	Quando i clienti acquistano l'offerta in AppSource, ottengono anche licenze per l'oggetto visivo di Power BI.
I clienti gestiscono le sottoscrizioni e assegnano/annullano l'assegnazione della licenza utente	I clienti gestiscono le sottoscrizioni e assegnano licenze per questi oggetti visivi e offerte nell'interfaccia di amministrazione di Microsoft 365, proprio come per qualsiasi altra sottoscrizione, ad esempio Office o Power BI.
Applicare i controlli di runtime	Offrire ai clienti un'esperienza uniforme usando le API predefinite per applicare i controlli delle licenze di runtime.
Visualizzare i report per alimentare la crescita	Ottenere informazioni dettagliate sui ricavi, le informazioni sui proventi e i dettagli dell'ordine e della licenza. Visualizzare informazioni su licenze e ordini acquistati, rinnovati e annullati nel tempo e in base all'area geografica.

API di gestione delle licenze

L'API di gestione delle licenze consente agli sviluppatori di oggetti visivi di Power BI di applicare licenze per oggetti visivi di Power BI. L'API supporta il recupero delle informazioni sulle licenze visive di Power BI assegnate all'utente di Power BI. Consente inoltre di attivare le notifiche correlate alle licenze visualizzate nell'oggetto visivo di Power BI e informare l'utente che deve acquistare le licenze mancanti. L'oggetto visivo non deve visualizzare la propria esperienza utente di licenza, ma usare una delle notifiche predefinite supportate da Power BI, come descritto nelle sezioni seguenti.

Per altre informazioni sulle licenze di Power BI, vedere Imposizione delle licenze.

Nota

L’API di gestione delle licenze è disponibile dalla versione 4.7. Per scoprire quale versione si sta usando, archiviare apiVersion nel file pbiviz.json.

Recuperare i piani di servizio dell'oggetto visivo assegnati all'utente attivo

Per ottenere i piani di servizio assegnati, aggiungere una chiamata a getAvailableServicePlans (disponibile tramite IVisualLicenseManager). Dal punto di vista delle prestazioni, tentare di recuperare le licenze una sola volta, preferibilmente nelle chiamate constructor o init, e salvare il risultato.
Una volta recuperate le licenze, queste vengono memorizzate nella cache sul lato host di Power BI durante la sessione di Power BI ed eventuali altre chiamate agli stessi dati restituiscono i dati memorizzati nella cache.

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

Il recupero delle licenze potrebbe essere un'operazione lunga, pertanto la getAvailableServicePlans chiamata è una chiamata asincrona e deve essere gestita come tale nel codice.
Come risposta alla chiamata al metodo, viene restituito l'oggetto LicenseInfoResult.

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

• plans - una matrice di piani di servizio acquistati dall'utente attivo per questo oggetto visivo. Le licenze acquistate per qualsiasi altro oggetto visivo non sono incluse nella risposta.
  Un ServicePlan contiene l'identificatore del servizio (spIdentifier) e il relativo stato (ServicePlanState).

  • spIdentifier: valore stringa dell'ID servizio generato quando si configurano i piani dell'offerta nel Centro per i partner (vedere l'esempio seguente)

  • state - enumerazione (ServicePlanState) che rappresenta lo stato dei piani assegnati.
    Stati del piano di servizio supportati:

    Stato	Descrizione
    Non attiva	Indica che la licenza non è attiva e non deve essere usata per i vantaggi del provisioning.
    Attive	Indica che la licenza è attiva e può essere usata per i vantaggi del provisioning.
    Avviso	Indica che la licenza è in un periodo di tolleranza probabile a causa di una violazione del pagamento.
    Sospeso	Indica che la licenza è sospesa probabilmente a causa di una violazione del pagamento.
    Sconosciuto	Valore di Microsoft Sentinel.

    Solo gli stati attivi e di avviso rappresentano una licenza utilizzabile. Tutti gli altri stati devono essere considerati come non risultanti da una licenza utilizzabile.

• isLicenseUnsupportedEnv - indica che il rendering dell'oggetto visivo viene eseguito in un ambiente Power BI che non supporta la gestione o l'imposizione delle licenze. Attualmente, gli ambienti Power BI seguenti non supportano la gestione delle licenze o l'imposizione delle licenze:

  • Incorporato - Pubblica sul Web, incorporamento PaaS
  • Cloud nazionali/regionali (dipende dal supporto generale per la transazionalità nei cloud nazionali/regionali)
  • RS Server (nessun supporto pianificato)
  • Esportazione (PDF\PPT) con l’API REST

• isLicenseInfoAvailable - Indica se è possibile recuperare le informazioni sulle licenze. L'errore nel recupero delle licenze può verificarsi nel caso in cui l'utente di Power BI Desktop non sia connesso a Internet (offline). Per il Web, il recupero delle licenze può non riuscire a causa di un'interruzione temporanea del servizio.

Esempio di chiamata getAvailableServicePlans per recuperare i piani di servizio dell'utente per questo oggetto visivo:

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

Nota

In questo esempio viene illustrato solo come verificare se l'utente dispone di piani validi per questo oggetto visivo. La plans matrice può contenere valori diversi spIdentifier e ogni identificatore può essere visualizzato più volte con stati diversi.

Notificare all'utente che mancano le licenze necessarie

La piattaforma Power BI offre diverse esperienze predefinite che possono essere usate per inviare notifiche:

• Le licenze devono essere acquistate per usufruire delle funzionalità dell'oggetto visivo completo
• La funzionalità dell'oggetto visivo specifico è bloccata a causa di licenze mancanti
• L'intero oggetto visivo è bloccato a causa di licenze mancanti
• L'intero oggetto visivo è bloccato perché l'ambiente di Power BI in uso non supporta la gestione delle licenze\imposizione

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

Esempio di chiamata notifyLicenseRequireddi :

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

Icona generale che indica che manca una licenza richiesta

Usare la chiamata notifyLicenseRequired con LicenseNotificationType.General per visualizzare un'icona come parte del contenitore dell'oggetto visivo.
Dopo l'attivazione, l'icona viene mantenuta per tutta la durata dell'oggetto visivo fino a clearLicenseNotification quando o notifyLicenseRequired non viene chiamata.

Nota

La LicenseNotificationType.General notifica viene applicata solo da un ambiente che supporta la gestione delle licenze e per gli scenari di modifica di Power BI. La chiamata a questa operazione in un ambiente non supportato o quando il report è in modalità lettura o nel dashboard non applica l'icona e restituisce false nella risposta della chiamata.

Esempio di visualizzazione dell'oggetto visivo contenente l'icona generale "licenze necessarie":

Sovrapporre la visualizzazione dell'oggetto visivo con una notifica di licenza mancante

Usare la chiamata notifyLicenseRequired con LicenseNotificationType.VisualIsBlocked per sovrapporre la visualizzazione dell'oggetto visivo con una notifica che indica che l'oggetto visivo è bloccato perché sono state trovate licenze necessarie mancanti.
Dopo l'attivazione, questa notifica viene mantenuta per tutta la durata dell'oggetto visivo fino a clearLicenseNotification quando o notifyLicenseRequired non viene chiamata.

Esempio di visualizzazione dell'oggetto visivo contenente la notifica dell'oggetto visivo bloccato. Power BI Desktop visualizza solo l'opzione Ottieni una licenza :

Sovrapporre la visualizzazione dell'oggetto visivo con una notifica di ambiente non supportato

Usare la chiamata notifyLicenseRequired con LicenseNotificationType.UnsupportedEnv per sovrapporre la visualizzazione dell'oggetto visivo con una notifica che indica che l'oggetto visivo è bloccato perché Power BI in uso non supporta la gestione delle licenze\imposizione.
Dopo l'attivazione, l'icona viene mantenuta per tutta la durata dell'oggetto visivo fino a clearLicenseNotification quando o notifyLicenseRequired non viene chiamata.

Nota

La notifica di LicenseNotificationType.UnsupportedEnv viene applicata solo quando viene chiamato nel contesto di un ambiente di licenza non supportato. La chiamata a questa operazione in qualsiasi altro ambiente non applica la notifica e restituisce false nella risposta della chiamata.

Esempio di visualizzazione dell'oggetto visivo contenente la notifica "Ambiente non supportato":

Visualizzare un banner che informa che non è stato possibile applicare la funzionalità di un oggetto visivo specifico

Quando si applica la funzionalità di un oggetto visivo specifico, sono necessarie licenze mancanti, è possibile usare la notifyFeatureBlocked chiamata che visualizza un banner popup come parte del contenitore dell'oggetto visivo. Il banner supporta anche una descrizione comando personalizzata che è possibile impostare e usare per fornire informazioni aggiuntive sulla funzionalità che ha attivato la notifica.

Nota

La funzionalità viene bloccata notifica solo quando si applicano entrambe le condizioni seguenti:

• Viene chiamato da un ambiente di licenza supportato
• Le sovrimpressioni di blocco non vengono applicate (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

La chiamata a questa notifica in un ambiente non supportato non applica la notifica e restituisce false nella risposta della chiamata.

Nota

Per supportare l'ambiente Power BI localizzato, è consigliabile mantenere le versioni localizzate delle descrizioni comando in uso. Usare l’API di localizzazione per recuperare la lingua delle impostazioni locali di Power BI.

Dopo l'attivazione, il banner viene visualizzato per 10 secondi o fino a quando non viene attivato l'altro banner "funzionalità bloccata" o fino a quando clearLicenseNotification non viene chiamato (qualsiasi cosa venga prima).

Esempio di visualizzazione dell'oggetto visivo contenente la notifica banner "funzionalità bloccata":

Testare un oggetto visivo concesso in licenza

Per testare un oggetto visivo con licenza end-to-end prima di renderlo disponibile pubblicamente:

• Se si sta creando una nuova offerta, aggiungere l'oggetto visivo come piano privato per un account cliente di test. L'offerta è visibile solo per questo account di test per l'acquisto. Usare questo account per convalidare l'offerta prima di renderla pubblica.
• Se l'oggetto visivo è già disponibile in AppSource e si vuole aggiornarlo a un oggetto visivo concesso in licenza, non è possibile renderlo un piano privato perché nasconde l'oggetto visivo da AppSource e gli utenti esistenti non potranno accedervi. Attualmente non è possibile testare un oggetto visivo pubblicato end-to-end. Testarlo allo stesso modo in cui è stato testato l'oggetto visivo originale in AppSource, simulando il valore dell'API di licenza per verificare le diverse possibilità.

Considerazioni e limitazioni

• La descrizione comando per il banner della funzionalità è limitata da 500 caratteri.
• La descrizione comando per il banner della funzionalità richiede la localizzazione.
• La creazione di bundle di licenze (ovvero una licenza che copre più offerte dello stesso editore) non è ancora supportata.

Contenuto correlato

Pubblicare un oggetto visivo personalizzato di Power BI

Altre domande? Contattare la community di Power BI