Automatische configuratie van een installatie van een sjabloon-app

  • Artikel

Sjabloon-apps zijn een uitstekende manier om klanten inzicht te geven uit hun gegevens. Met sjabloon-apps kunnen ze snel aan de slag door ze te verbinden met hun gegevens. De sjabloon-apps bieden ze vooraf gemaakte rapporten die ze desgewenst kunnen aanpassen.

Klanten zijn niet altijd bekend met de details over het maken van verbinding met hun gegevens. Deze gegevens moeten worden opgegeven wanneer ze een sjabloon-app installeren, kunnen een pijnpunt voor hen zijn.

Als u een gegevensserviceprovider bent en een sjabloon-app hebt gemaakt om uw klanten te helpen aan de slag te gaan met hun gegevens in uw service, kunt u het voor hen gemakkelijker maken om uw sjabloon-app te installeren. U kunt de configuratie van de parameters van uw sjabloon-app automatiseren. Wanneer de klant zich aanmeldt bij uw portal, selecteren ze een speciale koppeling die u hebt voorbereid. Deze koppeling:

  • Start de automatisering, die de benodigde informatie verzamelt.
  • Hiermee worden de parameters van de sjabloon-app vooraf geconfigureerd.
  • Hiermee wordt de klant omgeleid naar hun Power BI-account waar ze de app kunnen installeren.

Het enige wat ze hoeven te doen is Installeren en verifiëren op basis van hun gegevensbron, en ze zijn klaar om te gaan.

De klantervaring wordt hier geïllustreerd.

Illustration of user experience with an auto-installation application.

In dit artikel worden de basisstroom, de vereisten en de belangrijkste stappen en API's beschreven die u nodig hebt om de configuratie van de installatie van een sjabloon-app te automatiseren. Als u aan de slag wilt gaan, gaat u verder met de zelfstudie waarin u de configuratie van de installatie van de sjabloon-app automatiseert met behulp van een eenvoudige voorbeeldtoepassing die we hebben voorbereid die gebruikmaakt van een Azure-functie.

Basisstroom

De basisstroom voor het automatiseren van de configuratie van een installatie van een sjabloon-app is als volgt:

  1. De gebruiker meldt zich aan bij de portal van de ISV en selecteert de opgegeven koppeling. Met deze actie wordt de geautomatiseerde stroom gestart. De portal van de ISV bereidt in deze fase de gebruikersspecifieke configuratie voor.

  2. De ISV verkrijgt een token voor alleen apps op basis van een service-principal (alleen-app-token) dat is geregistreerd in de tenant van de ISV.

  3. Met power BI REST API's maakt de ISV een installatieticket dat de gebruikersspecifieke parameterconfiguratie bevat, zoals voorbereid door de ISV.

  4. De ISV leidt de gebruiker om naar Power BI met behulp van een POST omleidingsmethode die het installatieticket bevat.

  5. De gebruiker wordt omgeleid naar het Power BI-account met het installatieticket en wordt gevraagd om de sjabloon-app te installeren. Wanneer de gebruiker Installeren selecteert, wordt de sjabloon-app voor hen geïnstalleerd.

Notitie

Hoewel parameterwaarden worden geconfigureerd door de ISV tijdens het maken van het installatieticket, worden gegevensbronreferenties alleen door de gebruiker opgegeven in de laatste fasen van de installatie. Deze regeling voorkomt dat ze worden blootgesteld aan een derde partij en zorgt voor een beveiligde verbinding tussen de gebruiker en de gegevensbronnen van de sjabloon-app.

Vereisten

Als u een vooraf geconfigureerde installatie-ervaring voor uw sjabloon-app wilt bieden, zijn de volgende vereisten vereist:

  • Een Power BI Pro-licentie. Meld u aan voor een gratis proefversie voordat u begint als u nog niet bent aangemeld voor Power BI Pro.

  • Uw eigen Microsoft Entra-tenant is ingesteld. Zie Een Microsoft Entra-tenant maken voor instructies over het instellen van een tenant.

  • Een service-principal (alleen-app-token) geregistreerd in de voorgaande tenant. Zie Power BI-inhoud insluiten met service-principal en een toepassingsgeheim voor meer informatie. Zorg ervoor dat u de toepassing registreert als een webtoepassings-app aan de serverzijde. U registreert een webtoepassing aan de serverzijde om een toepassingsgeheim te maken. Vanuit dit proces moet u de toepassings-id (ClientID) en het toepassingsgeheim (ClientSecret) opslaan voor latere stappen.

  • Een geparameteriseerde sjabloon-app die gereed is voor installatie. De sjabloon-app moet worden gemaakt in dezelfde tenant waarin u uw toepassing registreert in Microsoft Entra ID. Zie tips voor sjabloon-apps of een sjabloon-app maken in Power BI voor meer informatie. In de sjabloon-app moet u de volgende informatie voor de volgende stappen noteren:

    • App-id, pakketsleutel en eigenaar-id zoals deze worden weergegeven in de installatie-URL aan het einde van het proces voor het definiëren van de eigenschappen van de sjabloon-app toen de app werd gemaakt. U kunt ook dezelfde koppeling ophalen door koppeling ophalen te selecteren in het deelvenster Releasebeheer van de sjabloon-app.
    • Parameternamen zoals deze zijn gedefinieerd in het semantische model van de sjabloon-app. Parameternamen zijn hoofdlettergevoelige tekenreeksen en kunnen ook worden opgehaald uit het tabblad Parameter Instellingen wanneer u de eigenschappen van de sjabloon-app of de semantische modelinstellingen in Power BI definieert.

  • Als u uw werkstroom voor automatisering wilt testen, voegt u de service-principal toe aan de werkruimte van de sjabloon-app als een Beheer.

    Notitie

    U kunt uw vooraf geconfigureerde installatietoepassing testen in uw sjabloon-app als de sjabloon-app klaar is voor installatie, zelfs als deze nog niet openbaar beschikbaar is in AppSource. Als gebruikers buiten uw tenant de toepassing voor geautomatiseerde installatie kunnen gebruiken om uw sjabloon-app te installeren, moet de sjabloon-app openbaar beschikbaar zijn in de Marketplace voor Power BI-apps. Voordat u uw sjabloon-app distribueert met behulp van de geautomatiseerde installatietoepassing die u maakt, moet u deze publiceren naar het Partnercentrum.

Belangrijkste stappen en API's

De belangrijkste stappen voor het automatiseren van de configuratie van een installatie van een sjabloon-app en de API's die u nodig hebt, worden beschreven in de volgende secties. Hoewel de meeste stappen worden uitgevoerd met Power BI REST API's, worden de hier beschreven codevoorbeelden gemaakt met de .NET SDK.

Stap 1: Een Power BI-clientobject maken

Als u Power BI REST API's gebruikt, moet u een toegangstoken ophalen voor uw service-principal van Microsoft Entra-id. U moet een Microsoft Entra-toegangstoken voor uw Power BI-toepassing ophalen voordat u de Power BI REST API's aanroept. Als u de Power BI-client wilt maken met uw toegangstoken, moet u uw Power BI-clientobject maken, zodat u kunt communiceren met de Power BI REST API's. U maakt het Power BI-clientobject door het AccessToken te verpakken met een Microsoft.Rest.TokenCredentials-object .

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

Stap 2: Een installatieticket maken

Maak een installatieticket dat wordt gebruikt wanneer u uw gebruikers omleidt naar Power BI. De API die voor deze bewerking wordt gebruikt, is de CreateInstallTicket-API .

Een voorbeeld van het maken van een installatieticket voor de installatie en configuratie van sjabloon-apps is beschikbaar via het bestand InstallTemplateApp/InstallAppFunction.cs in de voorbeeldtoepassing.

In het volgende codevoorbeeld ziet u hoe u de sjabloon-app CreateInstallTicket REST API gebruikt.

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

Stap 3: gebruikers omleiden naar Power BI met het ticket

Nadat u een installatieticket hebt gemaakt, gebruikt u dit om uw gebruikers om te leiden naar Power BI om door te gaan met de installatie en configuratie van de sjabloon-app. U gebruikt een POST methodeomleiding naar de installatie-URL van de sjabloon-app, met het installatieticket in de aanvraagbody.

Er zijn verschillende gedocumenteerde methoden voor het uitgeven van een omleiding met behulp van POST aanvragen. Het kiezen van een of andere is afhankelijk van het scenario en hoe uw gebruikers met uw portal of service communiceren.

Een eenvoudig voorbeeld, dat meestal wordt gebruikt voor testdoeleinden, gebruikt een formulier met een verborgen veld, dat automatisch wordt verzonden bij het laden.

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

In het volgende voorbeeld van het antwoord van de voorbeeldtoepassing wordt het installatieticket opgeslagen en worden gebruikers automatisch omgeleid naar Power BI. Het antwoord voor deze Azure-functie is hetzelfde automatisch zelf verzendende formulier dat we in het voorgaande HTML-voorbeeld zien.

...
    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();
}

Notitie

Er zijn verschillende methoden voor het gebruik POST van browseromleidingen. U moet altijd de veiligste methode gebruiken, die afhankelijk is van uw servicebehoeften en beperkingen. Houd er rekening mee dat sommige vormen van onveilige omleiding ertoe kunnen leiden dat uw gebruikers of service worden blootgesteld aan beveiligingsproblemen.

Stap 4: Uw automatisering verplaatsen naar productie

Wanneer de automatisering die u hebt ontworpen klaar is, moet u deze naar productie verplaatsen.

Gerelateerde inhoud

  • Probeer onze zelfstudie, die gebruikmaakt van een eenvoudige Azure-functie om de configuratie van de installatie van een sjabloon-app te automatiseren.
  • Meer vragen? Probeer het Power BI-community te vragen.