Introdução

  • 12 minutos

Você pode usar Microsoft Power BI APIs de cliente para incorporar Power BI conteúdo usando JavaScript ou TypeScript. É uma biblioteca de cliente que fornece controle programático de toda a experiência de incorporação.

Nota

Para saber mais sobre os conceitos básicos das APIs de Power BI cliente e como elas são usadas para incorporar Power BI conteúdo, consulte o módulo Incorporar Power BI conteúdo.

Além de incorporar Power BI conteúdo, as APIs do cliente permitem que seu aplicativo:

  • Aplique operações ao conteúdo, como adicionar um filtro de relatório.
  • Trabalhe com eventos para que seu aplicativo possa responder às ações do utente feitas em um relatório, como a seleção de um botão.
  • Interaja com marcadores, aplicando-os ou criando novos.
  • Produza layouts de relatório dinâmicos, que fornecem controle para que os utilizadores possam personalizar a experiência do relatório.
  • Crie elementos visuais de relatório personalizados.
  • Conduza um fluxo de trabalho de análise contextual.

Aplicar operações

Seu aplicativo pode aplicar muitas operações ao conteúdo incorporado. Essas operações incluem operações gerais, como recarregar ou atualizar um relatório. Eles também incluem a capacidade de entrar ou sair do modo de ecrã cheia, ou você pode reaplicar as configurações que o aplicativo aplicou no objeto de configuração ao incorporar o conteúdo pela primeira vez.

Além das operações gerais, as operações de navegação na página também estão disponíveis. Além disso, você tem acesso a operações de filtro e segmentação de dados, que permitem que seu aplicativo determine ou defina o estado do filtro/segmentação de dados. Outras operações úteis incluem operações de dados que permitem exportar dados visuais e operações de menu que estendem menus com novos comandos personalizados.

Você pode experimentar algumas dessas operações acessando o Power BI Embedded Google Analytics Playground e seguindo as instruções a seguir.

Nota

O Power BI Embedded Analytics Playground é um site que ajuda você a aprender, explorar e experimentar Power BI análises incorporadas. Ele inclui uma área restrita do desenvolvedor para experiências práticas que usam as APIs do cliente com conteúdo de exemplo Power BI ou seu próprio conteúdo. Trechos de código e vitrines também estão disponíveis para você explorar.

Para obter mais informações, consulte O que é o parque infantil de Power BI análise incorporada?

No painel esquerdo, selecione Área restrita do desenvolvedor.

Imagem mostrando o painel esquerdo com a opção Sandbox do desenvolvedor realçada.

Quando solicitado, selecione o botão Usar exemplo para começar usando um relatório de exemplo.

Imagem mostrando o botão Usar exemplo realçado na caixa de diálogo Usar um relatório de exemplo.

Dica

Você também pode selecionar seu próprio relatório proveniente do serviço ou usar um token de incorporação gerado pelo aplicativo de Power BI desenvolvimento. Nesta atividade, você continuará a usar o relatório de exemplo.

O parque infantil incorpora um relatório de exemplo e, acima do relatório, está o painel de código que contém o código necessário para incorporar, carregar e renderizar o relatório.

No painel APIs de Relatório Incorporado, expanda o grupo Operações Gerais.

Imagem mostrando o grupo de Operações Gerais expandido no painel APIs de Relatório Incorporado.

Para atualizar o código, no painel APIs de relatório incorporado, arraste a operação de ecrã cheia e solte-a na última linha (linha 94) no painel de código.

Imagem mostrando a operação em ecrã cheia com uma seta indicando onde soltá-la no painel de código.

Revise o fragmento de código que foi adicionado ao painel de código. Em seguida, para executar o código, na barra de menus acima do painel de código, selecione Executar.

Imagem mostrando a barra de menus com a opção de menu Executar realçada.

O relatório é renderizado no modo de ecrã cheia. Para sair do modo de ecrã cheia, pressione a tecla Esc .

Agora, vamos modificar programaticamente a segmentação de dados do relatório. No painel APIs de Relatório Incorporado, expanda o grupo Filtros & Segmentações de Dados.

Imagem mostrando o grupo Filtros e Segmentações de Dados expandido no painel APIs de Relatório Incorporado.

Arraste a operação Definir estado da segmentação de dados para o painel de código, soltando-a abaixo da última linha de código. Em seguida, reveja as 43 linhas de código que adicionou ao painel de código. Execute o código e, em seguida, observe que o relatório continua a abrir no modo de ecrã inteira. O intervalo de datas da segmentação de dados deve ser definido como 12 de outubro de 2014 a 27 de novembro de 2014.

Imagem mostrando as segmentações de dados e o novo intervalo de datas.

Para sair do modo de ecrã cheia, pressione a tecla Esc .

Dica

O parque infantil oferece uma maneira fácil de descobrir operações e avaliá-las sem a necessidade de desenvolver um aplicativo. Lembre-se, você pode explorar essas operações usando o relatório de exemplo ou seu próprio relatório.

Trabalhar com eventos subscritíveis

Os eventos comunicam entre o conteúdo incorporado Power BI e a sua aplicação. Um aplicativo pode gerar eventos em resposta a ações automatizadas (a renderização de um relatório) ou ações do utente (uma seleção de botão).

Isso também significa que seu aplicativo pode responder de forma significativa quando o relatório é carregado (o que gera o loaded evento) ou renderizado (rendered evento). Para obter mais informações, consulte Usar incorporação em fases.

Seu aplicativo pode responder quando um utente interage com um relatório incorporado Power BI . As seguintes ações do utente geram eventos que seu aplicativo pode assinar:

  • Seleção de um botão de relatório (buttonClicked evento)
  • Seleção de uma extensão de comando, que é um comando personalizado que seu aplicativo adiciona ao menu de contexto (commandTriggered evento)
  • Seleção de um hiperlink (dataHyperlinkClicked evento)
  • Seleção de um ponto de dados, como uma coluna de um gráfico de colunas visual (dataSelected evento)
  • Seleção de um relatório visual (visualClicked evento)
  • Alterar a página do relatório (pageChanged evento)

Considere o potencial para aprimorar seu aplicativo. Na Tailspin Toys, seu aplicativo de vendas pode escrever notas de interesse do cliente no banco de dados do aplicativo. Quando um utente seleciona um botão de relatório, o aplicativo abre uma janela de diálogo que solicita que ele insira suas anotações. A aplicação mantém os dados introduzidos e, em seguida, atualiza o relatório para mostrar os novos dados representados nos elementos visuais do relatório.

Unidades posteriores deste módulo demonstram como um aplicativo responde a vários eventos.

Além disso, outros eventos estão disponíveis para painéis, blocos de painel, a experiência de Perguntas e Respostas e relatórios incorporados no modo de exibição móvel. Para obter mais informações, consulte Como manipular eventos.

Interagir com marcadores

Os favoritos permitem que os utilizadores capturem o estado de uma Power BI página de relatório, incluindo filtros e o estado de visibilidade dos elementos do relatório. Quando aplicado, um marcador restaura o estado capturado na página do relatório. Você pode reproduzir uma série de favoritos, como uma apresentação de slides, que pode ser um dispositivo útil para contar histórias quando você está a apresentar para um público.

No seu aplicativo, você pode controlar programaticamente as experiências de marcação, onde você pode:

  • Gerencie os favoritos aplicando-os, capturando-os ou reproduzindo-os.
  • Aplique um marcador ou regresse à sessão de visualização atual.
  • Insira ou saia do modo de apresentação de slides de favoritos.
  • Mostrar ou ocultar o painel Favoritos .
  • Recupere uma lista de favoritos.
  • Acesse os favoritos e suas propriedades, talvez para apresentá-los em uma lista suspensa.

A imagem a seguir mostra as operações de favoritos que você pode explorar no Power BI Embedded Google Analytics Playground.

Imagem mostrando as operações de Bookmark que estão disponíveis no parque infantil e alinhadas com as experiências listadas anteriormente.

Na Tailspin Toys, seu aplicativo de vendas permite que os utilizadores capturem o estado atual de uma página de relatório incorporada como um marcador pessoal. Um marcador pessoal é visível apenas para o utente que o criou e permite que os utilizadores retornem a uma visão específica de interesse. O aplicativo persiste metadados de favoritos pessoais no banco de dados do aplicativo e apresenta uma lista suspensa de favoritos pessoais para que o utente possa reaplicá-los.

Uma unidade posterior deste módulo demonstra como um aplicativo pode usar favoritos.

Para obter mais informações, consulte Melhorar a experiência dos utilizadores com favoritos.

Produzir layouts de relatório dinâmicos

Você pode usar as APIs de layout para permitir que os utilizadores selecionem quais visuais e layouts desejam exibir.

A imagem a seguir mostra as operações de layout que você pode explorar no Power BI Embedded Google Analytics Playground.

Imagem mostrando as operações Layout, incluindo Aplicar layout personalizado, Verificar layout, Ocultar todos os cabeçalhos visuais, Mostrar todos os cabeçalhos visuais e Ocultar cabeçalho visual único.

Na Tailspin Toys, o aplicativo de vendas permite que os utilizadores definam o tamanho da página, a escala da ecrã e o layout das páginas. No layout de páginas, os utilizadores do aplicativo podem especificar um layout visual para cada visual. Também lhes permite mostrar ou redimensionar elementos visuais de interesse e ocultar outros elementos visuais.

Uma unidade posterior deste módulo demonstra como um aplicativo pode personalizar o layout do relatório.

Para obter mais informações, consulte Personalizar um layout de relatório.

Criar elementos visuais de relatório personalizados

A Power BI API do cliente inclui o pacote powerbi-report-authoring . Isto pacote é uma extensão da biblioteca powerbi-client para criar e personalizar visuais de forma programática e para escrever um Power BI relatório depois de carregado. Ele também permite que seu aplicativo edite relatórios incorporados Power BI .

Use a addPage função para adicionar uma página de criação e use a createVisual função para adicionar um novo visual com um layout padrão à página de criação.

A imagem a seguir mostra as operações de criação que você pode explorar no Power BI Embedded Google Analytics Playground.

Imagem mostrando as operações de criação, incluindo Criar uma página de criação, Criar um visual e outras.

Na Tailspin Toys, o aplicativo de vendas oferece uma experiência guiada que permite aos utilizadores configurar e personalizar novos visuais.

Uma unidade posterior deste módulo demonstra como um aplicativo pode permitir que os utilizadores criem visuais personalizados.

Para obter mais informações, consulte Visão geral da criação de relatórios.

Conduza um fluxo de trabalho de análise no contexto

O aplicativo incorpora Power BI conteúdo no elemento, hospedando o conteúdo dentro de div um iframe elemento. O iframe elemento cria uma separação entre o aplicativo e o conteúdo incorporado, garantindo que os dados estejam mais seguros. As APIs de cliente sempre se comunicam entre o aplicativo e o conteúdo incorporado. Como a comunicação é bidirecional, seu aplicativo pode gerar um fluxo de trabalho de análise no contexto:

  1. O utente navega dentro do aplicativo.
  2. A aplicação mostra um Power BI relatório que é filtrado para uma vista específica.
  3. O utente filtra interativamente os dados no relatório.
  4. O utente seleciona um botão para executar uma ação.
  5. O aplicativo responde executando algum código.

Imagem que mostra o fluxo de trabalho de análise no contexto conforme descrito nas etapas anteriores.