Introductie - Training | Microsoft Learn

12 minuten

U kunt Microsoft Power BI-client-API's gebruiken om Power BI-inhoud in te sluiten met behulp van JavaScript of TypeScript. Het is een clientbibliotheek die programmatisch beheer biedt over de volledige insluitingservaring.

Notitie

Zie de module Power BI-inhoud insluiten voor meer informatie over de basisbeginselen van Power BI-client-API's en hoe deze worden gebruikt om Power BI-inhoud in te sluiten.

Naast het insluiten van Power BI-inhoud, bieden de client-API's uw app het volgende:

Bewerkingen toepassen op inhoud, zoals het toevoegen van een rapportfilter.
Werk met gebeurtenissen zodat uw app kan reageren op gebruikersacties die in een rapport worden uitgevoerd, zoals een knopselectie.
Gebruik bladwijzers door ze toe te passen of nieuwe bladwijzers te maken.
Maak dynamische rapportindelingen, die controle bieden, zodat gebruikers de rapportervaring kunnen aanpassen.
Persoonlijke rapportvisuals maken.
Een werkstroom voor in-contextanalyse aandrijven.

Bewerkingen toepassen

Uw app kan veel bewerkingen toepassen op ingesloten inhoud. Deze bewerkingen omvatten algemene bewerkingen, zoals het opnieuw laden of vernieuwen van een rapport. Ze bevatten ook de mogelijkheid om de modus Volledig scherm in of af te sluiten, of u kunt de instellingen die de app in het configuratieobject heeft toegepast, opnieuw toepassen bij het insluiten van de inhoud.

Naast algemene bewerkingen zijn ook paginanavigatiebewerkingen beschikbaar. Daarnaast hebt u toegang tot filter- en slicerbewerkingen, waarmee uw app de filter-/slicerstatus kan bepalen of instellen. Andere nuttige bewerkingen zijn gegevensbewerkingen waarmee u visuele gegevens kunt exporteren en menubewerkingen waarmee menu's worden uitgebreid met nieuwe aangepaste opdrachten.

U kunt een aantal van deze bewerkingen ervaren door naar de Power BI Embedded Analytics Playground te gaan en de volgende instructies te volgen.

Notitie

De Power BI Embedded Analytics Playground is een website waarmee u ingesloten power BI-analyses kunt leren, verkennen en ermee kunt experimenteren. Het bevat een sandbox voor ontwikkelaars voor praktische ervaringen die gebruikmaken van de client-API's met power BI-voorbeeldinhoud of uw eigen inhoud. Codefragmenten en showcases zijn ook beschikbaar om te verkennen.

Zie Wat is de ingesloten analysespeelplaats van Power BI? voor meer informatie.

Selecteer ontwikkelaars-sandbox in het linkerdeelvenster.

Afbeelding van het linkerdeelvenster met de optie Sandbox voor ontwikkelaars gemarkeerd.

Wanneer u hierom wordt gevraagd, selecteert u de knop Voorbeeld gebruiken om te beginnen met een voorbeeldrapport.

Afbeelding met de knop Voorbeeld gebruiken gemarkeerd in het dialoogvenster Een voorbeeldrapport gebruiken.

Tip

U kunt ook uw eigen rapport selecteren dat afkomstig is van de Power BI-service, of u kunt een insluittoken gebruiken dat door uw ontwikkel-app wordt gegenereerd. In deze activiteit blijft u het voorbeeldrapport gebruiken.

De speeltuin sluit een voorbeeldrapport in en boven het rapport bevindt zich het codevenster met de code die nodig is om het rapport in te sluiten, te laden en weer te geven.

Vouw in het deelvenster Ingesloten rapport-API's de groep Algemene bewerkingen uit .

Als u de code wilt bijwerken, sleept u vanuit het deelvenster Ingesloten rapport-API's de bewerking Volledig scherm en zet u deze neer op de laatste regel (regel 94) in het codevenster.

Controleer het codefragment dat is toegevoegd aan het codevenster. Als u de code wilt uitvoeren, selecteert u uitvoeren in de menubalk boven het codevenster.

Afbeelding van de menubalk met de menuoptie Uitvoeren gemarkeerd.

Het rapport wordt weergegeven in de modus Volledig scherm. Druk op Esc om de modus Volledig scherm af te sluiten.

Nu gaan we de datumslicer van het rapport programmatisch wijzigen. Vouw in het deelvenster Ingesloten rapport-API's de groep Filters & slicers uit.

Sleep de bewerking Slicerstatus instellen naar het codevenster en plaats deze onder de laatste coderegel. Controleer vervolgens de 43 regels code die u aan het codevenster hebt toegevoegd. Voer de code uit en u ziet dat het rapport nog steeds in de modus Volledig scherm wordt geopend. Het datumbereik van de datumslicer moet worden ingesteld op 12 oktober 2014 - 27 november 2014.

Afbeelding van de datumslicers en het nieuwe datumbereik.

Druk op Esc om de modus Volledig scherm af te sluiten.

Tip

De speeltuin biedt een moeiteloze manier om bewerkingen te ontdekken en te evalueren zonder dat u een app hoeft te ontwikkelen. Vergeet niet dat u deze bewerkingen kunt verkennen met behulp van het voorbeeldrapport of uw eigen rapport.

Werken met beschrijfbare gebeurtenissen

Gebeurtenissen communiceren tussen ingesloten Power BI-inhoud en uw app. Een app kan gebeurtenissen genereren als reactie op geautomatiseerde acties (de weergave van een rapport) of gebruikersacties (een knopselectie).

Het betekent ook dat uw app op een zinvolle manier kan reageren wanneer het rapport wordt geladen (waardoor de loaded gebeurtenis wordt gegenereerd) of wordt weergegeven (rendered gebeurtenis). Zie Gefaseerd insluiten gebruiken voor meer informatie.

Uw app kan reageren wanneer een gebruiker communiceert met een ingesloten Power BI-rapport. De volgende gebruikersacties genereren gebeurtenissen waarop uw app zich kan abonneren:

Selectie van een rapportknop (buttonClicked gebeurtenis)
Selectie van een opdrachtextensie, een aangepaste opdracht die uw app toevoegt aan het contextmenu (commandTriggered gebeurtenis)
Selectie van een hyperlink (dataHyperlinkClicked gebeurtenis)
Selectie van een gegevenspunt, zoals een kolom van een kolomdiagramvisual (dataSelected gebeurtenis)
Selectie van een rapportvisual (visualClicked gebeurtenis)
Wijziging van rapportpagina (pageChanged gebeurtenis)

Overweeg de mogelijkheden om uw app te verbeteren. Bij Tailspin Toys kan hun verkoop-app klantnotities terugschrijven naar de app-database. Wanneer een gebruiker een rapportknop selecteert, wordt in de app een dialoogvenster geopend waarin de gebruiker wordt gevraagd zijn of haar notities in te voeren. De app bewaart de ingevoerde gegevens en vernieuwt vervolgens het rapport om de nieuwe gegevens weer te geven die worden weergegeven in de rapportvisuals.

Latere eenheden van deze module laten zien hoe een app reageert op verschillende gebeurtenissen.

Bovendien zijn er andere gebeurtenissen beschikbaar voor dashboards, dashboardtegels, de Q&A-ervaring en rapporten die zijn ingesloten in de mobiele weergave. Zie Gebeurtenissen verwerken voor meer informatie.

Werken met bladwijzers

Met bladwijzers kunnen gebruikers de status van een Power BI-rapportpagina vastleggen, inclusief filters en de zichtbaarheidsstatus van rapportelementen. Wanneer een bladwijzer wordt toegepast, wordt de vastgelegde status hersteld naar de rapportpagina. U kunt een reeks bladwijzers afspelen , zoals een diavoorstelling, wat een handig apparaat voor verhalen kan zijn wanneer u presenteert aan een publiek.

In uw app kunt u het maken van bladwijzers programmatisch beheren, waarbij u het volgende kunt doen:

Bladwijzers beheren door ze toe te passen, vast te leggen of af te spelen.
Pas een bladwijzer toe of ga terug naar de huidige weergavesessie.
De diavoorstellingsmodus bladwijzers in- of afsluiten.
Het deelvenster Bladwijzers weergeven of verbergen.
Een lijst met bladwijzers ophalen.
Open bladwijzers en hun eigenschappen, bijvoorbeeld om ze in een vervolgkeuzelijst weer te geven.

In de volgende afbeelding ziet u de bladwijzerbewerkingen die u kunt verkennen in de Power BI Embedded Analytics Playground.

Afbeelding van de bladwijzerbewerkingen die beschikbaar zijn in de speeltuin en die zijn afgestemd op de eerder vermelde ervaringen.

Bij Tailspin Toys kunnen gebruikers met hun verkoop-app de huidige status van een ingesloten rapportpagina vastleggen als een persoonlijke bladwijzer. Een persoonlijke bladwijzer is alleen zichtbaar voor de gebruiker die deze heeft gemaakt en stelt gebruikers in staat om terug te keren naar een specifieke weergave. De app bewaart metagegevens van persoonlijke bladwijzers in de app-database en toont een vervolgkeuzelijst met persoonlijke bladwijzers, zodat de gebruiker deze opnieuw kan toepassen.

Een latere eenheid van deze module laat zien hoe een app bladwijzers kan gebruiken.

Zie De gebruikerservaring verbeteren met bladwijzers voor meer informatie.

Dynamische rapportindelingen maken

U kunt de indelings-API's gebruiken om gebruikers te laten selecteren welke visuals en indelingen ze willen weergeven.

In de volgende afbeelding ziet u de indelingsbewerkingen die u kunt verkennen in de Power BI Embedded Analytics Playground.

Afbeelding met de indelingsbewerkingen, waaronder Aangepaste indeling toepassen, Indeling controleren, Alle visuele kopteksten verbergen, Alle visuele kopteksten weergeven en Enkele visuele kop verbergen.

Bij Tailspin Toys kunnen gebruikers met de verkoop-app het paginaformaat, de canvasschaal en de pagina-indeling definiëren. Binnen de pagina-indeling kunnen app-gebruikers een visuele indeling voor elke visual opgeven. Hiermee kunnen ze ook belangrijke visuals weergeven of het formaat ervan wijzigen en andere visuals verbergen.

Een latere eenheid van deze module laat zien hoe een app de rapportindeling aan uw persoonlijke voorkeur kan aanpassen.

Zie Een rapportindeling aanpassen voor meer informatie.

Persoonlijke rapportvisuals maken

De Power BI-client-API bevat het ontwerppakket powerbi-report . Dit pakket is een uitbreiding van de powerbi-clientbibliotheek voor het programmatisch maken en personaliseren van visuals en voor het schrijven van een Power BI-rapport nadat het is geladen. Hiermee kan uw app ook ingesloten Power BI-rapporten bewerken.

Gebruik de addPage functie om een ontwerppagina toe te voegen en gebruik de createVisual functie om een nieuwe visual met een standaardindeling toe te voegen aan de ontwerppagina.

In de volgende afbeelding ziet u de ontwerpbewerkingen die u kunt verkennen in de Power BI Embedded Analytics Playground.

Afbeelding van de bewerkingen voor ontwerpen, waaronder Een ontwerppagina maken, Een visual maken en andere.

Bij Tailspin Toys biedt de verkoop-app een begeleide ervaring waarmee gebruikers nieuwe visuals kunnen instellen en personaliseren.

Een latere eenheid van deze module laat zien hoe gebruikers met een app persoonlijke visuals kunnen maken.

Zie Overzicht van het ontwerpen van rapporten voor meer informatie.

Een werkstroom voor in-contextanalyse aandrijven

De app sluit Power BI-inhoud in het div -element in, waarbij de inhoud binnen een iframe element wordt gehost. Het iframe element maakt een scheiding tussen de app en de ingesloten inhoud, waardoor de gegevens veiliger zijn. De client-API's communiceren altijd tussen de app en de ingesloten inhoud. Omdat communicatie bidirectioneel is, kan uw app een in-contextanalysewerkstroom aandrijven:

De gebruiker navigeert in de app.
In de app wordt een Power BI-rapport weergegeven dat is gefilterd op een specifieke weergave.
De gebruiker filtert interactief gegevens in het rapport.
De gebruiker selecteert een knop om een actie uit te voeren.
De app reageert door code uit te voeren.

Doorgaan

Inleiding