¿Cuál es el puente de escritorio Power BI? (Versión preliminar)

El puente de escritorio de Power BI permite que las aplicaciones y agentes externos interactúen directamente con una instancia en ejecución de Power BI Desktop en el equipo local.

Nota:

El Puente de escritorio está actualmente en versión preliminar. Las características, el comportamiento y la API pueden cambiar antes de su disponibilidad general.

En este artículo, aprenderá lo siguiente:

  • Requisitos previos que necesita antes de usar el puente
  • Qué es el puente y cómo se comunica con Power BI Escritorio
  • Cómo empezar a trabajar rápidamente con la CLI de Power BI Desktop Bridge
  • Detección de métodos de API disponibles mediante una llamada a bridge.manifest
  • Métodos disponibles y lo que hacen
  • Cómo la función de creación de informes usa el puente

Prerequisites

Antes de usar el puente IPC, asegúrese de cumplir los siguientes requisitos:

  • Power BI Desktop está instalado en la máquina Windows.

  • La característica de versión preliminar "Habilitar el acceso de herramientas externas a Power BI Escritorio a través de API locales seguras" está habilitada. Está activado de forma predeterminada. Para comprobarlo o cambiarlo:

    1. Abra Power BI Escritorio.
    2. Vaya a Archivo>Opciones y configuración>Opciones.
    3. Seleccione Características de vista previa.
    4. Seleccione Permitir que las herramientas externas accedan a Power BI Desktop mediante API locales seguras.

    Captura de pantalla que muestra Habilitar el acceso de herramientas externas a Power BI Escritorio a través de API locales seguras.

¿Cuál es el puente de escritorio Power BI?

El puente de Power BI de escritorio permite que las herramientas externas se comuniquen con una instancia en ejecución de Power BI Desktop a través de las API que expone. Con el puente, los agentes y las herramientas externas pueden interactuar directamente con Power BI Escritorio para volver a cargar los cambios sin reiniciar la aplicación, tomar capturas de pantalla para la validación y mucho más.

Un buen ejemplo de cómo aprovechar el puente es la aptitud de creación de informes , , que usa el puente para leer definiciones de informe, aplicar cambios y comprobar los resultados en un flujo de trabajo de edición y comprobación iterativos.

Detalles técnicos

El puente es un servidor local que se ejecuta dentro del proceso de Power BI Escritorio. Usa IPC (comunicación entre procesos) a través de una canalización con nombre con el formato :

pbi-desktop-bridge-{processId}

Hechos principales

Hecho Detalle
Transporte Canalización con nombre (solo local)
Protocolo JSON-RPC 2.0
Encuadre Encabezado de longitud de contenido + cuerpo
Acceso remoto No soportado
Varias ventanas Cada ventana de escritorio abierta tiene su propia canalización independiente
Concurrencia Varios clientes pueden conectarse, pero solo se ejecuta una operación a la vez.
Si envía una solicitud mientras se ejecuta otra operación, recibirá un error. Espere a que la operación actual finalice primero.

Uso del puente de escritorio con la CLI de puente de escritorio de Power BI

La manera más fácil de empezar es con la CLI de Power BI Desktop Bridge. Permite aprovechar el puente de una manera sencilla y práctica, sin necesidad de crear primero integraciones personalizadas. Construido sobre el puente, incluye un conjunto de comandos intuitivos listos para usar.

Los siguientes comandos están disponibles en powerbi-desktop help:

Command Descripción
status [options]  Enumera las instancias de Desktop Bridge, las rutas de archivo actuales, el estado de los cambios sin guardar y las páginas PBIR.
manifest [options]  Muestra el manifiesto de Desktop Bridge de un proceso de Power BI Desktop en ejecución.
open [options] <report>  Abre un archivo PBIP/PBIX en Power BI Desktop y, a continuación, espera a que se compruebe el estado del puente.
reload [options]  Recarga el archivo PBIR actual en Power BI Desktop.
screenshot [options] <page-id>  Captura una página de informe como PNG.
screenshot-all [options]  Captura todas las páginas enumeradas en PBIR pages.json.
help [command]  Muestra ayuda para un comando.

Más información: CLI de Power BI Desktop Bridge

Métodos de puente de escritorio disponibles

Los métodos disponibles son: bridge.manifest, application.state.get/v1, report.snapshot.capture/v1y file.reload/v1.

bridge.manifest

Devuelve el manifiesto del método para la versión actual de Power BI Desktop.

  • Úselo para:

  • Descubra qué métodos se admiten actualmente.

  • Obtiene la descripción de cada método.

  • Lea el esquema de entrada y salida de cada método (params y result) antes de llamarlo.

    • Benefits:

  • Impide llamar a métodos no admitidos.

  • Ayuda a evitar -32601 MethodNotFound errores.

Devuelve:

Matriz methods que contiene definiciones de método como:

  • name
  • description
  • params esquema
  • result esquema

application.state.get/v1

Devuelve el estado actual de la aplicación, incluido el estado de archivo abierto.

Lo que se usa para:

  • Compruebe qué archivo está abierto actualmente.
    • Detecte cambios no guardados antes de ejecutar operaciones que podrían sobrescribir o volver a cargar contenido.
  • Actúe como comprobación de estado de archivo antes de los pasos de automatización.

Devuelve:

Campo Type Descripción
currentFilePath cadena o null Ruta de acceso completa del archivo abierto. Está vacío si no hay ninguna.
hasUnsavedChanges boolean Indica si el archivo tiene cambios no guardados.

Nota:

Este método se centra actualmente en el estado del archivo y puede exponer más detalles de estado en versiones futuras.

report.snapshot.capture/v1

Captura una captura de pantalla PNG de una página de informe.

Lo que se usa para:

  • Validación visual de los cambios del informe.
  • Bucles de comentarios en los que un agente necesita ver el estado actual del informe.
  • Inspección rápida de la página representada.

Parámetros:

Campo Type Obligatorio Descripción
pageId string Sí Id. de página interna de PBIR.
scale  number o null .\Test-DesktopBridge.ps1 -Silent Factor de escala (1,0–3,0). Su valor predeterminado es 1.0.

Devuelve:

Campo Descripción
payload Datos de imagen codificados en Base64.
mimeType Por ejemplo: image/png.
encoding Por ejemplo: Base64.
pageId Identificador de la página capturada.
pageDisplayName Nombre de página legible para personas.

Nota:

De hecho, se trata de una operación de captura de pantalla para una página de informe específica.

file.reload/v1

Recarga el archivo PBIP/PBIR abierto actualmente desde el disco. Útil después de realizar modificaciones manuales en los archivos de informe.

Lo que se usa para:

  • Actualice el estado de escritorio después de los cambios en el disco.
  • Controlar si la definición del modelo también se vuelve a aplicar.

Parámetros:

Campo Type Obligatorio Descripción
reloadModelDefinition booleano o null Sí Si se va a volver a aplicar la definición del modelo. Tiene como valor predeterminado true.

Devuelve:

Campo Descripción
success true cuando la recarga se completó correctamente.

Nota de comportamiento:

  • reloadModelDefinition = true (valor predeterminado): vuelve a cargar el informe más la definición del modelo semántico.
  • reloadModelDefinition = false: vuelve a cargar el informe sin volver a aplicar la definición del modelo.

Contenido relacionado

  • Last updated on