Automatisert konfigurasjon av en malappinstallasjon

  • Artikkel

Malapper er en flott måte for kunder å begynne å få innsikt fra dataene sine. Malapper får dem raskt i gang ved å koble dem til dataene. Malappene gir dem forhåndsbygde rapporter som de kan tilpasse hvis de ønsker det.

Kunder er ikke alltid kjent med detaljene om hvordan de kobler til dataene sine. Hvis du må oppgi disse detaljene når de installerer en malapp, kan det være et smertepunkt for dem.

Hvis du er en leverandør av datatjenester og har opprettet en malapp for å hjelpe kundene med å komme i gang med dataene på tjenesten, kan du gjøre det enklere for dem å installere malappen. Du kan automatisere konfigurasjonen av malappens parametere. Når kunden logger på portalen, velger de en spesiell kobling du har forberedt. Denne koblingen:

  • Starter automatiseringen, som samler inn informasjonen den trenger.
  • Forhåndskonfigurerer parameterne for malappen.
  • Omdirigerer kunden til Power BI-kontoen der de kan installere appen.

Alt de trenger å gjøre, er å velge Installer og autentisere mot datakilden, og de er gode å gå!

Kundeopplevelsen er illustrert her.

Illustration of user experience with an auto-installation application.

Denne artikkelen beskriver den grunnleggende flyten, forutsetningene og hovedtrinnene og API-ene du trenger for å automatisere konfigurasjonen av en malappinstallasjon. Hvis du vil dykke inn og komme i gang, kan du gå til opplæringen der du automatiserer konfigurasjonen av malappinstallasjonen ved hjelp av et enkelt eksempelprogram vi har forberedt som bruker en Azure-funksjon.

Grunnleggende flyt

Den grunnleggende flyten for å automatisere konfigurasjonen av en malappinstallasjon er som følger:

  1. Brukeren logger seg på ISV-portalen og velger den angitte koblingen. Denne handlingen starter den automatiserte flyten. ISV-portalen klargjør den brukerspesifikke konfigurasjonen på dette stadiet.

  2. ISV kjøper et app-only-token basert på en tjenestekontohaver (app-only token) som er registrert i ISV-leieren.

  3. Ved hjelp av REST-API-er for Power BI oppretter ISV en installasjonsforespørsel, som inneholder den brukerspesifikke parameterkonfigurasjonen som klargjort av ISV.

  4. ISV omdirigerer brukeren til Power BI ved hjelp av en POST omadresseringsmetode som inneholder installasjonsbilletten.

  5. Brukeren omdirigeres til Power BI-kontoen med installasjonsbilletten og blir bedt om å installere malappen. Når brukeren velger Installer, installeres malappen for dem.

Merk

Selv om parameterverdier konfigureres av ISV i prosessen med å opprette installasjonsbilletten, leveres bare datakilderelatert legitimasjon av brukeren i sluttfasen av installasjonen. Denne ordningen hindrer dem i å bli utsatt for en tredjepart og sikrer en sikker tilkobling mellom brukeren og datakildene for malappen.

Forutsetning

Følgende forutsetninger kreves for å gi en forhåndskonfigurert installasjonsopplevelse for malappen:

  • En Power BI Pro-lisens. Hvis du ikke er registrert for Power BI Pro, kan du registrere deg for en gratis prøveversjon før du begynner.

  • Din egen Microsoft Entra-leier er konfigurert. Hvis du vil ha instruksjoner om hvordan du konfigurerer en, kan du se Opprette en Microsoft Entra-leier.

  • En tjenestekontohaver (bare apptoken) registrert i den foregående leieren. Hvis du vil ha mer informasjon, kan du se Bygge inn Power BI-innhold med tjenestekontohaver og en programhemmelighet. Pass på at du registrerer programmet som en nettprogramapp på serversiden. Du registrerer et nettprogram på serversiden for å opprette en programhemmelighet. Fra denne prosessen må du lagre program-IDen (ClientID) og programhemmeligheten (ClientSecret) for senere trinn.

  • En parameterisert malapp som er klar for installasjon. Malappen må opprettes i samme leier der du registrerer programmet i Microsoft Entra ID. Hvis du vil ha mer informasjon, kan du se Tips for Mal-appen eller Opprette en malapp i Power BI. Fra malappen må du legge merke til følgende informasjon for de neste trinnene:

    • App-ID, pakkenøkkel og eier-ID slik de vises i nettadressen for installasjonen på slutten av prosessen med å definere egenskapene for malappen da appen ble opprettet. Du kan også få den samme koblingen ved å velge Hent kobling i utgivelsesbehandlingsruten for malappen.
    • Parameternavn slik de er definert i malappens semantiske modell. Parameternavn skiller mellom store og små bokstaver og kan også hentes fra kategorien Parameter Innstillinger når du definerer egenskapene for malappen eller fra semantiske modellinnstillinger i Power BI.

  • Hvis du vil kunne teste arbeidsflyten for automatisering, kan du legge til tjenestekontohaveren i arbeidsområdet for malappen som administrator.

    Merk

    Du kan teste det forhåndskonfigurerte installasjonsprogrammet på malappen hvis malappen er klar for installasjon, selv om den ikke er offentlig tilgjengelig på AppSource ennå. For at brukere utenfor leieren skal kunne bruke det automatiserte installasjonsprogrammet til å installere malappen, må malappen være offentlig tilgjengelig på Markedsplassen for Power BI-apper. Før du distribuerer malappen ved hjelp av det automatiserte installasjonsprogrammet du oppretter, må du publisere den til Partnersenter.

Hovedtrinn og API-er

De viktigste trinnene for å automatisere konfigurasjonen av en malappinstallasjon, og API-ene du trenger, er beskrevet i avsnittene nedenfor. Selv om de fleste trinnene utføres med REST-API-er for Power BI, blir kodeeksempler som er beskrevet her, laget med .NET SDK.

Trinn 1: Opprette et Power BI-klientobjekt

Bruk av REST-API-er for Power BI krever at du får et tilgangstoken for tjenestekontohaveren fra Microsoft Entra ID. Du må få et Microsoft Entra-tilgangstoken for Power BI-programmet før du foretar anrop til REST-API-ene for Power BI. Hvis du vil opprette Power BI-klienten med tilgangstokenet, må du opprette Power BI-klientobjektet, som lar deg samhandle med REST-API-ene for Power BI. Du oppretter Power BI-klientobjektet ved å pakke inn 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.
}

Trinn 2: Opprette en installasjonsforespørsel

Opprett en installasjonsforespørsel, som brukes når du omdirigerer brukerne til Power BI. API-en som brukes for denne operasjonen, er CreateInstallTicket-API-en .

Et eksempel på hvordan du oppretter en installasjonsforespørsel for installasjon og konfigurasjon av malappen, er tilgjengelig fra InstallTemplateApp/InstallAppFunction.cs-filen i eksempelprogrammet.

Følgende kodeeksempel viser hvordan du bruker MAL-appen 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);

Trinn 3: Omdirigere brukere til Power BI med billetten

Når du har opprettet en installasjonsforespørsel, bruker du den til å omdirigere brukerne til Power BI for å fortsette med installasjon og konfigurasjon av malappen. Du bruker en POST metodeomadressering til malappens nettadresse for installasjon, med installasjonsforespørselen i forespørselsteksten.

Det finnes ulike dokumenterte metoder for hvordan du utsteder en omadressering ved hjelp POST av forespørsler. Valg av ett eller annet avhenger av scenarioet og hvordan brukerne samhandler med portalen eller tjenesten.

Et enkelt eksempel, for det meste brukt til testformål, bruker et skjema med et skjult felt, som automatisk sender seg inn ved innlasting.

<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 inneholder installasjonsbilletten og omdirigerer automatisk brukere til Power BI. Svaret for denne Azure-funksjonen er det samme automatisk selvinnsendende skjemaet som vi ser i det foregående HTML-eksemplet.

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

Merk

Det finnes ulike metoder for å bruke POST nettleseromadresseringer. Du bør alltid bruke den sikreste metoden, som avhenger av tjenestebehov og begrensninger. Husk at noen former for usikker omadressering kan føre til at brukerne eller tjenesten utsettes for sikkerhetsproblemer.

Trinn 4: Flytte automatiseringen til produksjon

Når automatiseringen du har utformet, er klar, må du flytte den til produksjon.

Relatert innhold