Licenciamento e aplicação da transactabilidade (Visualização pública)

Ao criar visuais do Power BI para download no AppSource, agora você pode gerenciar e impor suas licenças usando sistemas Microsoft. O usuário final atribui e gerencia licenças usando ferramentas conhecidas, como o centro de administração do Microsoft 365, e a API de licenciamento permite aplicar essas licenças e garantir que apenas usuários licenciados possam renderizar os elementos visuais.

Processo de aplicação de licenças

A tabela a seguir ilustra as etapas envolvidas no gerenciamento de suas licenças visuais por meio da Microsoft:

API de licenciamento

A API de Licenciamento permite que os desenvolvedores visuais do Power BI imponham licenças visuais do Power BI. A API dá suporte à recuperação de informações sobre licenças visuais do Power BI atribuídas ao usuário do Power BI. Ele também permite acionar as notificações relacionadas ao licenciamento que aparecem no visual do Power BI e informar ao usuário que ele precisa comprar as licenças ausentes. O visual não deve exibir sua própria UX de licenciamento, em vez disso, use uma das notificações predefinidas com suporte do Power BI, conforme detalhado nas seções a seguir.

Saiba mais sobre o licenciamento do Power BI, consulte Aplicação de licença.

Recuperar planos de serviço do visual atribuídos ao usuário ativo

Para obter planos de serviço atribuídos, adicione uma chamada para getAvailableServicePlans (disponível via IVisualLicenseManager). Do ponto de vista do desempenho, tente buscar as licenças uma vez, de preferência nas constructor chamadas ou nas init chamadas, e salve o resultado.
Depois que as licenças são recuperadas, elas são armazenadas em cache no lado do host do Power BI durante a sessão do Power BI e quaisquer outras chamadas para o mesmo retornam os dados armazenados em cache.

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

Recuperar as licenças pode ser uma operação longa, portanto, a chamada é uma chamada assíncrona getAvailableServicePlans e deve ser tratada como tal em seu código.
Como resposta à chamada do método, LicenseInfoResult o objeto é retornado.

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

• plans - uma matriz de Planos de Serviço adquiridos pelo usuário ativo para este visual. (As licenças compradas para quaisquer outros elementos visuais não são incluídas na resposta.)
  Um ServicePlan contém o identificador de serviço (spIdentifier) e seu estado (ServicePlanState).

  • spIdentifier: o valor da cadeia de caracteres do ID de serviço gerado quando você configura os planos da sua oferta no Partner Center (consulte o exemplo a seguir)

  • state – enum (ServicePlanState) que representa o estado dos planos atribuídos.
    O plano de serviço suportado afirma:

    Condição	Description
    Inativos	Indica que a licença não está ativa e não deve ser usada para provisionar benefícios.
    Ativos	Indica que a licença está ativa e pode ser usada para benefícios de provisionamento.
    Aviso	Indica que a licença está em período de carência provavelmente devido a violação de pagamento.
    Suspenso	Indica que a licença está suspensa provavelmente devido a violação de pagamento.
    Desconhecido	Valor do Microsoft Sentinel.

    Apenas os estados ativo e de aviso representam uma licença utilizável. Todos os outros estados devem ser tratados como não resultando em uma licença utilizável.

• isLicenseUnsupportedEnv - indica que o visual está sendo renderizado em um ambiente do Power BI que não oferece suporte ao gerenciamento ou imposição de licenças. Atualmente, os seguintes ambientes do Power BI não oferecem suporte ao gerenciamento ou imposição de licenças:

  • Incorporado - Publicar na Web, incorporar PaaS
  • Nuvens nacionais/regionais (depende do suporte geral para transacionabilidade em nuvens nacionais/regionais)
  • Servidor RS (Sem suporte planeado)
  • Exportando (PDF\PPT) usando a API REST

• isLicenseInfoAvailable - Indica se as informações de licenças podem ser recuperadas. Pode ocorrer uma falha na recuperação de licenças caso o utilizador do Power BI Desktop não tenha sessão iniciada ou não esteja ligado à Internet (offline). Para a Web, a recuperação de licenças pode falhar devido a uma interrupção temporária do serviço.

Exemplo de chamada getAvailableServicePlans (usando o ID de serviço da imagem anterior):

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

Notificar o usuário de que as licenças necessárias estão faltando

A plataforma Power BI fornece várias experiências prontas para uso que podem ser usadas para notificar:

• As licenças devem ser adquiridas para desfrutar de todas as capacidades visuais
• O recurso do visual específico está bloqueado devido à falta de licenças
• Todo o visual está bloqueado devido à falta de licenças
• Todo o visual é bloqueado porque o ambiente do Power BI em uso não oferece suporte a gerenciamento\imposição de licenças

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

Exemplo de chamada 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);
        });
}

Ícone geral indicando que uma licença necessária está faltando

Use notifyLicenseRequired call with LicenseNotificationType.General para exibir um ícone como parte do contêiner do visual.
Uma vez acionado, o ícone é preservado durante toda a vida útil do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Exemplo do visor visual que contém o ícone geral "licenças são necessárias":

Sobreponha a exibição do visual com uma notificação de licença ausente

Use notifyLicenseRequired call with LicenseNotificationType.VisualIsBlocked para sobrepor a exibição do visual com uma notificação de que o visual está bloqueado porque as licenças necessárias foram encontradas ausentes.
Uma vez acionada, essa notificação é preservada durante toda a vida útil do visual até clearLicenseNotification ou notifyLicenseRequired ser chamada.

Exemplo do visor visual que contém a notificação visual bloqueada . O Power BI Desktop exibe apenas a opção Obter uma licença :

Sobreponha a exibição do visual com uma notificação de ambiente sem suporte

Use notifyLicenseRequired call with LicenseNotificationType.UnsupportedEnv para sobrepor a exibição do visual com uma notificação de que o visual está bloqueado, pois o Power BI em uso não oferece suporte a gerenciamento de licenças\enforcement.
Uma vez acionado, o ícone é preservado durante toda a vida útil do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Exemplo de exibição visual que contém a notificação "Ambiente não suportado":

Exibir um banner notificando que a funcionalidade de um visual específico não pôde ser aplicada

Quando a aplicação da funcionalidade de um visual específico requer licenças que foram encontradas ausentes, você pode usar a notifyFeatureBlocked chamada que exibe um banner pop-up como parte do contêiner do visual. O banner também suporta uma dica de ferramenta personalizada que você pode definir e usar para fornecer informações adicionais sobre o recurso que disparou a notificação.

Uma vez acionado, o banner é exibido por 10 segundos, ou até que outro banner "bloqueado por recurso" seja acionado, ou até clearLicenseNotification que seja chamado (o que vier primeiro).

Exemplo do visor visual que contém a notificação de banner "recurso bloqueado":

Testar um visual licenciado

Para testar um visual licenciado de ponta a ponta antes de disponibilizá-lo publicamente:

• Se você estiver criando uma oferta nova, adicione o visual como um plano privado para uma conta de cliente de teste. A oferta só é visível para esta conta de teste para compra. Use esta conta para validar a oferta antes de torná-la pública.
• Se seu visual já estiver disponível no AppSource e você quiser atualizá-lo para um visual licenciado, não poderá torná-lo um plano privado porque isso oculta o visual do AppSource e seus usuários existentes não terão acesso a ele. Atualmente, não há como testar um visual publicado de ponta a ponta. Teste-o da mesma forma que testou o visual original no AppSource, simulando o valor da API de licenciamento para verificar as diferentes possibilidades.

Considerações e limitações

• A dica de ferramenta para banner de recurso é limitada por 500 caracteres.
• A dica de ferramenta para banner de recurso requer localização.
• O agrupamento de licenças (ou seja, uma licença que cobre várias ofertas do mesmo editor) ainda não é suportado.

Conteúdos relacionados

Publicar um visual personalizado do Power BI

Tem dúvidas? Tente perguntar à Comunidade do Power BI