Introduction

  • 12 minutes

Vous pouvez utiliser les API clientes Microsoft Power BI pour incorporer du contenu Power BI à l’aide de JavaScript ou de TypeScript. Il s’agit d’une bibliothèque de client qui fournit un contrôle programmatique de toute l’expérience d’incorporation.

Notes

Pour plus d’informations sur les principes de base des API clientes Power BI et pour savoir comment les utiliser pour incorporer du contenu Power BI, consultez le module Incorporer du contenu Power BI.

En plus de l’incorporation de contenu Power BI, les API clientes permettent à votre application de :

  • Appliquer des opérations au contenu, par exemple ajouter un filtre de rapport.
  • Utiliser des événements pour répondre aux actions utilisateur effectuées dans un rapport, par exemple la sélection d’un bouton.
  • Interagir avec les signets, en les appliquant ou en en créant de nouveaux.
  • Produire des dispositions de rapport dynamiques, qui fournissent aux utilisateurs un contrôle leur permettant de personnaliser l’expérience du rapport.
  • Créer des visuels de rapport personnalisés.
  • Diriger un workflow analytique en contexte.

Appliquer des opérations

Votre application peut appliquer de nombreuses opérations à du contenu incorporé. Il peut s’agir d’opérations générales, par exemple recharger ou actualiser un rapport. Est également concernée la possibilité d’activer et de quitter le mode plein écran, ou de réappliquer les paramètres mis en œuvre par l’application dans l’objet de configuration lors de l’incorporation initiale du contenu.

Des opérations de navigation de page sont également disponibles en plus des opérations générales. En outre, vous avez accès aux opérations de filtre et de segment, qui permettent à votre application de déterminer et de définir l’état du filtre ou du segment. Citons également, parmi les opérations utiles, les opérations de données qui offrent la possibilité d’exporter des données visuelles et les opérations de menu qui étendent les menus avec de nouvelles commandes personnalisées.

Vous pouvez tester certaines de ces opérations en accédant au Terrain de jeu Analytique incorporée Power BI et en suivant les instructions ci-dessous.

Notes

Le terrain de jeu Analytique incorporée Power BI est un site web qui vous permet d’apprendre, d’explorer et de tester l’analytique incorporée Power BI. Il comprend un bac à sable de développement pour les expériences pratiques qui utilisent les API clientes avec des exemples de contenu Power BI ou votre propre contenu. Des extraits de code et des démos sont également disponibles.

Pour plus d’informations, consultez Qu’est-ce que le terrain de jeu d’analytique incorporée Power BI ?

Dans le volet gauche, sélectionnez Bac à sable de développement.

Image montrant le volet de gauche avec l’option Bac à sable de Développeur mise en surbrillance.

Quand vous y êtes invité, sélectionnez le bouton Utiliser un exemple pour commencer à utiliser un exemple de rapport.

Image montrant le bouton Utiliser l’exemple mis en surbrillance dans la boîte de dialogue Utiliser un exemple de rapport.

Conseil

Vous pouvez également sélectionner votre propre rapport provenant du service Power BI ou utiliser un jeton intégré généré par votre application de développement. Dans cette activité, vous continuerez de vous servir de l’exemple de rapport.

Le terrain de jeu incorpore un exemple de rapport, et au-dessus du rapport se trouve le volet avec le code permettant d’incorporer, de charger et d’afficher le rapport.

Dans le volet API de rapport incorporé, développez le groupe Opérations générales.

Image montrant le groupe Opérations générales développé dans le volet API de rapport incorporé.

Pour mettre à jour le code, faites glisser l’opération Plein écran du volet API de rapport incorporé et déposez-la sur la dernière ligne (94) du volet de code.

Image montrant l’opération Plein écran avec une flèche indiquant où la déposer dans le volet de code.

Examinez le fragment de code ajouté au volet de code. Ensuite, sélectionnez Exécuter dans la barre de menus située au-dessus du volet de code pour exécuter le code.

Image montrant la barre de menus avec l’option Exécuter le menu mise en surbrillance.

Le rapport s’affiche en mode plein écran. Pour quitter le mode plein écran, appuyez sur la touche Échap.

Vous modifiez maintenant programmatiquement le segment de date du rapport. Dans le volet API de rapport incorporé, développez le groupe Filtres et segments.

Image montrant le groupe Filtres et segments développé dans le volet API de rapport incorporé.

Faites glisser l’opération Définir l’état du segment vers le volet de code, et déposez-la sous la dernière ligne de code. Examinez ensuite les 43 lignes de code que vous avez ajoutées au volet de code. Exécutez le code. Comme vous pouvez le constater, le rapport continue à s’ouvrir en mode plein écran. La plage de dates du segment Date est en principe définie sur 12 octobre 2014 - 27 novembre 2014.

Image montrant les segments Date et la nouvelle plage de dates.

Pour quitter le mode plein écran, appuyez sur la touche Échap.

Conseil

Le terrain de jeu est un moyen facile de découvrir des opérations et de les évaluer sans avoir à développer une application. N’oubliez pas que vous pouvez explorer ces opérations en utilisant l’exemple de rapport ou votre propre rapport.

Utiliser des événements avec abonnement

Les événements communiquent entre le contenu incorporé Power BI et votre application. Une application peut déclencher des événements en réponse à des actions automatiques (l’affichage d’un rapport) ou à des actions utilisateur (la sélection d’un bouton).

Cela signifie également que l’application peut répondre de manière significative quand le rapport se charge (ce qui déclenche l’événement loaded) ou s’affiche (ce qui déclenche l’événement rendered). Pour plus d’informations, consultez Utiliser l’incorporation par phases.

Votre application peut répondre quand un utilisateur interagit avec un rapport incorporé Power BI. Les actions utilisateur suivantes déclenchent des événements auxquels votre application peut s’abonner :

  • Sélection d’un bouton de rapport (événement buttonClicked)
  • Sélection d’une extension de commande, c’est-à-dire une commande personnalisée ajoutée au menu contextuel par votre application (événement commandTriggered)
  • Sélection d’un lien hypertexte (événement dataHyperlinkClicked)
  • Sélection d’un point de données, par exemple une colonne d’un visuel de type histogramme (événement dataSelected)
  • Sélection d’un visuel de type rapport (événement visualClicked)
  • Changement d’une page de rapport (événement pageChanged)

Voyez comment vous pouvez améliorer votre application. Chez Tailspin Toys, leur application de vente peut mettre à jour les remarques d’intérêt des clients dans la base de données d’application. Quand un utilisateur sélectionne un bouton de rapport, l’application ouvre une boîte de dialogue qui l’invite à entrer ses remarques. Elle conserve les données entrées, puis actualise le rapport pour afficher les nouvelles données représentées dans les visuels du rapport.

Les unités suivantes de ce module montrent comment une application répond à divers événements.

D’autres événements sont par ailleurs disponibles pour les tableaux de bord, les vignettes de tableau de bord, l’expérience Questions et réponses et les rapports incorporés dans la vue mobile. Pour plus d’informations, consultez Comment traiter les événements.

Interagir avec les signets

Les signets permettent aux utilisateurs de capturer l’état d’une page de rapport Power BI, y compris les filtres et l’état de visibilité des éléments de rapport. Quand un signet est appliqué, il restaure l’état capturé de la page de rapport. Vous avez la possibilité de lire une série de signets comme un diaporama, ce qui peut être utile pour faire une présentation devant un public.

Dans votre application, vous pouvez contrôler programmatiquement les expériences de signet :

  • Gérer les signets en les appliquant, les capturant ou les lisant.
  • Appliquer un signet ou revenir à la session de consultation actuelle.
  • Activer ou quitter le mode diaporama des signets.
  • Afficher ou masquer le volet Signets.
  • Récupérer une liste de signets.
  • Accéder aux signets et à leurs propriétés, peut-être pour les présenter dans une liste déroulante.

L’image suivante montre les opérations de signet que vous pouvez explorer dans le terrain de jeu Analytique incorporée Power BI.

Image montrant les opérations Signet disponibles dans le terrain de jeu, en correspondance avec la liste d’expériences précédente.

Chez Tailspin Toys, l’application de vente permet aux utilisateurs de capturer l’état actuel d’une page de rapport incorporé comme un signet personnel. Un signet personnel n’est visible que pour l’utilisateur qui l’a créé. Il lui permet de revenir à une vue spécifique qui l’intéresse. L’application conserve les métadonnées des signets personnels dans la base de données d’application. Elle présente la liste déroulante des signets personnels pour permettre à l’utilisateur de les réappliquer.

Une des unités suivantes de ce module montre comment une application peut utiliser des signets.

Pour plus d’informations, consultez Améliorer l’expérience de vos utilisateurs avec les signets.

Produire des dispositions de rapport dynamiques

Vous pouvez utiliser les API de disposition pour permettre aux utilisateurs de sélectionner les visuels et les dispositions qu’ils veulent afficher.

L’image suivante montre les opérations de disposition que vous pouvez explorer dans le terrain de jeu Analytique incorporée Power BI.

Image montrant les opérations Disposition, notamment Appliquer une disposition personnalisée, Vérifier la disposition, Masquer tous les en-têtes d’objets visuels, Afficher tous les en-têtes d’objets visuels et Masquer l’en-tête d’un seul objet visuel.

Chez Tailspin Toys, l’application de vente permet aux utilisateurs de définir la taille de page, l’échelle de canevas et la disposition des pages. Dans la disposition des pages, les utilisateurs de l’application peuvent spécifier une disposition pour chaque visuel. Ils ont également la possibilité d’afficher et redimensionner les visuels qui les intéressent et de masquer les autres.

Une des unités suivantes de ce module montre comment une application peut personnaliser la disposition du rapport.

Pour plus d’informations, consultez Personnaliser la disposition d’un rapport.

Créer des visuels de rapport personnalisés

L’API cliente Power BI comprend le package powerbi-report-authoring. Ce package est une extension de la bibliothèque powerbi-client qui permet de créer et personnaliser programmatiquement des visuels, et d’écrire un rapport Power BI après son chargement. Elle permet également à votre application de modifier les rapports Power BI incorporés.

Utilisez la fonction addPage pour ajouter une page de création, et la fonction createVisual pour ajouter un nouveau visuel qui possède une disposition par défaut sur la page de création.

L’image suivante montre les opérations de création que vous pouvez explorer dans le terrain de jeu Analytique incorporée Power BI.

Image montrant les opérations Création, notamment Créer une page de création et Créer un objet visuel.

Chez Tailspin Toys, l’application de vente offre une expérience guidée qui permet aux utilisateurs de configurer et de personnaliser de nouveaux visuels.

Une des unités suivantes de ce module montre comment une application peut permettre aux utilisateurs de créer des visuels personnalisés.

Pour plus d'informations, consultez Vue d’ensemble de la création de rapport.

Diriger un workflow analytique en contexte

L’application incorpore le contenu Power BI dans l’élément div, qui héberge le contenu dans un élément iframe. L’élément iframe crée une séparation entre l’application et le contenu incorporé, de façon à veiller à ce que les données soient plus sécurisées. Les API clientes communiquent toujours entre l’application et le contenu incorporé. Comme la communication est bidirectionnelle, votre application peut diriger un workflow analytique en contexte :

  1. L’utilisateur navigue dans l’application.
  2. L’application affiche un rapport Power BI filtré sur une vue spécifique.
  3. L’utilisateur filtre de manière interactive les données dans le rapport.
  4. L’utilisateur sélectionne un bouton pour effectuer une action.
  5. L’application répond en exécutant du code.

Image montrant le workflow analytique en contexte, décrit dans les étapes précédentes.