Introduzione

  • 12 minuti

Le API client di Microsoft Power BI consentono di incorporare il contenuto di Power BI usando JavaScript o TypeScript. Si tratta di una libreria client che fornisce il controllo programmatico dell'intera esperienza di incorporamento.

Nota

Per informazioni sulle nozioni di base delle API client di Power BI e su come vengono usate per incorporare il contenuto di Power BI, vedere il modulo Incorporare il contenuto di Power BI.

Oltre a incorporare il contenuto di Power BI, le API client consentono all'app di:

  • Applicare operazioni al contenuto, come ad esempio aggiungere un filtro del report.
  • Usare gli eventi, affinché l'app possa rispondere alle azioni dell'utente eseguite in un report, ad esempio la selezione di un pulsante.
  • Interagire con i segnalibri, applicandoli o creandone di nuovi.
  • Generare layout di report dinamici, che forniscono il controllo affinché gli utenti possano personalizzare l'esperienza del report.
  • Creare oggetti visivi del report personalizzati.
  • Implementare un flusso di lavoro di analisi nel contesto.

Applicare le operazioni

Esistono molte operazioni che l'app può applicare al contenuto incorporato. Queste operazioni includono operazioni generali come il ricaricamento o l'aggiornamento di un report. Includono anche la possibilità di attivare o disattivare la modalità A schermo intero o la possibilità di applicare nuovamente le impostazioni applicate dall'app nell'oggetto di configurazione durante il primo incorporamento del contenuto.

Oltre alle operazioni generali, sono disponibili operazioni di spostamento nelle pagine. È inoltre possibile accedere alle operazioni di filtro e di filtro dei dati, che consentono all'app di determinare o impostare lo stato di filtro/filtro dei dati. Altre operazioni utili sono quelle sui dati che consentono l'esportazione di dati visivi e le operazioni di menu che estendono i menu con nuovi comandi personalizzati.

È possibile sperimentare alcune di queste operazioni passando a Power BI Embedded Analytics Playground e seguendo le istruzioni seguenti.

Nota

Il playground di analisi incorporata di Power BI è un sito Web che consente di apprendere, esplorare e provare l'analisi incorporata di Power BI. Include un ambiente sandbox per sviluppatori per esperienze pratiche che usano le API client con contenuti di Power BI di esempio o contenuti personalizzati. I frammenti di codice e le presentazioni sono disponibili anche per l'esplorazione.

Per altre informazioni, vedere Che cos'è il playground di analisi incorporata di Power BI?

Nel riquadro a sinistra selezionare Sandbox per sviluppatori.

Immagine che mostra il riquadro sinistro con l'opzione Sandbox sviluppatore evidenziata.

Quando richiesto, selezionare il pulsante Use sample (Usa esempio) per iniziare usando un report di esempio.

Immagine che mostra il pulsante Usa esempio evidenziato nella finestra di dialogo Usa un report di esempio.

Suggerimento

È anche possibile selezionare il proprio report originato dal servizio Power BI oppure usare un token di incorporamento generato dall'app di sviluppo. In questa attività si continuerà a usare il report di esempio.

Il playground incorpora un report di esempio e sopra il report è il riquadro del codice che contiene il codice necessario per incorporare, caricare ed eseguire il rendering del report.

Nel riquadro API report incorporato espandere il gruppo Operazioni generali.

Immagine che mostra il gruppo Operazioni generali espanso nel riquadro API Report incorporato.

Per aggiornare il codice, dal riquadro API report incorporato trascinare l'operazione Full screen e rilasciarla sull'ultima riga (riga 94) nel riquadro del codice.

Immagine che mostra l'operazione Full screen con una freccia che indica dove rilasciarla nel riquadro del codice.

Esaminare il frammento di codice aggiunto al riquadro del codice. Quindi, per eseguire il codice, sulla barra dei menu sopra il riquadro del codice, selezionare Esegui.

Immagine che mostra la barra dei menu con l'opzione di menu Esegui evidenziata.

Il rendering del report viene eseguito in modalità schermo intero. Per uscire dalla modalità A schermo intero, premere ESC.

A questo punto, è possibile modificare a livello di codice il filtro dei dati data del report. Nel riquadro API report incorporato espandere il gruppo Filtri e filtri dei dati.

Immagine che mostra il gruppo Filtri e filtri dei dati espanso nel riquadro API report incorporato.

Trascinare l'operazione Set slicer state (Imposta stato del filtro dei dati) nel riquadro del codice, rilasciandola sotto l'ultima riga di codice. Esaminare quindi le 43 righe di codice aggiunte al riquadro del codice. Eseguire il codice. Notare che il report continua a essere aperto in modalità A schermo intero. L'intervallo di date del filtro dei dati Date deve essere impostato su 12 ottobre 2014 - 27 novembre 2014.

Immagine che mostra i filtri dei dati Date e il nuovo intervallo di date.

Per uscire dalla modalità A schermo intero, premere ESC.

Suggerimento

Il playground offre un modo semplice per individuare le operazioni e valutarle senza la necessità di sviluppare un'app. Tenere presente che è possibile esplorare queste operazioni usando il report di esempio o un report personalizzato.

Usare gli eventi sottoscrivibili

Gli eventi sono comunicazioni tra il contenuto di Power BI incorporato e l'app. Un'app può generare eventi in risposta ad azioni automatizzate, ad esempio il rendering di un report, o ad azioni dell'utente, come la selezione di un pulsante.

Significa che l'app può rispondere in modo significativo durante il caricamento del report (che genera l'evento loaded) o il rendering del report (evento rendered). Per altre informazioni, vedere Usare l'incorporamento in più fasi.

L'app può rispondere quando un utente interagisce con un report di Power BI incorporato. Le azioni utente seguenti generano eventi che l'app può sottoscrivere:

  • Selezione di un pulsante del report (evento buttonClicked)
  • Selezione di un'estensione di comando, ovvero un comando personalizzato che l'app aggiunge al menu contestuale (evento commandTriggered)
  • Selezione di un collegamento ipertestuale (evento dataHyperlinkClicked)
  • Selezione di un punto dati, ad esempio una colonna di un oggetto visivo grafico a colonne (evento dataSelected)
  • Selezione di un oggetto visivo del report (evento visualClicked)
  • Modifica di una pagina del report (evento pageChanged)

Valutare il potenziale per migliorare l'app. In Tailspin Toys l'app di vendita può eseguire il writeback delle note sul cliente di interesse nel database dell'app. Quando un utente seleziona un pulsante del report, l'app apre una finestra di dialogo che richiede di immettere le note. L'app salva in modo permanente i dati immessi e aggiorna il report in modo da visualizzare i nuovi dati che vengono rappresentati negli oggetti visivi del report.

Le unità successive di questo modulo illustrano in che modo un'app risponde a vari eventi.

Sono disponibili anche altri eventi per i dashboard, i riquadri di dashboard, l'esperienza di Domande e risposte e i report incorporati nella visualizzazione per dispositivi mobili. Per altre informazioni, vedere Come gestire gli eventi.

Interagire con i segnalibri

I segnalibri consentono agli utenti di acquisire lo stato di una pagina del report di Power BI, inclusi i filtri e lo stato di visibilità degli elementi del report. Quando applicato, un segnalibro ripristina lo stato acquisito alla pagina del report. È possibile riprodurre una serie di segnalibri come una presentazione. Questa funzionalità può essere utile per la narrazione di storie durante le presentazioni a un pubblico.

Nell'app è possibile controllare a livello di codice le esperienze di impostazione dei segnalibri. È possibile:

  • Gestire i segnalibri mediante applicazione, acquisizione o riproduzione.
  • Applicare un segnalibro o tornare alla sessione di visualizzazione corrente.
  • Entrare o uscire dalla modalità di presentazione con segnalibri.
  • Mostrare o nascondere il riquadro Segnalibri.
  • Recuperare un elenco di segnalibri.
  • Accedere ai segnalibri e alle relative proprietà, ad esempio per presentarli in un elenco a discesa.

L'immagine seguente mostra le operazioni sui segnalibri che è possibile esplorare nel playground di analisi incorporata di Power BI.

Immagine che mostra le operazioni segnalibro disponibili nel playground e allineate alle esperienze elencate in precedenza.

In Tailspin Toys l'app di vendita consente agli utenti di acquisire lo stato corrente di una pagina del report incorporato come segnalibro personale. Un segnalibro personale è visibile solo all'utente che lo ha creato e gli consente di tornare a una visualizzazione di interesse specifica. L'app salva in modo permanente i metadati dei segnalibri personali nel database dell'app e presenta un elenco a discesa di segnalibri personali che l'utente potrà riapplicare.

Un'unità successiva di questo modulo illustra come un'app può usare i segnalibri.

Per altre informazioni, vedere Ottimizzare l'esperienza degli utenti con i segnalibri.

Generare layout di report dinamici

È possibile usare le API di layout per consentire agli utenti di selezionare gli oggetti visivi e i layout che desiderano visualizzare.

L'immagine seguente mostra le operazioni di layout che è possibile esplorare nel playground di analisi incorporata di Power BI.

Immagine che mostra le operazioni di layout, tra cui Applica layout personalizzato, Controlla layout, Nascondi tutte le intestazioni visive, Mostra tutte le intestazioni visive e Nascondi intestazione di un singolo oggetto visivo.

In Tailspin Toys l'app di vendita consente agli utenti di definire le dimensioni della pagina, la scala dell'area di disegno e il layout delle pagine. All'interno del layout delle pagine, gli utenti dell'app possono specificare un layout visivo per ogni oggetto visivo. Possono inoltre visualizzare o ridimensionare gli oggetti visivi di interesse e nasconderne altri.

Un'unità successiva di questo modulo illustra come un'app può personalizzare il layout del report.

Per altre informazioni, vedere Personalizzare un layout di report.

Creare oggetti visivi del report personalizzati

L'API client di Power BI include il pacchetto powerbi-report-authoring. Questo pacchetto è un'estensione della libreria powerbi-client per la creazione e la personalizzazione degli oggetti visivi a livello di codice e per la scrittura di un report di Power BI dopo che è stato caricato. Consente anche all'app di modificare i report di Power BI incorporati.

Usare la funzione addPage per aggiungere una pagina di creazione e quindi la funzione createVisual per aggiungere un nuovo oggetto visivo con un layout predefinito alla pagina di creazione.

L'immagine seguente mostra le operazioni di creazione che è possibile esplorare nel playground di analisi incorporata di Power BI.

Immagine che mostra le operazioni di creazione, tra cui Creare una pagina di creazione, Creare un oggetto visivo e altri.

In Tailspin Toys l'app di vendita offre un'esperienza guidata che consente agli utenti di configurare e personalizzare nuovi oggetti visivi.

Un'unità successiva di questo modulo illustra come un'app può consentire agli utenti di creare oggetti visivi personalizzati.

Per altre informazioni, vedere Panoramica della creazione di report.

Implementare un flusso di lavoro di analisi nel contesto

L'app incorpora il contenuto di Power BI nell'elemento div, ospitando il contenuto all'interno di un elemento iframe. L'elemento iframe crea una separazione tra l'app e il contenuto incorporato. In questo modo i dati sono più al sicuro. Le API client comunicano sempre tra l'app e il contenuto incorporato. Poiché la comunicazione è bidirezionale, l'app può gestire un flusso di lavoro di analisi nel contesto:

  1. L'utente si sposta all'interno dell'app.
  2. L'app mostra un report di Power BI filtrato in base a una visualizzazione specifica.
  3. L'utente filtra in modo interattivo i dati nel report.
  4. L'utente seleziona un pulsante per eseguire un'azione.
  5. L'app risponde con l'esecuzione di codice.

Immagine che mostra il flusso di lavoro di analisi nel contesto, come descritto nei passaggi precedenti.