Imposição de licenciamento e transabilidade (versão prévia 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 familiares, como Centro de administração do Microsoft 365, e a API de licenciamento permite impor essas licenças e garantir que somente usuários licenciados possam renderizar os visuais.

Processo de imposição de licença

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

Etapa	Detalhes
Criar uma oferta no Partner Center	Escolha fazer transações por meio do sistema de comércio da Microsoft. Permitir que a Microsoft gerencie licenças. Definir o preço e a disponibilidade.
Adicionar imposição de licença ao pacote visual do Power BI	Crie ou reconfigure seu pacote para usar a licença de runtime do Power BI, que impõe o licenciamento de acordo com o acesso de cada usuário.
Os clientes descobrem sua oferta no AppSource e compram uma assinatura	Quando os clientes adquirem sua oferta no AppSource, eles também obtêm licenças para o Visual do Power BI.
Os clientes gerenciam suas assinaturas e atribuem/cancelam a atribuição de licenças de usuário	Os clientes gerenciam assinaturas e atribuem licenças para esses Visuais e ofertas no Centro de administração do Microsoft 365, assim como fazem para qualquer uma de suas outras assinaturas, como o Office ou o Power BI.
Impor verificações de runtime	Dê aos seus clientes uma experiência uniforme usando nossas APIs prontas para uso para impor verificações de licença de runtime.
Exibir relatórios para impulsionar o crescimento	Obtenha insights sobre receita, informações de pagamento e detalhes de pedidos e licenças. Exiba informações sobre licenças e pedidos comprados, renovados e cancelados ao longo do tempo e por geografia.

API de licenciamento

A API de Licenciamento permite que os desenvolvedores de visuais do Power BI apliquem licenças de visuais do Power BI. A API dá suporte à recuperação das informações sobre licenças de visuais do Power BI atribuídas ao usuário do Power BI. Ele também permite disparar as notificações relacionadas ao licenciamento que aparecem no visual do Power BI e informam ao usuário que ele precisa comprar as licenças ausentes. O visual não deve exibir sua própria experiência do usuário 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 em imposição de licenças.

Observação

A API de Licenciamento está disponível na versão 4.7. Para descobrir qual versão você está usando, confira apiVersion no arquivo pbiviz.json.

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

Para obter planos de serviço atribuídos, adicione uma chamada a getAvailableServicePlans(disponível via IVisualLicenseManager). Do ponto de vista do desempenho, tente buscar as licenças uma vez, de preferência nas chamadas constructor ou nas chamadas init 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 todas as 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 getAvailableServicePlans chamada é uma chamada assíncrona e deve ser tratada como tal em seu código.
Como resposta à chamada ao método, o objeto LicenseInfoResult é retornado.

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

• plans – uma matriz de Planos de Serviço comprados pelo usuário ativo para este visual. (As licenças compradas para outros visuais não estã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 da ID do serviço gerado quando você configura os planos da sua oferta no Partner Center (veja o exemplo a seguir)

  • estado – enumeração (ServicePlanState) que representa o estado dos planos atribuídos.
    Estados do plano de serviço com suporte:

    Estado	Descrição
    Inativo	Indica que a licença não está ativa e não deve ser usada para provisionamento de benefícios.
    Ativo	Indica que a licença está ativa e pode ser usada para provisionamento de benefícios.
    Aviso	Indica que a licença está em período de cortesia, provavelmente devido a uma violação de pagamento.
    Suspenso	Indica que a licença está suspensa, provavelmente devido a uma violação de pagamento.
    Desconhecido	Valor do Microsoft Sentinel.

    Somente os estados ativos e 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 dá suporte ao gerenciamento ou à imposição de licenças. Atualmente, os seguintes ambientes do Power BI não dão suporte ao gerenciamento ou à imposição de licenças:

  • Inserido – Publicar na Web, inserir PaaS
  • Nuvens nacionais/regionais (depende do suporte geral para transacionalidade em nuvens nacionais/regionais)
  • Servidor RS (sem suporte planejado)
  • Exportação (PDF\PPT) usando a API REST

• isLicenseInfoAvailable – Indica se as informações de licenças podem ser recuperadas. A falha na recuperação de licenças pode ocorrer caso o usuário do Power BI Desktop não esteja logado ou não esteja conectado à 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 para recuperar os planos de serviço do usuário para este visual:

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

Observação

Este exemplo demonstra apenas como verificar se o usuário tem planos válidos para esse visual. A plans matriz pode conter valores diferentes spIdentifier e cada identificador pode aparecer várias vezes com estados diferentes.

Notifique o usuário de que as licenças necessárias estão ausentes

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

• As licenças devem ser adquiridas para que o usuário desfrute dos recursos completos do visual
• O recurso específico do visual é bloqueado devido a licenças ausentes
• Todo o visual está bloqueado devido a licenças ausentes
• Todo o visual está bloqueado porque o ambiente do Power BI em uso não dá suporte ao 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 que indica que uma licença necessária está ausente

Use a chamada notifyLicenseRequired com LicenseNotificationType.General para exibir um ícone como parte do contêiner do visual.
Depois de disparado, o ícone é preservado durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired é chamado.

Observação

A LicenseNotificationType.General notificação só é imposta de um ambiente que dá suporte ao gerenciamento de licenciamento e para cenários de edição do Power BI. Chamar isso em um ambiente sem suporte ou quando o relatório está no modo de leitura ou no painel não aplica o ícone e retorna false na resposta da chamada.

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

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

Use a chamada notifyLicenseRequired com LicenseNotificationType.VisualIsBlocked para sobrepor a exibição do visual com uma notificação de que o visual está bloqueado, pois as licenças necessárias estão ausentes.
Depois de disparada, essa notificação é preservada durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired é chamada.

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

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

Use a chamada notifyLicenseRequired com 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 dá suporte ao gerenciamento\imposição de licenças.
Depois de disparado, o ícone é preservado durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired é chamado.

Observação

A notificação LicenseNotificationType.UnsupportedEnv só é imposta quando chamada no contexto sem suporte para o ambiente de licenciamento. Chamar isso em qualquer outro ambiente não aplica a notificação e retorna false na resposta da chamada.

Exemplo da exibição do visual que contém a notificação "Ambiente sem suporte":

Exibir uma faixa notificando que não foi possível exibir a funcionalidade de um visual específico

Ao aplicar a funcionalidade de um visual específico exigir licenças que foram encontradas ausentes, você pode usar a notifyFeatureBlocked chamada que exibe uma faixa pop-up como parte do contêiner do visual. A faixa também dá suporte a uma dica de ferramenta personalizada que você pode definir e usar para fornecer informações adicionais sobre o recurso que disparou a notificação.

Observação

A notificação de recurso bloqueado só é aplicada quando as seguintes condições se aplicam:

• Ele é chamado de um ambiente de licenciamento com suporte
• As sobreposições de bloqueio não são aplicadas (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

Chamar essa notificação em um ambiente sem suporte não aplica a notificação e retorna false na resposta da chamada.

Observação

Para dar suporte ao ambiente localizado do Power BI, recomendamos manter versões localizadas das dicas de ferramenta em uso. Use a API de Localização para recuperar o idioma de localidade do Power BI.

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

Exemplo da exibição do visual que contém a notificação de faixa "recurso bloqueado":

Testar um visual licenciado

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

• Se estiver criando uma oferta totalmente 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. Utilize essa conta para validar a oferta antes de torná-la pública.
• Se o 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 os 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 você 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 a faixa de recurso é limitada por 500 caracteres.
• A dica de ferramenta para a faixa de recursos requer localização.
• O pacote de licenças (ou seja, uma licença que abrange várias ofertas do mesmo editor) ainda não tem suporte.

Conteúdo relacionado

Publicar um visual personalizado do Power BI

Mais perguntas? Experimente perguntar à Comunidade do Power BI