Automatisierte Konfiguration der Installation einer Vorlagen-App

  • Artikel

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 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.

Illustration of user experience with an auto-installation application.

In diesem Artikel werden der grundlegende Ablauf, die Voraussetzungen und die wichtigsten Schritte und APIs erläutert, die Sie für die Automatisierung der Konfiguration der Installation einer Vorlagen-App benötigen. Wenn Sie direkt loslegen möchten, können Sie mit dem Tutorial fortfahren, in dem Sie die Konfiguration der Installation für die Vorlagen-App mithilfe einer einfachen Beispielanwendung automatisieren, die eine Azure-Funktion verwendet.

Grundlegender Ablauf

Der grundlegende Ablauf der Automatisierung der Installationskonfiguration einer Vorlagen-App lautet wie folgt:

  1. Der Benutzer meldet sich beim ISV-Portal an und klickt auf den bereitgestellten Link. Durch diese Aktion wird der automatisierte 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

Die folgenden Voraussetzungen müssen erfüllt sein, um eine vorkonfigurierte Installationsoption für Ihre Vorlagen-App bereitstellen zu können:

  • 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.

  • 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. Weitere Informationen finden Sie unter Einbetten von Power BI-Inhalten mit 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. Bei diesem Vorgang müssen Sie die Anwendungs-ID (Client-ID) und das Anwendungsgeheimnis (Clientgeheimnis) für spätere Schritte speichern.

  • 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. Für die nächsten Schritte müssen Sie sich die folgenden Informationen in der Vorlagen-App notieren:

    • AppId, PackageKey und OwnerId: Diese werden in der Installations-URL am Ende des Schritts zum 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. Parameternamen sind Zeichenfolgen, bei denen die Groß- und Kleinschreibung beachtet wird. Sie können, wenn Sie aus der Registerkarte Parametereinstellungen abgerufen werden, wenn Sie die Eigenschaften der Vorlagen-App definieren, oder aus den Einstellungen des semantischen Modells in Power BI.

  • Um den Automatisierungsworkflow testen zu können, fügen Sie den Dienstprinzipal als Administrator dem Vorlagen-App-Arbeitsbereich hinzu.

    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.

Wichtige Schritte und APIs

Die wichtigsten Schritte zum Automatisieren der Konfiguration der Installation einer Vorlagen-App und der erforderlichen APIs werden in den folgenden Abschnitten beschrieben. Während die meisten Schritte mit den Power BI-REST-APIs ausgeführt werden, wird für die hier beschriebenen Codebeispiele das .NET SDK verwendet.

Schritt 1: Erstellen eines Power BI-Clientobjekts

Wenn Sie Power BI-REST-APIs verwenden, müssen Sie ein Zugriffstoken für Ihren Dienstprinzipal aus Microsoft Entra ID abrufen. Sie benötigen ein Microsoft Entra-Zugriffstoken für Ihre Power BI-Anwendung, bevor Sie Aufrufe an die Power BI-REST-APIs durchführen können. Sie müssen ein Power BI-Clientobjekt erstellen, durch das Sie mit den Power BI-REST-APIs interagieren können, um den Power BI-Client mit Ihrem Zugriffstoken zu erstellen. Sie erstellen das Power BI-Clientobjekt durch Einschließen des Zugriffstokens in ein Microsoft.Rest.TokenCredentials-Objekt.

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI client object. It's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code goes here.
}

Schritt 2: Erstellen eines Installationstickets

Erstellen Sie ein Installationsticket, das verwendet wird, wenn Sie Benutzer zu Power BI umleiten. Die für diesen Vorgang verwendete API ist die CreateInstallTicket-API.

Ein Beispiel zum Erstellen eines Installationstickets für die Installation und Konfiguration einer Vorlagen-App finden Sie in der Datei InstallTemplateApp/InstallAppFunction.cs in der Beispielanwendung.

Im folgenden Codebeispiel wird gezeigt, wie Sie die CreateInstallTicket-REST-API für die Vorlagen-App verwenden.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
    InstallDetails = new List<TemplateAppInstallDetails>()
    {
        new TemplateAppInstallDetails()
        {
            AppId = Guid.Parse(AppId),
            PackageKey = PackageKey,
            OwnerTenantId = Guid.Parse(OwnerId),
            Config = new TemplateAppConfigurationRequest()
            {
                Configuration = Parameters
                                    .GroupBy(p => p.Name)
                                    .ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
            }
        }
    }
};

// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);

Schritt 3: Umleiten von Benutzern an Power BI mit dem Ticket

Nachdem Sie ein Installationsticket erstellt haben, verwenden Sie es, um Benutzer zu Power BI umzuleiten und die Installation und Konfiguration der Vorlagen-App fortzusetzen. Sie verwenden eine POST-Umleitungsmethode zur Installations-URL der Vorlagen-App mit dem Installationsticket im Anforderungstext.

Es gibt verschiedene dokumentierte Methoden, eine Umleitung mithilfe von POST-Anforderungen auszugeben. Die Auswahl hängt vom Szenario und der Interaktion Ihrer Benutzer mit Ihrem Portal oder Dienst ab.

In einem einfachen Beispiel, das hauptsächlich für Testzwecke verwendet wird, wird ein Formular mit einem ausgeblendeten Feld genutzt, das beim Laden automatisch übermittelt wird.

<html>
    <body onload='document.forms["form"].submit()'>
        <!-- form method is POST and action is the app install URL -->
        <form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
            <!-- value should be the new install ticket -->
            <input type='hidden' name='ticket' value='H4sI....AAA='>
        </form>
    </body>
</html>

Im folgenden Beispiel für die Antwort der Beispielanwendung ist das Installationsticket enthalten, und Benutzer werden automatisch zu Power BI umgeleitet. Die Antwort für diese Azure-Funktion ist dasselbe automatisch gesendete Formular, das im vorherigen HTML-Beispiel angezeigt wird.

...
    return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}

...

public static string RedirectWithData(string url, string ticket)
{
    StringBuilder s = new StringBuilder();
    s.Append("<html>");
    s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
    s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
    s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
    s.Append("</form></body></html>");
    return s.ToString();
}

Hinweis

Es gibt verschiedene Methoden, POST-Browserumleitungen zu verwenden. Sie sollten immer die sicherste Methode verwenden, die von den Dienstanforderungen und -einschränkungen abhängig ist. Denken Sie daran, dass einige Varianten für unsichere Umleitungen dazu führen können, dass Ihre Benutzer oder Dienste Sicherheitsrisiken ausgesetzt werden.

Schritt 4: Verlagern der Automatisierung in die Produktion

Wenn Sie die von Ihnen entworfene Automatisierung fertiggestellt haben, sollten Sie sicherstellen, dass Sie diese in die Produktion verschieben.

Zugehöriger Inhalt