Che cos'è Power BI Desktop Bridge? (anteprima)

Il Power BI Desktop Bridge consente alle applicazioni e agli agenti esterni di interagire direttamente con un'istanza in esecuzione di Power BI Desktop nel computer locale.

Annotazioni

Desktop Bridge è attualmente in anteprima. Le funzionalità, il comportamento e la superficie dell'API possono cambiare prima della disponibilità generale.

In questo articolo, imparerai a:

  • Quali prerequisiti sono necessari prima di usare il bridge
  • Che cos'è il bridge e come comunica con Power BI Desktop
  • Come iniziare rapidamente a usare l'interfaccia della riga di comando di Power BI Desktop Bridge
  • Come individuare i metodi API disponibili chiamando bridge.manifest
  • Metodi disponibili e operazioni eseguite
  • Come la funzionalità di creazione di report utilizza il bridge

Prerequisites

Prima di usare il bridge IPC, assicurarsi di soddisfare i requisiti seguenti:

  • Power BI Desktop è installato nel computer Windows.

  • La funzionalità di anteprima "Abilitare l'accesso degli strumenti esterni a Power BI Desktop tramite API locali sicure" è abilitata. È attivata per impostazione predefinita. Per controllarlo o modificarlo:

    1. Apri Power BI Desktop.
    2. Vai a File>Opzioni e impostazioni>Opzioni.
    3. Selezionare Funzionalità di anteprima.
    4. Controllare Abilitare l'accesso degli strumenti esterni a Power BI Desktop tramite API locali sicure.

    Screenshot che mostra l'opzione Abilita l'accesso esterno agli strumenti esterni per Power BI Desktop tramite API locali sicure.

Che cos'è Power BI Desktop Bridge?

Il Power BI Desktop Bridge consente agli strumenti esterni di comunicare con un'istanza in esecuzione di Power BI Desktop tramite le API esposte. Usando il bridge, gli agenti e gli strumenti esterni possono interagire direttamente con Power BI Desktop per ricaricare le modifiche senza riavviare l'app, acquisire screenshot per la convalida e altro ancora.

Un ottimo esempio di come sfruttare il bridge è la competenza creazione report, , che usa il bridge per leggere le definizioni del report, applicare le modifiche e verificare i risultati in un flusso di lavoro iterativo di modifica e verifica.

Dettagli tecnici

Il bridge è un server locale in esecuzione all'interno del processo Power BI Desktop. Si usa IPC (comunicazione interprocesso) tramite una pipe denominata con il formato:

pbi-desktop-bridge-{processId}

Fatti chiave

Fatto Detail
Trasporto Pipe con nome (solo locale)
Protocollo JSON-RPC 2.0
Inquadratura Intestazione content-Length + corpo
Accesso remoto Non supportato
Più finestre Ogni finestra aperta del desktop ha una propria pipe indipendente
Concorrenza Più client possono connettersi, ma viene eseguita una sola operazione alla volta.
Se si invia una richiesta mentre è in esecuzione un'altra operazione, viene visualizzato un errore. Attendere il completamento dell'operazione corrente.

Usare Desktop Bridge con Power BI Desktop Bridge CLI

Il modo più semplice per iniziare consiste nell'interfaccia della riga di comando di Power BI Desktop Bridge. Consente di sfruttare il bridge in modo semplice, pratico, senza prima creare integrazioni personalizzate. Costruito sopra il bridge, include una serie di comandi intuitivi pronti per l'uso.

I comandi seguenti sono disponibili in powerbi-desktop help:

Comando Descrizione
status [options]  Elenca le istanze di Desktop Bridge, i percorsi dei file correnti, lo stato di modifica non salvato e le pagine PBIR.
manifest [options]  Mostra il manifesto di Desktop Bridge per un processo di Power BI Desktop in esecuzione.
open [options] <report>  Apre un file PBIP/PBIX in Power BI Desktop, quindi attende lo stato del bridge.
reload [options]  Ricarica il file PBIR corrente in Power BI Desktop.
screenshot [options] <page-id>  Cattura una pagina del report in formato PNG.
screenshot-all [options]  Cattura ogni pagina elencata in PBIR pages.json.
help [command]  Visualizza la guida per un comando.

Ulteriori informazioni: Power BI Desktop Bridge CLI

Metodi di Desktop Bridge disponibili

I metodi disponibili sono: bridge.manifest, application.state.get/v1, report.snapshot.capture/v1e file.reload/v1.

bridge.manifest

Restituisce il manifesto del metodo per la versione corrente di Power BI Desktop.

  • Usarlo per:

  • Individuare i metodi attualmente supportati.

  • Ottenere la descrizione di ogni metodo.

  • Leggere lo schema di input/output di ogni metodo (params e result) prima di chiamarlo.

    • Vantaggi:

  • Impedisce di chiamare metodi non supportati.

  • Aiuta a evitare errori -32601 MethodNotFound.

restituisce:

Matrice methods contenente definizioni di metodo, ad esempio:

  • name
  • description
  • params Schema
  • result Schema

application.state.get/v1

Restituisce lo stato dell'applicazione corrente, incluso lo stato open-file.

Cosa viene usato per:

  • Controllare quale file è attualmente aperto.
    • Rilevare le modifiche non salvate prima di eseguire operazioni che potrebbero sovrascrivere o ricaricare il contenuto.
  • Agire come controllo dello stato del file prima dei passaggi di automazione.

restituisce:

Field Type Descrizione
currentFilePath stringa o null Percorso completo del file aperto. Vuoto se non c'è niente.
hasUnsavedChanges Boolean Indica se il file ha modifiche non salvate.

Annotazioni

Questo metodo è attualmente incentrato sullo stato del file e può esporre altri dettagli sullo stato nelle versioni future.

report.snapshot.capture/v1

Cattura una schermata in formato PNG di una pagina del report.

Cosa viene usato per:

  • Convalida visiva delle modifiche del report.
  • Cicli di feedback in cui un agente deve visualizzare lo stato corrente del report.
  • Ispezione rapida della pagina renderizzata.

Parametri:

Field Type Obbligatorio Descrizione
pageId string Yes ID della pagina interna di PBIR.
scale  number o null .\Test-DesktopBridge.ps1 -Silent Fattore di scala (1,0-3,0). Il valore predefinito è 1.0.

restituisce:

Field Descrizione
payload Dati dell'immagine con codifica Base64.
mimeType Ad esempio: image/png.
encoding Ad esempio: Base64.
pageId ID della pagina acquisita.
pageDisplayName Nome della pagina leggibile dall'utente.

Annotazioni

Si tratta in effetti di un'operazione di screenshot per una pagina del report specifica.

file.reload/v1

Ricarica il file PBIP/PBIR attualmente aperto dal disco. Utile dopo aver apportato modifiche manuali ai file di report.

Cosa viene usato per:

  • Aggiornare lo stato del desktop dopo le modifiche apportate al disco.
  • Controllare se la definizione del modello viene applicata nuovamente.

Parametri:

Field Type Obbligatorio Descrizione
reloadModelDefinition booleano o null Yes Se applicare nuovamente la definizione del modello. Di default è true.

restituisce:

Field Descrizione
success true quando il ricaricamento è stato completato correttamente.

Nota comportamento:

  • reloadModelDefinition = true (impostazione predefinita): ricarica il report e la definizione del modello semantico.
  • reloadModelDefinition = false: ricarica il report senza riapplicare la definizione del modello.

Contenuti correlati

  • Last updated on