Introducción

  • 12 minutos

Puede usar las API de cliente de Microsoft Power BI para insertar contenido de Power BI mediante JavaScript o TypeScript. Es una biblioteca cliente que proporciona control mediante programación de toda la experiencia de inserción.

Nota

Para obtener información sobre los conceptos básicos de las API de cliente de Power BI y cómo se usan para insertar contenido de Power BI, consulte el módulo Insertar contenido de Power BI.

Más allá de insertar contenido de Power BI, las API de cliente permiten que la aplicación:

  • Aplique operaciones al contenido, como agregar un filtro de informe.
  • Trabaje con eventos para que la aplicación pueda responder a las acciones de usuario realizadas en un informe, como la selección de un botón.
  • Interactúe con marcadores, aplicándolos o creando otros nuevos.
  • Genere diseños de informe dinámicos, que proporcionan control para que los usuarios puedan personalizar la experiencia del informe.
  • Cree objetos visuales del informe personalizados.
  • Impulse un flujo de trabajo de análisis en contexto.

Aplicar operaciones

La aplicación puede aplicar muchas operaciones al contenido insertado. Estas operaciones engloban operaciones generales, como recargar o actualizar un informe. También ofrecen la posibilidad de entrar o salir del modo de pantalla completa, o se puede volver a aplicar la configuración que la aplicación aplicó en el objeto de configuración al insertar el contenido por primera vez.

Además de las operaciones generales, también están disponibles las operaciones de navegación por páginas. Además, tiene acceso a las operaciones de filtrado y segmentación, que permiten a la aplicación determinar o establecer el estado de filtro o segmentación. Otras operaciones útiles incluyen operaciones con datos que permiten exportar datos visuales y operaciones de menú que amplían los menús con nuevos comandos personalizados.

Para experimentar algunas de estas operaciones, vaya al área de juegos de análisis de Power BI Embedded y siga las instrucciones que se indican a continuación.

Nota

El Área de juegos de análisis integrado de Power BI es un sitio web que facilita el aprendizaje, la exploración y la prueba del análisis integrado de Power BI. Incluye un espacio aislado para desarrolladores para experiencias prácticas que usan las API de cliente con contenido de Power BI de ejemplo o el suyo propio. Los fragmentos de código y las presentaciones también están disponibles para explorar.

Para más información, consulte Introducción al área de juegos de análisis integrado de Power BI.

En el panel izquierdo, seleccione Espacio aislado para desarrolladores.

Imagen que muestra el panel izquierdo con la opción Espacio aislado para desarrolladores resaltada.

Cuando se le solicite, seleccione el botón Usar muestra para empezar con un informe de muestra.

Imagen que muestra el botón Usar ejemplo resaltado en el cuadro de diálogo Usar un informe de ejemplo.

Sugerencia

También puede seleccionar su propio informe procedente del servicio de Power BI o usar un token de inserción que genera la aplicación de desarrollo. En esta actividad, seguirá usando el informe de ejemplo.

El área de juegos inserta un informe de ejemplo y encima del informe está el panel de código que contiene el código necesario para insertar, cargar y representar el informe.

En el panel API del informe incrustadas, expanda el grupo Operaciones generales.

Imagen que muestra el grupo Operaciones generales expandido en el panel API del informe incrustadas.

Para actualizar el código, desde el panel API del informe incrustadas, arrastre la operación Pantalla completa y colóquela en la última línea (línea 94) del panel de código.

Imagen que muestra la operación de Pantalla completa con una flecha que indica dónde colocarla en el panel de código.

Revise el fragmento de código agregado al panel de código. A continuación, para ejecutar el código, en la barra de menús que está encima del panel de código, seleccione Ejecutar.

Imagen que muestra la barra de menús con la opción de menú Ejecutar resaltada.

El informe se representa en modo de pantalla completa. Para salir del modo de pantalla completa, presione la tecla Esc.

Ahora, modificará mediante programación la segmentación de fechas del informe. En el panel API del informe incrustadas, expanda el grupo Filtros y segmentaciones.

Imagen que muestra el grupo Filtros y segmentaciones expandido en el panel API del informe incrustadas.

Arrastre la operación Establecer estado de segmentación al panel de código y colóquela debajo de la última línea de código. A continuación, revise las 43 líneas de código que agregó al panel de código. Ejecute el código y observe que el informe continúa abierto en modo de pantalla completa. El intervalo de fechas de segmentación de Fecha debe establecerse en 12 de octubre de 2014 a 27 de noviembre de 2014.

Imagen que muestra las segmentaciones de Fecha y el nuevo intervalo de fechas.

Para salir del modo de pantalla completa, presione la tecla Esc.

Sugerencia

El área de juegos proporciona una manera sencilla de detectar operaciones y evaluarlas sin necesidad de desarrollar una aplicación. Recuerde que puede explorar estas operaciones mediante el informe de muestra o su propio informe.

Trabajar con eventos a los que se puede suscribir

Los eventos se comunican entre el contenido integrado de Power BI y la aplicación. Una aplicación puede generar eventos en respuesta a acciones automatizadas (la representación de un informe) o acciones de usuario (la selección de un botón).

También significa que la aplicación puede responder de forma significativa cuando se carga el informe (que genera el evento loaded) o representa (evento rendered). Para obtener más información, consulte Uso de la inserción por fases.

La aplicación puede responder cuando un usuario interactúa con un informe integrado de Power BI. Las siguientes acciones de usuario generan eventos a los que la aplicación puede suscribirse:

  • Selección de un botón de informe (evento buttonClicked)
  • Selección de una extensión de comando, que es un comando personalizado que la aplicación agrega al menú contextual (evento commandTriggered)
  • Selección de un hipervínculo (evento dataHyperlinkClicked)
  • Selección de un punto de datos, como una columna de un objeto visual de gráfico de columnas (evento dataSelected)
  • Selección de un objeto visual del informe (evento visualClicked)
  • Cambio de una página del informe (evento pageChanged)

Considere la posibilidad de mejorar la aplicación. En Tailspin Toys, su aplicación de ventas puede escribir notas de interés de los clientes en la base de datos de la aplicación. Cuando un usuario selecciona un botón de informe, la aplicación abre una ventana de cuadro de diálogo que le pide que escriba sus notas. La aplicación conserva los datos especificados y actualiza el informe para mostrar los nuevos datos representados en los objetos visuales del informe.

Las unidades posteriores de este módulo muestran cómo una aplicación responde a varios eventos.

Además, hay otros eventos disponibles para paneles, iconos de panel, la experiencia de preguntas y respuestas e informes insertados en la vista móvil. Para más información, consulte Procedimiento para controlar eventos.

Interacción con marcadores

Los marcadores permiten a los usuarios capturar el estado de una página del informe de Power BI, incluidos los filtros y el estado de visibilidad de los elementos del informe. Cuando se aplica, un marcador restaura el estado capturado en la página del informe. Puede reproducir una serie de marcadores, como una presentación, que puede ser útil para contar historias al realizar una exposición pública.

En la aplicación, puede controlar mediante programación las experiencias de marcador, donde puede hacer lo siguiente:

  • Administrar los marcadores aplicando, capturando o reproduciéndolos.
  • Aplicar un marcador o vuelver a la sesión de visualización actual.
  • Escribir o salir del modo de presentación de marcadores.
  • Mostrar o ocultar el panel Marcadores.
  • Recuperar una lista de marcadores.
  • Acceder a los marcadores y sus propiedades, quizás para presentarlos en una lista desplegable.

En la imagen siguiente se muestran las operaciones de marcador que puede explorar en el Área de juegos de análisis integrado de Power BI.

Imagen que muestra las operaciones de marcador que están disponibles en el área de juegos y que se alinean con las experiencias enumeradas anteriormente.

En Tailspin Toys, su aplicación de ventas permite a los usuarios capturar el estado actual de una página de informe integrado como marcador personal. Un marcador personal solo es visible para el usuario que lo creó, y permite a los usuarios volver a una vista específica de interés. La aplicación conserva los metadatos de marcador personales en la base de datos de la aplicación y presenta una lista desplegable de marcadores personales para que el usuario pueda volver a aplicarlos.

En una unidad posterior de este módulo se muestra cómo una aplicación puede usar marcadores.

Para más información, consulte Mejora de la experiencia de los usuarios con marcadores.

Generar diseños de informe dinámicos

Puede usar las API de diseño para permitir a los usuarios seleccionar qué objetos visuales y diseños quieren ver.

En la imagen siguiente se muestran las operaciones de diseño que puede explorar en el Área de juegos de análisis integrado de Power BI.

Imagen que muestra las operaciones de diseño, como Aplicar diseño personalizado, Comprobar diseño, Ocultar todos los encabezados visuales, Mostrar todos los encabezados visuales y Ocultar un solo encabezado visual.

En Tailspin Toys, la aplicación de ventas permite a los usuarios definir el tamaño de página, la escala del lienzo y el diseño de las páginas. Dentro del diseño de páginas, los usuarios de la aplicación pueden especificar un diseño visual para cada objeto visual. También pueden mostrar o cambiar el tamaño de los objetos visuales de interés y ocultar otros.

En una unidad posterior de este módulo se muestra cómo una aplicación puede personalizar el diseño del informe.

Para más información, consulte Personalizar un diseño de informe.

Creación de objetos visuales del informe personalizados

La API de cliente para Power BI incluye el paquete powerbi-report-authoring. Este paquete es una extensión de la biblioteca powerbi-client para crear y personalizar objetos visuales mediante programación, y para escribir un informe de Power BI después de cargarlo. También permite que la aplicación edite los informes integrados de Power BI.

Use la función addPage para agregar una página de creación y la función createVisual para agregar un nuevo objeto visual con un diseño predeterminado a la página de creación.

En la imagen siguiente se muestran las operaciones de creación que puede explorar en el Área de juegos de análisis integrado de Power BI.

Imagen que muestra las operaciones de creación, como Crear una página de creación, Crear un objeto visual, etc.

En Tailspin Toys, la aplicación de ventas proporciona una experiencia guiada que permite a los usuarios configurar y personalizar nuevos objetos visuales.

En una unidad posterior de este módulo se muestra cómo una aplicación puede permitir a los usuarios crear objetos visuales personalizados.

Para más información, consulte Información general sobre la creación de informes.

Impulsar un flujo de trabajo de análisis en contexto

La aplicación inserta contenido de Power BI en el elemento div y hospeda el contenido dentro de un elemento iframe. El elemento iframe crea una separación entre la aplicación y el contenido integrado, y garantiza que los datos sean más seguros. Las API de cliente siempre se comunican entre la aplicación y el contenido integrado. Dado que la comunicación es bidireccional, la aplicación puede impulsar un flujo de trabajo de análisis en contexto:

  1. El usuario navega dentro de la aplicación.
  2. La aplicación muestra un informe de Power BI que se filtra por una vista específica.
  3. El usuario filtra de forma interactiva los datos del informe.
  4. El usuario selecciona un botón para realizar una acción.
  5. La aplicación responde mediante la ejecución de código.

Imagen que muestra el flujo de trabajo de análisis en contexto como se describe en los pasos anteriores.