Incorporar relatórios do Power BI

  • 8 minutos

Os relatórios do Power BI são o tipo de conteúdo incorporado mais frequentemente devido ao grande número de tipos de elementos visuais (incluindo IA e elementos visuais personalizados) e funcionalidades interativas.

Pode incorporar um relatório do Power BI em três modos diferentes:

  • Incorporar um relatório do Power BI existente
  • Editar um relatório incorporado
  • Incorporar um novo relatório do Power BI

Para cada modo, pode definir muitas propriedades do objeto de configuração para especificar com precisão como a aplicação apresenta o relatório. A type propriedade do objeto de configuração está sempre definida como relatório.

Incorporar um relatório existente

Ao incorporar um relatório existente, utilize um objeto de configuração do tipo IReportLoadConfiguration. Além das propriedades necessárias (descritas na Unidade 1), a aplicação pode definir as seguintes propriedades opcionais.

  • contrastMode e theme - Opcional. Controle o tema e o nível de contraste que o conteúdo incorporado utiliza. Por predefinição, qualquer conteúdo que tenha incorporado é apresentado com o tema predefinido e sem contraste. Pode substituir este comportamento ao configurar um tema ou nível de contraste específico. Para obter mais informações, veja Temas e modo de alto contraste.
  • pageName - Opcional. Controla a página do relatório incorporado que é apresentada inicialmente. Quando não estiver definido, abre a página selecionada quando o autor guardou o relatório pela última vez.
  • filters - Opcional. Define o estado do filtro. Considere definir o estado do filtro com base no contexto da aplicação, talvez para filtrar pela região de vendas do utilizador da aplicação. Para obter mais informações, veja Controlar filtros de relatórios.
  • slicers - Opcional. Tal como os filtros, é possível definir o estado da segmentação de dados. Para obter mais informações, veja Controlar segmentações de dados de relatórios.
  • bookmark - Opcional. Aplicar um marcador específico.
  • datasetBinding - Opcional. Liga o relatório a um conjunto de dados diferente que define o esquema de dados ao qual o relatório incorporado se liga. Para obter mais informações, veja Vincular conjuntos de dados dinamicamente a um relatório.
  • permissions - Opcional. Concede operações que o utilizador pode fazer. As opções de operação incluem criar, ver, editar, guardar ou guardar uma cópia do relatório. A edição e criação de relatórios é abordada mais à frente nesta unidade.
  • viewMode - Opcional. Determina se o relatório é aberto no modo de visualização (predefinição) ou no modo de edição. Conforme descrito anteriormente, a aplicação tem de conceder permissões de edição para ativar o modo de edição.
  • settings - Opcional. Ajusta o aspeto e o comportamento do relatório. Pode mostrar e expandir painéis abertos para trabalhar com marcadores, campos, filtros, navegação de páginas, seleção, segmentações de dados de sincronização ou visualizações. Também pode definir o tipo de esquema como vista móvel ou definir definições de região, que especificam o idioma e a formatação do relatório. Para obter mais informações, veja Personalizar definições.

Nota

Em muitos casos, é possível alterar as definições após o carregamento do relatório, talvez em resposta às interações do utilizador.

Experimente como a sua aplicação pode incorporar um relatório do Power BI ao aceder ao playground de análise incorporada do Power BI e ao seguir as seguintes instruções.

Nota

O playground de análise incorporada do Power BI é um site que o ajuda a aprender, explorar e experimentar a análise incorporada do Power BI. Inclui um sandbox para programadores para experiências práticas que utilizam as APIs cliente com conteúdo do Power BI de exemplo ou o seu próprio conteúdo. Os fragmentos de código e as apresentações também estão disponíveis para explorar.

Para obter mais informações, consulte O que é o playground de análise incorporado do Power BI?

No painel esquerdo, selecione Explorar as nossas APIs.

Captura de ecrã do painel esquerdo com a opção Explorar as nossas APIs realçada.

No painel de conteúdos, repare na lista pendente Exemplo e na lista pendente modo Incorporado adjacente. Por predefinição, ambas as listas pendentes estão definidas para apresentar um relatório do Power BI no modo de visualização.

Captura de ecrã de duas listas pendentes definidas para apresentar um relatório do Power BI no modo de visualização.

Para ver como o relatório foi incorporado, selecione Mostrar código de exemplo no canto superior esquerdo do painel.

Captura de ecrã da barra de menus com o comando Mostrar código de exemplo realçado.

Na janela fragmento de código, analise o código ao deslocar-se verticalmente de cima para baixo. Procure as linhas de código que criam o objeto de configuração e incorporam o relatório (cerca de metade para baixo).

// Create the embed configuration object for the report
// For more information see https://go.microsoft.com/fwlink/?linkid=2153590
let config = {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: embedReportId,
    permissions: permissions,
    settings: {
        panes: {
            filters: {
                visible: true
            },
            pageNavigation: {
                visible: true
            }
        }
    }
};

// Get a reference to the embedded report HTML element
let embedContainer = $('#embedContainer')[0];

// Embed the report and display it within the div container.
report = powerbi.embed(embedContainer, config);```

Repare que o objeto de configuração define os filtros e os painéis de navegação de páginas como visíveis.

Editar um relatório incorporado

Para permitir que o utilizador edite um relatório incorporado, utilize um objeto de configuração do tipo IReportLoadConfiguration. Defina a viewMode propriedade como models.ViewMode.Edit.

Para obter informações sobre permissões de token de acesso para editar um relatório, consulte Criar, editar e guardar um relatório incorporado. Quando o utilizador tem Copy permissão, pode guardar a cópia do relatório utilizando Guardar Como.

No playground de análise incorporada do Power BI, na lista pendente Modo incorporado , selecione Modo de edição.

Captura de ecrã da lista pendente Modo incorporado definida como Modo de edição.

O relatório incorporado tem agora a barra de ação na parte superior do relatório. Inclui o comando Guardar , que está localizado na extremidade direita do relatório. Agora, é possível alterar o relatório e (tentar) guardar o relatório editado.

Nota

Tentar guardar o relatório no playground de análise incorporada do Power BI produzirá um erro porque se trata de uma aplicação de exemplo.

Abra a janela de fragmento de código e localize a instrução que cria o objeto de configuração . Repare que a propriedade viewMode está definida como Editar.

viewMode: models.ViewMode.Edit,

Selecione Cancelar para fechar a janela de fragmento de código.

Incorporar um novo relatório

Para incorporar um novo relatório, utilize um objeto de configuração do tipo IReportCreateConfiguration. As propriedades nesta interface são semelhantes às propriedades do objeto de configuração de carga do relatório, com as duas exceções seguintes:

  • datasetId - Necessário. O DatasetID ao qual o novo relatório se liga.

  • embedUrl - Necessário. O URL de incorporação do conjunto de dados.

Tem de definir a permissions propriedade para permitir a criação de um relatório (Create e All).

Para obter informações sobre as permissões de token de acesso para criar e guardar um relatório, consulte Criar, editar e guardar um relatório incorporado.

No playground de análise incorporada do Power BI, na lista pendente Modo incorporado , selecione Criar modo.

Captura de ecrã a mostrar a lista pendente Modo incorporado definida como Modo de criação.

O relatório incorporado tem agora a barra de ação na parte superior do relatório. Inclui o menu Ficheiro , que está localizado na extremidade esquerda do relatório. Agora, é possível (tentar) guardar o relatório.

Nota

Tentar guardar o relatório no playground de análise incorporada do Power BI produzirá um erro porque se trata de uma aplicação de exemplo.

Abra a janela de fragmento de código e localize a instrução que cria o objeto embedCreateConfiguration . Repare que o código define a propriedade datasetId .

// This object is used when calling powerbi.createReport.
let embedCreateConfiguration = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    datasetId: embedDatasetId,
};

Selecione Cancelar para fechar a janela de fragmento de código.

Para obter uma descrição completa sobre como incorporar relatórios do Power BI, veja Incorporar um relatório.