Tutorial: Automatisieren der Konfiguration der Installation von Vorlagen-Apps mithilfe einer Azure-Funktion

Vorlagen-Apps bieten Kunden eine hervorragende Möglichkeit, Erkenntnisse aus ihren Daten zu gewinnen. Vorlagen-Apps ermöglichen eine schnelle Einrichtung und Ausführung, indem eine Verbindung mit ihren Daten hergestellt wird. Die Vorlagen-Apps bieten Kunden vorgefertigte Berichte, die nach Bedarf angepasst werden können.

Kunden sind nicht immer mit den Details zum Herstellen einer Verbindung mit ihren Daten vertraut. Wenn sie diese Details beim Installieren einer Vorlagen-App angeben müssen, kann dies ein Problem sein.

Wenn Sie ein Datendienstanbieter sind und eine Vorlagen-App erstellt haben, um Kunden den Einstieg in die Verwendung Ihres Diensts mit ihren Daten zu vereinfachen, können Sie die Installation Ihrer Vorlagen-App vereinfachen. Sie können die Konfiguration der Parameter Ihrer Vorlagen-App automatisieren.

Wenn sich der Kunde bei Ihrem Portal anmeldet, klickt er auf einen speziellen Link, den Sie vorbereitet haben. Dieser Link bewirkt Folgendes:

• Hiermit wird die Automatisierung gestartet, die die benötigten Informationen sammelt.
• Die Parameter der Vorlagen-App werden vorkonfiguriert.
• Der Kunde wird zu seinem Power BI-Konto umgeleitet, wo er die App installieren kann.

Die Benutzer müssen lediglich auf Installieren klicken und sich bei der Datenquelle authentifizieren.

Die Funktion wird im Folgenden dargestellt.

In diesem Tutorial verwenden Sie ein Azure Functions-Beispiel für die automatisierte Installation, das für die Vorabkonfiguration und Installation Ihrer Vorlagen-App erstellt wurde. Dieses Beispiel wurde zu Demonstrationszwecken bewusst einfach gehalten. Es umfasst die Einrichtung einer Azure-Funktion für die Nutzung von Power BI-APIs zum Installieren einer Vorlagen-App und zum automatischen Konfigurieren dieser Vorlagen-App für Ihre Benutzer.

Weitere Informationen zum allgemeinen Automatisierungsflow und die von der App verwendeten APIs finden Sie unter Automatisierte Konfiguration der Installation einer Vorlagen-App.

Die einfache Beispielanwendung verwendet eine Azure-Funktion. Weitere Informationen zu Azure Functions finden Sie in der Dokumentation zu Azure Functions.

Grundlegender Ablauf

Der folgende grundlegende Flow beschreibt die Aktionen der Anwendung, wenn der Kunde diese startet, indem er auf den Link in Ihrem Portal klickt.

1. Der Benutzer meldet sich beim ISV-Portal an und klickt auf den bereitgestellten Link. Durch diese Aktion wird der Flow initiiert. Das ISV-Portal bereitet zu diesem Zeitpunkt die benutzerspezifische Konfiguration vor.

2. Der ISV ruft ein app-only-Token (Token nur für Anwendungen) ab, das auf einem Dienstprinzipal (Token nur für Anwendungen) basiert, der im ISV-Mandanten registriert ist.

3. Mit Power BI-REST-APIs erstellt der ISV ein Installationsticket, das die benutzerspezifische Parameterkonfiguration enthält, die vom ISV vorbereitet wurde.

4. Der ISV leitet den Benutzer mithilfe einer POST-Umleitungsmethode, die das Installationsticket umfasst, zu Power BI um.

5. Der Benutzer wird mit dem Installationsticket an sein Power BI-Konto umgeleitet und aufgefordert, die Vorlagen-App zu installieren. Wenn der Benutzer auf Installieren klickt, wird die Vorlagen-App installiert.

Hinweis

Obwohl Parameterwerte beim Erstellen des Installationstickets vom ISV konfiguriert werden, werden die datenquellenbezogenen Anmeldeinformationen nur vom Benutzer in den letzten Schritten der Installation bereitgestellt. Durch diese Regelung wird verhindert, dass sie für einen Drittanbieter verfügbar gemacht werden. So wird sichergestellt, dass eine sichere Verbindung zwischen dem Benutzer und den Datenquellen der Vorlagen-App besteht.

Voraussetzungen

• Ihr eigenes Microsoft Entra-Mandanten-Setup. Anweisungen zum Einrichten eines solchen Mandanten finden Sie unter Erstellen eines Microsoft Entra-Mandanten.
• Sie benötigen einen Dienstprinzipal (Token nur für Anwendungen), der im zuvor genannten Mandanten registriert ist.
• Sie benötigen eine parametrisierte Vorlagen-App, die zur Installation bereitsteht. Die Vorlagen-App muss in dem gleichen Mandanten erstellt werden, in dem Sie Ihre Anwendung in Microsoft Entra ID registrieren. Weitere Informationen finden Sie unter Tipps zu Vorlagen-Apps und Erstellen einer Vorlagen-App in Power BI.
• Um den Automatisierungsworkflow testen zu können, fügen Sie den Dienstprinzipal als Administrator dem Vorlagen-App-Arbeitsbereich hinzu.
• Sie verfügen über eine Power BI Pro-Lizenz. Falls Sie nicht für Power BI Pro registriert sind, registrieren Sie sich für eine kostenlose Testversion, bevor Sie beginnen.

Einrichten Ihrer Entwicklungsumgebung zum Automatisieren von Vorlagen-Apps

Bevor Sie mit der Einrichtung Ihrer Anwendung fortfahren, führen Sie die Anweisungen unter Schnellstart: Erstellen einer Azure Functions-App mit Azure App Configuration aus, um eine Azure-Funktion zusammen mit einer Azure-App-Konfiguration zu entwickeln. Erstellen Sie Ihre App-Konfiguration gemäß der Beschreibung im Artikel.

Registrieren einer Anwendung in Microsoft Entra ID

Erstellen Sie ein Dienstprinzipal nach den Anweisungen unter Einbetten von Power BI-Inhalten mit einem Dienstprinzipal und Anwendungsgeheimnis.

Stellen Sie sicher, dass Sie die Anwendung als serverseitige Webanwendung registrieren. Eine serverseitige Webanwendung wird registriert, wenn Sie ein Anwendungsgeheimnis erstellen möchten.

Speichern Sie die Anwendungs-ID (Client-ID) und das Anwendungsgeheimnis (Clientgeheimnis) für spätere Schritte.

Sie können das Einbettungssetuptool durchlaufen, um schnell mit der Erstellung einer App-Registrierung zu beginnen. Wenn Sie das Power BI-App-Registrierungstool verwenden, wählen Sie die Option Einbetten für Ihre Kunden aus.

Fügen Sie den Dienstprinzipal als Administrator dem Vorlagen-App-Arbeitsbereich hinzu, damit Sie den Automatisierungsworkflow testen können.

Vorbereiten der Vorlagen-App

Nachdem Sie Ihre Vorlagen-App erstellt haben und diese für die Installation bereit ist, speichern Sie die folgenden Informationen für die nächsten Schritte:

• AppId, PackageKey und OwnerId: Diese werden in der Installations-URL am Ende des Schritts Definieren der Eigenschaften der Vorlagen-App angezeigt, wenn die App erstellt wurde.

  Sie können auch denselben Link abrufen, indem Sie im Bereich Releaseverwaltung der Vorlagen-App auf Link abrufen klicken.

• Parameternamen: Diese werden im semantischen Modell der Vorlagen-App definiert. Bei Parameternamen wird die Groß- und Kleinschreibung beachtet. Sie können auch von der Registerkarte Parametereinstellungen, wenn Sie die Eigenschaften der Vorlagen-App definieren, oder aus den Einstellungen des semantischen Modells in Power BI abgerufen werden.

Hinweis

Sie können Ihre vorkonfigurierte Installationsanwendung in Ihrer Vorlagen-App testen, wenn die Vorlagen-App für die Installation bereit ist, auch wenn sie noch nicht in AppSource öffentlich verfügbar ist. Damit Benutzer außerhalb Ihres Mandanten die automatisierte Installationsanwendung zum Installieren der Vorlagen-App verwenden können, muss die Vorlagen-App im Marketplace für Power BI-Apps öffentlich verfügbar sein. Stellen Sie vor dem Veröffentlichen Ihrer Vorlagen-App mithilfe der von Ihnen erstellten automatisierten Installationsanwendung sicher, dass Sie die Vorlagen-App in Partner Center veröffentlichen.

Installieren und Konfigurieren der Vorlagen-App

In diesem Abschnitt verwenden Sie ein Azure Functions-Beispiel für die automatisierte Installation, das für die Vorabkonfiguration und Installation Ihrer Vorlagen-App erstellt wurde. Dieses Beispiel wurde zu Demonstrationszwecken bewusst einfach gehalten. Es ermöglicht Ihnen die Nutzung einer Azure-Funktion und von Azure App Configuration, um die API für die automatisierte Installation mühelos für Ihre Vorlagen-Apps bereitzustellen und zu verwenden.

Herunterladen von Visual Studio (Version 2017 oder höher)

Laden Sie Visual Studio (Version 2017 oder höher) herunter. Laden Sie das neueste NuGet-Paket herunter.

Herunterladen des Azure Functions-Beispiels für die automatisierte Installation

Laden Sie das Azure Functions-Beispiel für die automatisierte Installation von GitHub herunter.

Einrichten der Azure-App-Konfiguration

Sie müssen zum Ausführen dieses Beispiels Ihre Azure-App-Konfiguration mit den hier beschriebenen Werten und Schlüsseln einrichten. Bei den Schlüsseln handelt es sich um die Anwendungs-ID, das Anwendungsgeheimnis und die Werte AppId, PackageKey und OwnerId Ihrer Vorlagen-App. In den folgenden Abschnitten finden Sie Informationen dazu, wie Sie diese Werte abrufen.

Die Schlüssel werden auch in der Datei Constants.cs definiert.

Konfigurationsschlüssel	Bedeutung
TemplateAppInstall:Application:AppId	AppId aus der Installations-URL
TemplateAppInstall:Application:PackageKey	PackageKey aus der Installations-URL
TemplateAppInstall:Application:OwnerId	OwnerId aus der Installations-URL
TemplateAppInstall:ServicePrincipal:ClientId	Anwendungs-ID des Dienstprinzipals
TemplateAppInstall:ServicePrincipal:ClientSecret	Anwendungsgeheimnis des Dienstprinzipals

Die Constants.cs-Datei wird hier angezeigt.

Abrufen der Eigenschaften der Vorlagen-App

Geben Sie die relevanten Eigenschaften der Vorlagen-App ein, die beim Erstellen der App definiert werden. Bei diesen Eigenschaften handelt es sich um die Werte AppId, PackageKey und OwnerId der Vorlagen-App.

Führen Sie diese Schritte aus, um die zuvor genannten Werte abzurufen:

1. Melden Sie sich bei Power BI an.

2. Navigieren Sie zum ursprünglichen Arbeitsbereich der Anwendung.

3. Öffnen Sie den Bereich Releaseverwaltung.

   

4. Wählen Sie die App-Version aus, und rufen Sie den Installationslink ab.

   

5. Kopieren Sie den Link in die Zwischenablage.

   

6. Diese Installations-URL enthält die drei URL-Parameter, deren Werte Sie benötigen. Verwenden Sie die Werte AppId, PackageKey und OwnerId für die Anwendung. Hier sehen Sie eine Beispiel-URL.

   https://app.powerbi.com/Redirect?action=InstallApp&appId=3c386...16bf71c67&packageKey=b2df4b...dLpHIUnum2pr6k&ownerId=72f9...1db47&buildVersion=5
   

Abrufen der Anwendungs-ID

Geben Sie für applicationId die Anwendungs-ID aus Azure ein. Die Anwendung identifiziert sich mithilfe des applicationId-Werts bei den Benutzern, von denen Sie Berechtigungen anfordern.

Führen Sie die folgenden Schritte aus, um die Anwendungs-ID abzurufen:

1. Melden Sie sich beim Azure-Portal an.

2. Klicken Sie im Bereich auf der linken Seite auf Alle Dienste>App-Registrierungen.

   

3. Wählen Sie die Anwendung aus, für die die Anwendungs-ID benötigt wird.

   

4. Es gibt eine Anwendungs-ID, die als GUID aufgeführt ist. Verwenden Sie diese Anwendungs-ID als applicationId-Wert für die Anwendung.

   

Abrufen des Anwendungsgeheimnisses

Geben Sie für ApplicationSecret die Informationen aus dem Abschnitt Schlüssel Ihres Abschnitts für App-Registrierungen in Azure ein. Dieses Attribut funktioniert, wenn Sie den Dienstprinzipal verwenden.

Führen Sie die folgenden Schritte aus, um das Anwendungsgeheimnis abzurufen:

1. Melden Sie sich beim Azure-Portal an.

2. Klicken Sie im Bereich auf der linken Seite auf Alle Dienste>App-Registrierungen.

   

3. Wählen Sie die Anwendung aus, die das Anwendungsgeheimnis verwenden muss.

   

4. Wählen Sie Certificates and secrets (Zertifikate und Geheimnisse) unter Verwalten aus.

5. Wählen Sie New client secrets (Neue geheime Clientschlüssel) aus.

6. Geben Sie in das Feld Beschreibung einen Namen ein, und wählen Sie eine Dauer aus. Klicken Sie anschließend auf Speichern, um den Wert für Ihre Anwendung abzurufen. Wenn Sie den Bereich Schlüssel nach dem Speichern des Schlüsselwerts schließen, wird das Feld Wert nur als ausgeblendet angezeigt. An diesem Punkt können Sie den Schlüsselwert nicht abrufen. Wenn Sie den Schlüsselwert verlieren, müssen Sie im Azure-Portal einen neuen erstellen.

   

Lokales Testen der Funktion

Führen Sie die unter Lokales Ausführen der Funktion beschriebenen Schritte aus, um Ihre Funktion auszuführen.

Konfigurieren Sie Ihr Portal zum Ausgeben einer POST-Anforderung an die URL der Funktion. z. B. POST http://localhost:7071/api/install. Der Anforderungstext muss ein JSON-Objekt sein, das Schlüssel-Wert-Paare beschreibt. Schlüssel sind Parameternamen (wie in Power BI Desktop definiert). Werte sind die gewünschten Werte, die für jeden Parameter in der Vorlagen-App festgelegt werden sollen.

Hinweis

In der Produktionsumgebung werden Parameterwerte für jeden Benutzer von der Logik Ihres Portals abgeleitet.

Der gewünschte Flow sollte wie folgt lauten:

1. Das Portal bereitet die Anforderung für jeden Benutzer bzw. jede Sitzung vor.
2. Die Anforderung POST /api/install wird an Ihre Azure-Funktion ausgegeben. Der Anforderungstext besteht aus Schlüssel-Wert-Paaren. Der Schlüssel ist der Parametername. Der Wert ist der gewünschte Wert, der festgelegt werden soll.
3. Wenn alle Konfigurationen ordnungsgemäß vorgenommen wurden, sollte der Browser automatisch zum Power BI-Konto des Kunden weiterleiten und den automatisierten Installationsflow anzeigen.
4. Bei der Installation werden die Parameterwerte gemäß der Konfiguration in den Schritten 1 und 2 festgelegt.

Zugehöriger Inhalt

Veröffentlichen Ihres Projekts in Azure

Befolgen Sie die Anweisungen in der Azure Functions-Dokumentation, um Ihr Projekt in Azure zu veröffentlichen. Anschließend können Sie die APIs für die automatisierte Installation der Vorlagen-App in Ihr Produkt integrieren und damit beginnen, sie in Produktionsumgebungen zu testen.