Integração do sistema de visuais do Power BI

  • Artigo

O artigo descreve a API Visual e como o Power BI lida com as interações entre você, o visual e o host.

As ações e as atualizações posteriores no Power BI podem ser iniciadas manual ou automaticamente. Tipos de atualização:

A figura a seguir mostra como são processadas no Power BI ações comuns baseadas em visuais, como selecionar um indicador.

Diagram of the Power BI visual process.

Interagir com um visual por meio do Power BI

Você pode atualizar um visual com o Power BI da seguinte maneira:

  • Abra o painel de propriedades do visual.

    Quando você abre o painel de propriedades do visual, o Power BI busca objetos e propriedades com suporte no arquivo capabilities.json do visual. Para receber valores reais das propriedades, o Power BI chama o método getFormattingModel do visual (APIs anteriores à versão 5.0 chamam enumerateObjectInstances). A API retorna componentes modernos do modelo do painel de formato, propriedades e seus valores reais.

    Saiba mais em Funcionalidades e propriedades de visuais do Power BI.

  • Personalizar títulos, telas de fundo, etiquetas e legendas de visualizações.

    Quando você altera o valor de uma propriedade no painel Formato, o Power BI chama o método update. O Power BI passa o novo objeto options para o método update e os objetos contêm os novos valores.

    Para obter mais informações, confira Objetos e propriedades de visuais do Power BI.

  • Redimensione o visual.

    Quando você altera o tamanho de um visual, o Power BI chama o método update e passa o novo objeto options. Os objetos options têm objetos viewport aninhados que contêm a nova largura e altura do visual.

  • Aplique um filtro no nível do relatório, da página ou do visual.

    O Power BI filtra os dados com base nas condições do filtro. O Power BI chama o método update do visual para atualizar o visual com novos dados.

    O visual obtém uma nova atualização dos objetos options quando há novos dados em um dos objetos aninhados. Como a atualização ocorrerá depende da configuração de mapeamento de exibição de dados do visual.

    Para obter mais informações, confira Entender o mapeamento de exibição de dados em visuais do Power BI.

  • Selecione um ponto de dados em outro visual do relatório.

    Quando você seleciona um ponto de dados em outro visual do relatório, o Power BI filtra ou realça os pontos de dados selecionados e chama o método update do visual. O visual obtém novos dados filtrados ou os mesmos dados com a matriz dos destaques.

    Para obter mais informações, confira Realçar pontos de dados em Visuais do Power BI.

  • Selecione um indicador no painel Indicadores do relatório.

    Quando você seleciona um indicador no painel Indicadores:

    • O Power BI chama uma função que é passada e registrada pelo método registerOnSelectionCallback. A função de retorno de chamada obtém matrizes de seleções para o indicador correspondente.

    • O Power BI chama o método update com um objeto filter correspondente dentro do objeto options.

      Em ambos os casos, o visual altera seu estado de acordo com as seleções recebidas ou com o objeto filter.

      Para saber mais sobre indicadores e filtros, confira a API de Filtros Visuais em visuais do Power BI.

Interagir diretamente com o visual

Você também pode interagir diretamente com o visual para atualizá-lo:

  • Passe o mouse sobre um elemento de dados.

    O visual pode exibir mais informações sobre o ponto de dados por meio da API de Dicas de Ferramentas do Power BI. Quando você passa o mouse sobre um elemento visual, o visual pode manipular o evento e exibir dados sobre o elemento ToolTip associado. O visual pode exibir a dica de ferramenta padrão ou a dica de ferramenta da página do relatório.

    Para obter mais informações, consulte Adicionar dicas de ferramenta aos visuais do Power BI.

  • Altere as propriedades do visual (por exemplo, expandindo uma árvore) e o visual salva o novo estado nas propriedades do visual.

    Um visual pode salvar os valores das propriedades por meio da API do Power BI. Por exemplo, quando você interage com o visual, que precisa salvar ou atualizar valores de propriedades, o visual pode chamar o método persistProperties.

  • Selecione uma URL.

    Por padrão, um visual não pode abrir diretamente uma URL. Para abrir uma URL em uma nova guia, o visual pode chamar o método launchUrl e passar a URL como um parâmetro.

    Saiba mais em Criar uma URL de inicialização.

  • Aplique um filtro por meio do visual.

    Um visual pode chamar o método applyJsonFilter e passar as condições para filtrar dados em outros visuais. Vários tipos de filtros estão disponíveis, incluindo filtros básicos, avançados e de tupla.

    Saiba mais em API de Filtros Visuais em visuais do Power BI.

  • Selecione elementos no visual.

    Saiba mais sobre seleções em visuais do Power BI em Adicionar interatividade ao Power BI usando seleções de visual do Power BI.

O visual interage com o Power BI

Às vezes, o visual inicia a comunicação com o host do Power BI sem nenhuma entrada sua:

  • O visual solicita mais dados do Power BI.

    O visual processa os dados por partes. O método de API fetchMoreData solicita o próximo fragmento de dados no modelo semântico.

    Saiba mais em Buscar mais dados do Power BI.

  • O serviço de evento dispara.

    O Power BI pode exportar um relatório para PDF ou enviar um relatório por email (aplica-se somente a visuais certificados). Para notificar o Power BI de que a renderização foi concluída e que o visual está pronto para ser capturado como PDF ou para email, o visual deve chamar a API de Renderização de Eventos.

    Saiba mais em Exportar relatórios do Power BI para PDF.

    Para saber mais sobre o serviço de eventos, confira "Renderizando" eventos em visuais do Power BI.

Conteúdo relacionado

Você está interessado em criar suas próprias visualizações e adicioná-las ao Microsoft AppSource? Consulte estes artigos: