Systemintegration von Power BI-VisualsPower BI visuals system integration

In diesem Artikel wird beschrieben, wie Visuals in Power BI integriert werden und wie ein Benutzer mit einem Visual in Power BI interagieren kann.The article describes how visuals integrate with Power BI and how a user can interact with a visual in Power BI.

Die folgende Abbildung zeigt, wie gängige, auf Visuals basierende Aktionen, die von einem Benutzer ausgeführt werden – beispielsweise das Auswählen eines Lesezeichens –, in Power BI verarbeitet werden.The following figure depicts how common visual-based actions that a user takes, like selecting a bookmark, are processed in Power BI.

Diagramm: Aktionen mit Power BI-Visuals

Visuals erhalten Aktualisierungen von Power BIVisuals get updates from Power BI

Ein Visual ruft eine update-Methode auf, um Aktualisierungen von Power BI zu erhalten.A visual calls an update method to get updates from Power BI. Die update-Methode enthält normalerweise die Hauptlogik des Visuals und ist für das Rendern eines Diagramms bzw. Visualisieren von Daten zuständig.The update method usually contains the main logic of the visual and is responsible for rendering a chart or visualizing data.

Updates werden ausgelöst, wenn das Visual die update-Methode aufruft.Updates are triggered when the visual calls the update method.

Aktions- und AktualisierungsmusterAction and update patterns

Aktionen und anschließende Aktualisierungen in Power BI-Visuals erfolgen nach einem der folgenden drei Muster:Actions and subsequent updates in Power BI visuals occur in one of these three patterns:

  • Der Benutzer interagiert über Power BI mit einem Visual.User interacts with a visual through Power BI.
  • Der Benutzer interagiert direkt mit dem Visual.User interacts with the visual directly.
  • Das Visual interagiert mit Power BI.Visual interacts with Power BI.

Der Benutzer interagiert über Power BI mit einem VisualUser interacts with a visual through Power BI

  • Ein Benutzer öffnet den Eigenschaftenbereich eines Visuals.A user opens the visual's properties panel.

    Wenn ein Benutzer den Eigenschaftenbereich eines Visuals öffnet, ruft Power BI unterstützte Objekte und Eigenschaften aus der Datei capabilities.json des Visuals ab.When a user opens the visual's properties panel, Power BI fetches supported objects and properties from the visual's capabilities.json file. Um die tatsächlichen Werte der Eigenschaften abzurufen, ruft Power BI die enumerateObjectInstances-Methode des Visuals auf.To receive actual values of properties, Power BI calls the enumerateObjectInstances method of the visual. Das Visual gibt die tatsächlichen Werte der Eigenschaften zurück.The visual returns actual values of properties.

    Weitere Informationen finden Sie unter Funktionen und Eigenschaften von Power BI-Visuals.For more information, see Capabilities and properties of Power BI visuals.

  • Ein Benutzer ändert eine Eigenschaft des Visuals im Bereich „Format“.A user changes a property of the visual in the format panel.

    Wenn ein Benutzer im Formatbereich den Wert einer Eigenschaft ändert, ruft Power BI die update-Methode des Visuals auf.When a user changes the value of a property in the format panel, Power BI calls the update method of the visual. Power BI übergibt das neue options-Objekt an die update-Methode.Power BI passes in the new options object to the update method. Das Objekt enthält die neuen Werte.The objects contain the new values.

    Weitere Informationen finden Sie unter Objekte und Eigenschaften von Power BI-Visuals.For more information, see Objects and properties of Power BI visuals.

  • Ein Benutzer ändert die Größe des Visuals.A user resizes the visual.

    Wenn ein Benutzer die Größe eines Visuals ändert, ruft Power BI die update-Methode mit dem neuen options-Objekt auf.When a user changes the size of a visual, Power BI calls the update method with the new options object. Das options-Objekt enthält geschachtelte viewport-Objekte mit der neuen Breite und Höhe des Visuals.The options objects have nested viewport objects that contain the new width and height of the visual.

  • Ein Benutzer wendet einen Filter auf Berichts-, Seiten- oder Visualebene an.A user applies a filter at the report, page, or visual level.

    Power BI filtert die Daten basierend auf den Filterbedingungen.Power BI filters data based on filter conditions. Power BI ruft die update-Methode des Visuals auf, um das Visual mit neuen Daten zu aktualisieren.Power BI calls the update method of the visual to update the visual with new data.

    Das Visual erhält eine neue Aktualisierung der options-Objekte, wenn eins der geschachtelten Objekte neue Daten enthält.The visual gets a new update of the options objects when there's new data in one of the nested objects. Der genaue Ablauf der Aktualisierung richtet sich nach der Konfiguration der Zuordnung für die Datenansicht des Visuals.How the update occurs depends on the data view mapping configuration of the visual.

    Weitere Informationen finden Sie unter Grundlegendes zur Zuordnung von Datenansichten in Power BI-Visuals.For more information, see Understand data view mapping in Power BI visuals.

  • Ein Benutzer wählt einen Datenpunkt in einem anderen Visual im Bericht aus.A user selects a data point in another visual in the report.

    Wenn ein Benutzer einen Datenpunkt in einem anderen Visual im Bericht auswählt, filtert oder hebt Power BI die ausgewählten Datenpunkte hervor und ruft die update-Methode des Datenpunkts auf.When a user selects a data point in another visual in the report, Power BI filters or highlights the selected data points and calls the visual's update method. Das Visual erhält neue gefilterte Daten oder dieselben Daten mit einem Array von Hervorhebungen.The visual gets new filtered data, or it gets the same data with an array of highlights.

    Weitere Informationen finden Sie unter Hervorheben von Datenpunkten in Power BI-Visuals.For more information, see Highlight data points in Power BI visuals.

  • Ein Benutzer wählt im Bereich „Lesezeichen“ des Berichts ein Lesezeichen aus.A user selects a bookmark in the bookmarks panel of the report.

    Wenn ein Benutzer im Lesezeichenbereich des Berichts ein Lesezeichen auswählt, kann eine von zwei Aktionen ausgeführt werden:When a user selects a bookmark in the report's bookmarks panel, one of two actions can occur:

    • Power BI ruft eine Funktion auf, die von der registerOnSelectionCallback-Methode übergeben und registriert wird.Power BI calls a function that's passed and registered by the registerOnSelectionCallback method. Die Rückruffunktion ruft Array mit Auswahloptionen für das entsprechende Lesezeichen auf.The callback function gets arrays of selections for the corresponding bookmark.

    • Power BI ruft die update-Methode mit einem entsprechenden filter-Objekt innerhalb des options-Objekts auf.Power BI calls the update method with a corresponding filter object inside the options object.

    In beiden Fällen muss das Visual seinen Zustand gemäß den empfangenen Auswahloptionen oder gemäß dem filter-Objekt ändern.In either case, the visual must change its state according to the received selections or filter object.

    Weitere Informationen zu Lesezeichen und Filtern finden Sie unter API für visuelle Filter für Power BI-Visuals.For more information about bookmarks and filters, see Visual Filters API in Power BI visuals.

Der Benutzer interagiert direkt mit dem VisualUser interacts with the visual directly

  • Ein Benutzer zeigt mit der Maus auf ein Datenelement.A user hovers the mouse over a data element.

    Ein Visual kann über die API für Power BI-QuickInfos weitere Informationen zu einem Datenpunkt anzeigen.A visual can display more information about a data point through the Power BI Tooltips API. Wenn ein Benutzer mit der Maus auf ein Visual zeigt, kann das Visual das Ereignis verarbeiten und Daten zum zugehörigen QuickInfo-Element anzeigen.When a user hovers the mouse over a visual element, the visual can handle the event and display data about the associated tooltip element. Das Visual kann entweder eine standardmäßige QuickInfo oder eine QuickInfo der Berichtsseite anzeigen.The visual can display either a standard tooltip or a report page tooltip.

    Weitere Informationen finden Sie unter QuickInfos in Power BI-Visuals.For more information, see Tooltips in Power BI visuals.

  • Ein Benutzer ändert die Eigenschaften eines Visuals.A user changes visual properties. (Beispiel: Ein Benutzer erweitert eine Struktur, und das Visual speichert den Zustand in den Visualeigenschaften.)(For example, a user expands a tree and the visual saves state in the visual properties.)

    Ein Visual kann mithilfe der Power BI-API Eigenschaftswerte speichern.A visual can save properties values through the Power BI API. Wenn ein Benutzer beispielsweise mit dem Visual interagiert, und das Visual Eigenschaftswerte speichern oder aktualisieren muss, kann es die presistProperties-Methode aufrufen.For example, when a user interacts with the visual and the visual needs to save or update properties values, the visual can call the presistProperties method.

  • Ein Benutzer wählt eine URL aus.A user selects a URL.

    Standardmäßig kann ein Visual URLs nicht direkt öffnen.By default, a visual can't open a URL directly. Stattdessen kann das Visual die launchUrl-Methode aufrufen und die URL als Parameter übergeben, um eine URL in einer neuen Registerkarte zu öffnen.Instead, to open a URL in a new tab, the visual can call the launchUrl method and pass the URL as a parameter.

    Weitere Informationen finden Sie unter Erstellen einer Start-URL.For more information, see Create a launch URL.

  • Ein Benutzer wendet über das Visual einen Filter an.A user applies a filter through the visual.

    Ein Visual kann die applyJsonFilter-Methode aufrufen und Bedingungen übergeben, um nach Daten in anderen Visuals zu filtern.A visual can call the applyJsonFilter method and pass conditions to filter for data in other visuals. Es stehen verschiedene Arten von Filtern zur Verfügung, beispielsweise einfache Filter, erweiterte Filter und Tupelfilter.Several types of filters are available, including Basic, Advanced, and Tuple filters.

    Weitere Informationen finden Sie unter API für visuelle Filter für Power BI-Visuals.For more information, see Visual Filters API in Power BI visuals.

  • Ein Benutzer wählt Elemente in einem Visual aus.A user selects elements in the visual.

    Weitere Informationen zu Auswahloptionen in einem Power BI-Visual finden Sie unter Power BI-Visuals interaktiv gestalten mithilfe von Auswahloptionen.For more information about selections in a Power BI visual, see Add interactivity by using Power BI visual selections.

Das Visual interagiert mit Power BIVisual interacts with Power BI

  • Ein Visual fordert mehr Daten von Power BI an.A visual requests more data from Power BI.

    Ein Visual verarbeitet Daten nacheinander.A visual processes data part by part. Die API-Methode fetchMoreData fordert das nächste Datenfragment im Dataset an.The fetchMoreData API method requests the next fragment of data in the dataset.

    Weitere Informationen finden Sie unter Abrufen größerer Datenmengen von Power BI.For more information, see Fetch more data from Power BI.

  • Der Ereignisdienst wird ausgelöst.The event service triggers.

    Power BI kann einen Bericht als PDF exportieren oder per E-Mail senden (gilt nur für zertifizierte Visuals).Power BI can export a report to PDF or send a report by e-mail (applies only to certified visuals). Um Power BI zu benachrichtigen, dass das Rendern abgeschlossen und das Visual zur Erfassung als PDF oder E-Mail bereit ist, muss das Visual die API zum Rendern von Ereignissen aufrufen.To notify Power BI that rendering is finished and that the visual is ready to be captured as PDF or e-mail, the visual should call the Rendering Events API.

    Weitere Informationen finden Sie unter Exportieren von Power BI-Berichten als PDF-Dateien.For more information, see Export reports from Power BI to PDF.

    Informationen zum Ereignisdienst finden Sie unter Rendern von Ereignissen in Power BI-Visuals.To learn about the event service, see Render events in Power BI visuals.

Nächste SchritteNext steps

Möchten Sie eigene Visualisierungen erstellen und zu Microsoft AppSource hinzufügen?Interested in creating visualizations and adding them to Microsoft AppSource? Informationen hierzu finden Sie in diesen Artikeln:See these articles: