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 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 licenzautente	I clienti gestiscono le sottoscrizioni e assegnano licenze per questi oggetti visivi e offerte nel 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 licenze consente agli sviluppatori di oggetti visivi di Power BI di applicare licenze visive di Power BI. L'API supporta il recupero delle informazioni sulle licenze visive di Power BI assegnate all'utente di Power BI. Abilita anche l'attivazione delle notifiche correlate alle licenze che verranno visualizzate nell'oggetto visivo di Power BI e informano l'utente che devono 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 di seguito.

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

Nota

L'API licenze è disponibile dalla versione 4.7. Per scoprire quale versione si sta usando, archiviare apiVersion il file di 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 constructor chiamate o init e salvare il risultato.
Una volta recuperate le licenze, queste verranno memorizzate nella cache sul lato host di Power BI durante la sessione di Power BI e tutte le altre chiamate agli stessi restituiranno 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 , LicenseInfoResult viene restituito l'oggetto .

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

• plans : 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:

    Provincia	Descrizione
    Inattivi	Indica che la licenza non è attiva e non deve essere usata per i vantaggi del provisioning.
    Attivo	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 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:

  • Embedded - Publish to Web, PaaS embed
  • Cloud nazionali/regionali (dipende dal supporto generale per la transazioni 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 (usando l'ID servizio dell'immagine precedente):

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

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

Icona generale che indica che manca una licenza richiesta

Usare notifyLicenseRequired la chiamata con LicenseNotificationType.General per visualizzare un'icona come parte del contenitore dell'oggetto visivo.
Dopo l'attivazione, l'icona verrà 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 quando si applicano entrambi: supportati per gli scenari di gestione delle licenze e 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 applicherà l'icona e restituirà 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 notifyLicenseRequired la chiamata 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 verrà 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 bloccata dall'oggetto visivo . Power BI Desktop visualizzerà solo l'opzione Ottieni una licenza :

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

Usare notifyLicenseRequired la chiamata 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 verrà mantenuta per tutta la durata dell'oggetto visivo fino a clearLicenseNotification quando o notifyLicenseRequired non viene chiamata.

Nota

La LicenseNotificationType.UnsupportedEnv notifica 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 applicherà la notifica e restituirà 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 applicano le funzionalità di un oggetto visivo specifico, sono necessarie licenze mancanti, è possibile usare la notifyFeatureBlocked chiamata che aprirà un banner come parte del contenitore dell'oggetto visivo. Il banner supporta anche una descrizione comando personalizzata che può essere impostata dall'utente e usata per fornire informazioni aggiuntive sulla funzionalità che ha attivato la notifica.

Nota

La funzionalità è bloccata notifica viene applicata solo quando viene chiamato nel contesto di supportato per l'ambiente di licenza e nel caso in cui le sovrimpressioni di blocco non vengano applicate (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked). La chiamata a questa notifica in un ambiente non supportato non applicherà la notifica e restituirà 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 verrà visualizzato per 10 secondi o finché non viene attivato un altro banner "bloccato da funzionalità" 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 sarà visibile solo all'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 con licenza, non è possibile renderlo un piano privato perché nasconderà 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 licenze, ad esempio una licenza che copre più offerte dallo stesso editore, non è ancora supportata.

Contenuto correlato

Pubblicare un oggetto visivo personalizzato di Power BI

Altre domande? Contattare la community di Power BI