Del via

Automatiseret konfiguration af installationen af et skabelonprogram

  • Artikel

Skabelonapps er en fantastisk måde for kunder at begynde at få indsigt fra deres data. Skabelonapps får dem hurtigt i gang ved at forbinde dem med deres data. Skabelonappsene giver dem færdigbyggede rapporter, som de kan tilpasse, hvis de ønsker det.

Kunderne kender ikke altid detaljerne for, hvordan de opretter forbindelse til deres data. At skulle angive disse oplysninger, når de installerer en skabelonapp, kan være et smertepunkt for dem.

Hvis du er datatjenesteudbyder og har oprettet en skabelonapp for at hjælpe dine kunder med at komme i gang med deres data på din tjeneste, kan du gøre det nemmere for dem at installere dit skabelonprogram. Du kan automatisere konfigurationen af parametrene for dit skabelonprogram. Når kunden logger på din portal, vælger vedkommende et særligt link, du har forberedt. Dette link:

  • Starter automatiseringen, som indsamler de oplysninger, den har brug for.
  • Forudkonfigurer parametrene for skabelonappen.
  • Omdirigerer kunden til deres Power BI-konto, hvor de kan installere appen.

Det eneste, de skal gøre, er at vælge Installér og godkend i forhold til deres datakilde, så er de klar!

Kundeoplevelsen illustreres her.

Illustration of user experience with an auto-installation application.

I denne artikel beskrives det grundlæggende flow, forudsætningerne samt de vigtigste trin og API'er, du skal bruge for at automatisere konfigurationen af installationen af et skabelonprogram. Hvis du vil se nærmere på og komme i gang, kan du gå videre til selvstudiet, hvor du automatiserer konfigurationen af installationen af skabelonappen ved hjælp af et simpelt eksempelprogram, som vi har forberedt, og som bruger en Azure-funktion.

Grundlæggende flow

Det grundlæggende flow til automatisering af konfigurationen af installationen af et skabelonprogram er som følger:

  1. Brugeren logger på ISV'ens portal og vælger det angivne link. Denne handling starter det automatiserede flow. ISV'ens portal forbereder den brugerspecifikke konfiguration på nuværende tidspunkt.

  2. ISV'en henter et token kun til apps baseret på en tjenesteprincipal (kun app-token), der er registreret i ISV'ens lejer.

  3. Ved hjælp af REST API'er til Power BI opretter ISV'en en installationsbillet, som indeholder den brugerspecifikke parameterkonfiguration, som er forberedt af ISV'en.

  4. ISV'en omdirigerer brugeren til Power BI ved hjælp af en POST omdirigeringsmetode, der indeholder installationsbilletten.

  5. Brugeren omdirigeres til sin Power BI-konto med installationsbilletten og bliver bedt om at installere skabelonappen. Når brugeren vælger Installér, installeres skabelonappen for vedkommende.

Bemærk

Selvom parameterværdier konfigureres af ISV'en i processen med at oprette installationsbilletten, leveres legitimationsoplysninger relateret til datakilden kun af brugeren i de sidste faser af installationen. Dette arrangement forhindrer dem i at blive eksponeret for en tredjepart og sikrer en sikker forbindelse mellem brugeren og datakilderne for skabelonappen.

Forudsætninger

Følgende forudsætninger er nødvendige for at levere en forudkonfigureret installationsoplevelse til dit skabelonprogram:

  • En Power BI Pro-licens. Hvis du ikke er tilmeldt Power BI Pro, kan du tilmelde dig en gratis prøveversion, før du begynder.

  • Din egen Microsoft Entra-lejer er konfigureret. Du kan finde oplysninger om, hvordan du konfigurerer en, under Opret en Microsoft Entra-lejer.

  • En tjenesteprincipal (kun app-token), der er registreret i den foregående lejer. Du kan finde flere oplysninger under Integrer Power BI-indhold med tjenesteprincipal og en programhemmelighed. Sørg for at registrere programmet som en serverbaseret webprogramapp . Du registrerer et serverbaseret webprogram for at oprette en programhemmelighed. Fra denne proces skal du gemme program-id'et (ClientID) og programhemmeligheden (ClientSecret) til senere trin.

  • En parameteriseret skabelonapp , der er klar til installation. Skabelonappen skal oprettes i den samme lejer, som du registrerer dit program i Microsoft Entra ID i. Du kan få flere oplysninger under Tip til skabelonapps eller Opret en skabelonapp i Power BI. I skabelonappen skal du notere følgende oplysninger for de næste trin:

    • App-id, pakkenøgle og ejer-id , som de vises i URL-adressen til installation i slutningen af processen med at definere egenskaberne for skabelonappen , da appen blev oprettet. Du kan også få det samme link ved at vælge Hent link i ruden Udgivelsesadministration i skabelonappen.
    • Parameternavne , som de er defineret i skabelonappens semantiske model. Der skelnes mellem store og små bogstaver i parameternavne, og de kan også hentes fra fanen Parameter Indstillinger, når du definerer egenskaberne for skabelonappen eller fra indstillingerne for semantiske modeller i Power BI.

  • Hvis du vil kunne teste dit automatiseringsarbejdsflow, skal du føje tjenesteprincipalen til arbejdsområdet for skabelonappen som en Administration.

    Bemærk

    Du kan teste dit forudkonfigurerede installationsprogram i dit skabelonprogram, hvis skabelonappen er klar til installation, også selvom det endnu ikke er offentligt tilgængeligt på AppSource. Hvis brugere uden for din lejer skal kunne bruge det automatiserede installationsprogram til at installere dit skabelonprogram, skal skabelonappen være offentligt tilgængelig på markedspladsen for Power BI-apps. Før du distribuerer dit skabelonprogram ved hjælp af det automatiserede installationsprogram, du opretter, skal du sørge for at publicere det i Partnercenter.

Primære trin og API'er

De vigtigste trin til automatisering af konfigurationen af installationen af et skabelonprogram og de API'er, du skal bruge, er beskrevet i følgende afsnit. Selvom de fleste af trinnene udføres med REST API'er til Power BI, udføres de kodeeksempler, der er beskrevet her, med .NET SDK.

Trin 1: Opret et Power BI-klientobjekt

Brug af REST API'er til Power BI kræver, at du får et adgangstoken til din tjenesteprincipal fra Microsoft Entra-id. Du skal have et Microsoft Entra-adgangstoken til dit Power BI-program, før du foretager kald til REST API'erne til Power BI. Hvis du vil oprette Power BI-klienten med dit adgangstoken, skal du oprette dit Power BI-klientobjekt, som giver dig mulighed for at interagere med REST API'erne til Power BI. Du opretter Power BI-klientobjektet ved at ombryde AccessToken med et 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.
}

Trin 2: Opret en installationsbillet

Opret en installationsbillet, som bruges, når du omdirigerer dine brugere til Power BI. Den API, der bruges til denne handling, er CreateInstallTicket-API'en .

Du kan finde et eksempel på, hvordan du opretter en installationsbillet til installation og konfiguration af skabelonapps , i filen InstallTemplateApp/InstallAppFunction.cs i eksempelprogrammet.

I følgende kodeeksempel kan du se, hvordan du bruger skabelonappen CreateInstallTicket REST API.

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

Trin 3: Omdiriger brugere til Power BI med billetten

Når du har oprettet en installationsbillet, kan du bruge den til at omdirigere dine brugere til Power BI for at fortsætte med installationen og konfigurationen af skabelonappen. Du bruger en POST metodeomdirigering til URL-adressen til installation af skabelonappen med installationsbilletten i anmodningsteksten.

Der er forskellige dokumenterede metoder til, hvordan du udsteder en omdirigering ved hjælp POST af anmodninger. Valget af den ene eller den anden afhænger af scenariet, og hvordan brugerne interagerer med din portal eller tjeneste.

Et simpelt eksempel, der primært bruges til testformål, bruger en formular med et skjult felt, som automatisk sender sig selv ved indlæsning.

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

Følgende eksempel på eksempelprogrammets svar indeholder installationsbilletten og omdirigerer automatisk brugere til Power BI. Svaret på denne Azure-funktion er den samme formular til automatisk indsendelse af sig selv, som vi ser i det foregående HTML-eksempel.

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

Bemærk

Der er forskellige metoder til brug af POST browseromdirigeringer. Du skal altid bruge den mest sikre metode, som afhænger af dine tjenestebehov og -begrænsninger. Husk, at nogle former for usikker omdirigering kan resultere i, at brugerne eller tjenesten udsættes for sikkerhedsproblemer.

Trin 4: Flyt din automatisering til produktion

Når den automatisering, du har designet, er klar, skal du sørge for at flytte den til produktion.

Relateret indhold