Automatisierte Konfiguration einer Vorlagen-App-Installation

Vorlagen-Apps sind eine hervorragende Möglichkeit für Kunden, Einblicke aus ihren Daten zu erhalten. Vorlagen-Apps ermöglichen es, sie schnell in Betrieb zu nehmen, indem sie mit ihren Daten verbunden werden. Die Vorlagen-Apps bieten ihnen vordefinierte Berichte, die sie bei Bedarf anpassen können.

Kunden sind nicht immer mit den Details der Verbindung zu ihren Daten vertraut. Das Erfordernis, diese Details anzugeben, wenn sie eine Vorlagen-App installieren, kann für sie ein Schmerzpunkt sein.

Wenn Sie ein Datendienstanbieter sind und eine Vorlagen-App erstellt haben, die Ihren Kunden bei den ersten Schritten mit ihren Daten in Ihrem Dienst hilft, 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, wählt er einen speziellen Link aus, den Sie vorbereitet haben. Dieser Link:

• Startet die Automatisierung, die die benötigten Informationen sammelt.
• Vorkonfiguriert die Vorlagen-App-Parameter.
• Leitet den Kunden an sein Power BI-Konto weiter, in dem er die App installieren kann.

Alles, was sie tun müssen, ist Installieren zu wählen und sich bei ihrer Datenquelle zu authentifizieren, und sie können loslegen!

Die Kundenerfahrung wird hier veranschaulicht.

In diesem Artikel werden der grundlegende Fluss, die Voraussetzungen, die wichtigsten Schritte und die APIs beschrieben, die Sie zum Automatisieren der Konfiguration einer Vorlagen-App-Installation benötigen. Wenn Sie sich eintauchen und loslegen möchten, können Sie mit dem Lernprogramm fortfahren, in dem Sie die Konfiguration der Vorlagen-App-Installation automatisieren, indem Sie eine einfache Beispielanwendung verwenden, die wir vorbereitet haben, die eine Azure-Funktion verwendet.

Grundlegender Ablauf für die automatisierte Konfiguration

Der grundlegende Fluss zum Automatisieren der Konfiguration einer Vorlagen-App-Installation wird wie folgt fortgesetzt:

1. Der Benutzer meldet sich beim Portal des ISV an und wählt den bereitgestellten Link aus. Diese Aktion initiiert den automatisierten Fluss. Das ISV-Portal bereitet die benutzerspezifische Konfiguration in dieser Phase vor.
2. Der ISV erwirbt ein Nur-App-Token basierend auf einem Dienstprinzipal (nur App-Token), das im Mandanten des ISV registriert ist.
3. Mithilfe von Power BI-REST-APIs erstellt der ISV ein Installationsticket, das die vom ISV vorbereitete benutzerspezifische Parameterkonfiguration enthält.
4. Der ISV leitet den Benutzer mithilfe einer POST Umleitungsmethode, die das Installationsticket enthält, an Power BI um.
5. Der Benutzer wird mit dem Installationsticket zu ihrem Power BI-Konto umgeleitet und zur Installation der Vorlagen-App aufgefordert. Wenn der Benutzer "Installieren" auswählt, wird die Vorlagen-App für sie installiert.

Voraussetzungen

Um eine vorkonfigurierte Installationsumgebung für Ihre Vorlagen-App bereitzustellen, sind die folgenden Voraussetzungen erforderlich:

• Eine Power BI Pro-Lizenz. Wenn Sie nicht für Power BI Pro registriert sind, registrieren Sie sich für eine kostenlose Testversion , bevor Sie beginnen.

• Ihr eigenes Microsoft Entra-Mandantensetup. Anweisungen zum Einrichten eines Mandanten finden Sie unter Erstellen eines Microsoft Entra-Mandanten.

• Ein Dienstprinzipal (nur App-Token), der im vorherigen Mandanten registriert ist. Weitere Informationen finden Sie unter Einbetten von Power BI-Inhalten mit Dienstprinzipal und einem geheimen Anwendungsschlüssel. Registrieren Sie die Anwendung unbedingt als serverseitige Webanwendungs-App . Sie registrieren eine serverseitige Webanwendung, um einen geheimen Anwendungsschlüssel zu erstellen. Aus diesem Prozess müssen Sie die Anwendungs-ID (ClientID) und den geheimen Anwendungsschlüssel (ClientSecret) für spätere Schritte speichern.

• Eine parametrisierte Vorlagen-App , die für die Installation bereit ist. Die Vorlagen-App muss im selben Mandanten erstellt werden, in dem Sie Ihre Anwendung in Microsoft Entra ID registrieren. Weitere Informationen finden Sie unter Vorlagen-App-Tipps oder Erstellen einer Vorlagen-App in Power BI. In der Vorlagen-App müssen Sie die folgenden Informationen für die nächsten Schritte beachten:

  • App-ID, Paketschlüssel und Besitzer-ID , wie sie am Ende des Prozesses der Definition der Eigenschaften der Vorlagen-App beim Erstellen der App in der Installations-URL angezeigt werden. Sie können auch denselben Link abrufen, indem Sie im Bereich "Versionsverwaltung" der Vorlagen-App "Link abrufen" auswählen.
  • Parameternamen, wie sie im Semantikmodell der Vorlagen-App definiert sind. Parameternamen sind Zeichenfolgen, die Groß- und Kleinschreibung berücksichtigen, und können auch über die Registerkarte "Parametereinstellungen" abgerufen werden, wenn Sie die Eigenschaften der Vorlage-App oder aus den Semantikmodelleinstellungen in Power BI definieren.

• Um Ihren Automatisierungsworkflow testen zu können, fügen Sie den Dienstprinzipal dem Vorlagen-App-Arbeitsbereich als Administrator 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 öffentlich auf AppSource verfügbar ist. Damit Benutzer außerhalb Ihres Mandanten die automatisierte Installationsanwendung verwenden können, um Ihre Vorlagen-App zu installieren, muss die Vorlagen-App in AppSource öffentlich verfügbar sein. Bevor Sie Ihre Vorlagen-App mithilfe der automatischen Installationsanwendung verteilen, die Sie erstellen, müssen Sie sie unbedingt im Partner Center veröffentlichen.

Hauptschritte und APIs

Die wichtigsten Schritte zum Automatisieren der Konfiguration einer Vorlagen-App-Installation und der apIs, die Sie benötigen, werden in den folgenden Abschnitten beschrieben. Während die meisten Schritte mit Power BI REST-APIs ausgeführt werden, werden die hier beschriebenen Codebeispiele mit dem .NET SDK erstellt.

Schritt 1: Erstellen eines Power BI-Clientobjekts

Die Verwendung von Power BI-REST-APIs erfordert, dass Sie ein Zugriffstoken für Ihren Dienstprinzipal von Microsoft Entra ID abrufen. Sie müssen ein Microsoft Entra-Zugriffstoken für Ihre Power BI-Anwendung abrufen, bevor Sie Aufrufe an die Power BI-REST-APIs ausführen. Um den Power BI-Client mit Ihrem Zugriffstoken zu erstellen, müssen Sie Ihr Power BI-Clientobjekt erstellen, mit dem Sie mit den Power BI-REST-APIs interagieren können. Sie erstellen das Power BI-Clientobjekt, indem Sie das AccessToken mit einem Microsoft.Rest.TokenCredentials-Objekt umschließen .

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 Ihre Benutzer zu Power BI umleiten. Die für diesen Vorgang verwendete API ist die CreateInstallTicket-API .

• Template-Apps – Installations-Ticket erstellen

Ein Beispiel zum Erstellen eines Installationstickets für die Installation und Konfiguration der Vorlagen-App ist in der Beispielanwendung über die Datei InstallTemplateApp/InstallAppFunction.cs verfügbar.

Das folgende Codebeispiel zeigt, wie die Vorlagen-App CreateInstallTicket REST-API verwendet wird.

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 mit dem Ticket zu Power BI

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

Es gibt verschiedene dokumentierte Methoden zum Ausgeben einer Umleitung mithilfe von POST-Anfragen. Die Auswahl eines oder eines anderen hängt vom Szenario ab und davon, wie Ihre Benutzer mit Ihrem Portal oder Dienst interagieren.

Ein einfaches Beispiel, das hauptsächlich zu Testzwecken verwendet wird, verwendet ein Formular mit einem ausgeblendeten Feld, das sich automatisch beim Laden selbst übermittelt.

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

Das folgende Beispiel der Antwort der Beispielanwendung enthält das Installationsticket und leitet Benutzer automatisch zu Power BI um. Die Antwort für diese Azure-Funktion ist dasselbe automatisch selbst sendende 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();
}

Schritt 4: Verschieben Ihrer Automatisierung in die Produktion

Wenn die von Ihnen entworfene Automatisierung bereit ist, stellen Sie sicher, dass Sie sie in die Produktion verschieben.

Verwandte Inhalte

• Probieren Sie unser Lernprogramm aus, das eine einfache Azure-Funktion verwendet, um die Konfiguration einer Vorlagen-App-Installation zu automatisieren.
• Weitere Fragen? Stellen Sie Ihre Frage in der Power BI-Community.