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:

Passo	Detalhes
Criar uma oferta no Partner Center	Opte por efetuar transações através do sistema de comércio da Microsoft. Habilite a Microsoft para gerenciar licenças. Defina preços e disponibilidade.
Adicionar imposição de licença ao seu pacote visual do Power BI	Crie ou reconfigure seu pacote para usar a licença de tempo de execução 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 compram sua oferta no AppSource, eles também obtêm licenças para o Power BI Visual.
Os clientes gerem as suas subscrições e atribuem/anulam a atribuição de licençasde utilizador	Os clientes gerem subscrições e atribuem licenças para estes Visuais e ofertas no centro de administração do Microsoft 365, tal como fazem para qualquer uma das suas outras subscrições, como o Office ou o Power BI.
Impor verificações de tempo de execução	Ofereça aos seus clientes uma experiência uniforme usando nossas APIs prontas para uso para impor verificações de licença de tempo de execução.
Visualizar relatórios para impulsionar o crescimento	Obtenha informações sobre receitas, informações de pagamento e detalhes de pedidos e licenças. Veja 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 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 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 abaixo.

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

Nota

A API de licenciamento está disponível a partir da versão 4.7. Para saber qual versão você está usando, verifique a apiVersionno arquivo pbiviz.json .

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 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 é 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 sentinela.

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

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

Í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 será preservado durante toda a vida útil do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Nota

A LicenseNotificationType.General notificação só é imposta quando ambos se aplicam: suportado para ambiente 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 painel não aplicará o ícone e retornará false na resposta da chamada.

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 será 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 exibirá 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 será preservado durante toda a vida útil do visual até clearLicenseNotification ou notifyLicenseRequired ser chamado.

Nota

A LicenseNotificationType.UnsupportedEnv notificação só é aplicada quando chamada no contexto de ambiente de licenciamento sem suporte. Chamá-lo em qualquer outro ambiente não aplicará a notificação e retornará false na resposta da chamada.

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 exibirá um banner como parte do contêiner do visual. O banner também suporta 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.

Nota

A notificação de bloqueio do recurso só é aplicada quando chamada no contexto do ambiente de licenciamento suportado e no caso de sobreposições de bloqueio não serem 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.

Nota

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

Uma vez acionado, o banner será 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ó será visível para a conta deste 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 ocultará 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.
• A agregação de licenças (ou seja, uma licença que cobre várias ofertas do mesmo editor) ainda não é suportada.

Conteúdos relacionados

Publicar um visual personalizado do Power BI

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