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. Ela também permite disparar as notificações relacionadas ao licenciamento que aparecerão 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 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 forem recuperadas, elas serã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 retornarão 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 getAvailableServicePlans é 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.
    Unknown	Valor de sentinela.

    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 (usando a ID do serviço da imagem acima):

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

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

Í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 será preservado durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Observação

A notificação LicenseNotificationType.General só é aplicada quando ambos se aplicam: com suporte para ambientes de licenciamento e cenários de edição do Power BI. Chamar isso em um ambiente sem suporte ou quando o relatório estiver no modo de leitura ou no dashboard não aplicará o ícone e retornará 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 será preservada durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Exemplo da exibição do visual que contém a notificação visual bloqueado. Power BI Desktop exibirá 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 será preservado durante todo o tempo de vida do visual até clearLicenseNotification ou notifyLicenseRequired ser 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 aplicará a notificação e retornará 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

Aplicar uma funcionalidade específica do visual requer licenças que estão ausentes, você pode usar a chamada notifyFeatureBlocked, que exibirá uma faixa como parte do contêiner do visual. A faixa também dá suporte a uma dica de ferramenta personalizada que pode ser definida por você e usada para fornecer informações adicionais sobre o recurso que disparou a notificação.

Observação

A notificação de que o recurso está bloqueada só é aplicada quando chamada no contexto de suporte para ambiente de licenciamento e caso as sobreposições de bloqueio não sejam aplicadas (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked). Chamar essa notificação em um ambiente sem suporte não aplicará a notificação e retornará 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 disparada, a faixa será exibida por 10 segundos ou até que outra faixa "recurso bloqueado" seja disparada ou até clearLicenseNotification ser chamada (o que vier 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ó estará visível para a conta de teste para compras. Utilize essa conta para validar a oferta antes de torná-la pública.
• Se o 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 ocultará 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.
• Ainda não há suporte para o agrupamento de licenças (ou seja, uma licença que abrange várias ofertas do mesmo editor).

Conteúdo relacionado

Publicar um visual personalizado do Power BI

Mais perguntas? Experimente perguntar à Comunidade do Power BI