Automatisk konfiguration av en mallappsinstallation

  • Artikel

Mallappar är ett bra sätt för kunder att börja få insikter från sina data. Mallappar får igång dem snabbt genom att ansluta dem till deras data. Mallapparna ger dem fördefinierade rapporter som de kan anpassa om de så önskar.

Kunderna är inte alltid bekanta med information om hur de ansluter till sina data. Att behöva ange den här informationen när de installerar en mallapp kan vara en smärtpunkt för dem.

Om du är en datatjänstleverantör och har skapat en mallapp som hjälper dina kunder att komma igång med sina data i tjänsten kan du göra det enklare för dem att installera mallappen. Du kan automatisera konfigurationen av mallappens parametrar. När kunden loggar in på portalen väljer de en särskild länk som du har förberett. Den här länken:

  • Startar automatiseringen, som samlar in den information som behövs.
  • Förkonfigurerar mallappparametrarna.
  • Omdirigerar kunden till sitt Power BI-konto där de kan installera appen.

Allt de behöver göra är att välja Installera och autentisera mot sin datakälla, och de är bra att gå!

Kundupplevelsen visas här.

Illustration of user experience with an auto-installation application.

Den här artikeln beskriver det grundläggande flödet, förutsättningarna och de viktigaste stegen och API:erna som du behöver för att automatisera konfigurationen av en mallappinstallation. Om du vill dyka in och komma igång kan du gå vidare till självstudien där du automatiserar konfigurationen av mallappens installation med hjälp av ett enkelt exempelprogram som vi har förberett som använder en Azure-funktion.

Grundläggande flöde

Det grundläggande flödet för att automatisera konfigurationen av en mallappsinstallation är följande:

  1. Användaren loggar in på ISV-portalen och väljer den angivna länken. Den här åtgärden initierar det automatiserade flödet. ISV-portalen förbereder den användarspecifika konfigurationen i det här skedet.

  2. ISV:en hämtar en apptoken baserat på ett huvudnamn för tjänsten (endast apptoken) som är registrerad i ISV:ens klientorganisation.

  3. Med Hjälp av Power BI REST-API:er skapar ISV en installationsbiljett som innehåller den användarspecifika parameterkonfigurationen som har förberetts av ISV:en.

  4. ISV omdirigerar användaren till Power BI med hjälp av en POST omdirigeringsmetod som innehåller installationsbiljetten.

  5. Användaren omdirigeras till sitt Power BI-konto med installationsbiljetten och uppmanas att installera mallappen. När användaren väljer Installera installeras mallappen åt dem.

Kommentar

Medan parametervärden konfigureras av ISV i processen för att skapa installationsbiljetten, tillhandahålls datakällans relaterade autentiseringsuppgifter endast av användaren i de sista stegen i installationen. Det här arrangemanget förhindrar att de exponeras för tredje part och säkerställer en säker anslutning mellan användaren och mallappens datakällor.

Förutsättningar

För att tillhandahålla en förkonfigurerad installationsupplevelse för mallappen krävs följande krav:

  • En Power BI Pro-licens. Om du inte har registrerat dig för Power BI Pro så registrerar du dig för en kostnadsfri utvärderingsversion innan du börjar.

  • Din egen Microsoft Entra-klientorganisation har konfigurerats. Anvisningar om hur du konfigurerar en finns i Skapa en Microsoft Entra-klientorganisation.

  • Ett huvudnamn för tjänsten (endast apptoken) som registrerats i föregående klientorganisation. Mer information finns i Bädda in Power BI-innehåll med tjänstens huvudnamn och en programhemlighet. Se till att registrera programmet som en webbapp på serversidan. Du registrerar ett webbprogram på serversidan för att skapa en programhemlighet. Från den här processen måste du spara program-ID (ClientID) och programhemlighet (ClientSecret) för senare steg.

  • En parametriserad mallapp som är redo för installation. Mallappen måste skapas i samma klientorganisation där du registrerar ditt program i Microsoft Entra-ID. Mer information finns i Mallappstips eller Skapa en mallapp i Power BI. Från mallappen måste du anteckna följande information för nästa steg:

    • App-ID, paketnyckel och ägar-ID som de visas i installations-URL:en i slutet av processen för att definiera egenskaperna för mallappen när appen skapades. Du kan också få samma länk genom att välja Hämta länk i mallappens versionshanteringsfönster.
    • Parameternamn som de definieras i mallappens semantiska modell. Parameternamn är skiftlägeskänsliga strängar och kan också hämtas från fliken Parameter Inställningar när du definierar egenskaperna för mallappen eller från de semantiska modellinställningarna i Power BI.

  • För att kunna testa ditt automationsarbetsflöde lägger du till tjänstens huvudnamn på mallappens arbetsyta som administratör.

    Kommentar

    Du kan testa ditt förkonfigurerade installationsprogram i mallappen om mallappen är redo för installation, även om den inte är offentligt tillgänglig på AppSource ännu. För att användare utanför klientorganisationen ska kunna använda det automatiserade installationsprogrammet för att installera mallappen måste mallappen vara offentligt tillgänglig på Marknadsplatsen för Power BI-appar. Innan du distribuerar mallappen med hjälp av det automatiska installationsprogram som du skapar bör du publicera den i Partnercenter.

Huvudsteg och API:er

De viktigaste stegen för att automatisera konfigurationen av en mallappinstallation och de API:er som du behöver beskrivs i följande avsnitt. De flesta stegen görs med Power BI REST-API:er, men kodexemplen som beskrivs här görs med .NET SDK.

Steg 1: Skapa ett Power BI-klientobjekt

Om du använder Power BI REST-API:er måste du hämta en åtkomsttoken för tjänstens huvudnamn från Microsoft Entra-ID. Du måste hämta en Microsoft Entra-åtkomsttoken för ditt Power BI-program innan du gör anrop till Power BI REST-API:erna. Om du vill skapa Power BI-klienten med din åtkomsttoken måste du skapa power BI-klientobjektet, vilket gör att du kan interagera med Power BI REST-API:erna. Du skapar Power BI-klientobjektet genom att omsluta AccessToken med ett 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.
}

Steg 2: Skapa en installationsbiljett

Skapa ett installationsärende som används när du omdirigerar dina användare till Power BI. API:et som används för den här åtgärden är CreateInstallTicket-API:et.

Ett exempel på hur du skapar en installationsbiljett för installation och konfiguration av mallappar finns i filen InstallTemplateApp/InstallAppFunction.cs i exempelprogrammet.

I följande kodexempel visas hur du använder mallappen 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);

Steg 3: Omdirigera användare till Power BI med biljetten

När du har skapat ett installationsärende använder du det för att omdirigera användarna till Power BI för att fortsätta med installationen och konfigurationen av mallappen. Du använder en POST metodomdirigering till mallappens installations-URL med installationsbiljetten i begärandetexten.

Det finns olika dokumenterade metoder för hur du utfärdar en omdirigering med hjälp POST av begäranden. Om du väljer ett eller annat beror det på scenariot och hur användarna interagerar med portalen eller tjänsten.

Ett enkelt exempel, som främst används i testsyfte, använder ett formulär med ett dolt fält, som automatiskt skickar sig själv vid inlä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öljande exempel på exempelprogrammets svar innehåller installationsbiljetten och omdirigerar automatiskt användare till Power BI. Svaret för den här Azure-funktionen är samma automatiskt självskickande formulär som vi ser i föregående HTML-exempel.

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

Kommentar

Det finns olika metoder för att använda POST webbläsaromdirigeringar. Du bör alltid använda den säkraste metoden, vilket beror på dina tjänstbehov och begränsningar. Kom ihåg att vissa former av osäker omdirigering kan leda till att användarna eller tjänsten utsätts för säkerhetsproblem.

Steg 4: Flytta automatiseringen till produktion

När automatiseringen du har utformat är klar bör du flytta den till produktion.

Relaterat innehåll