Automatická konfigurácia inštalácie aplikácie šablóny

  • Článok

Aplikácie šablón sú skvelým spôsobom, ako môžu zákazníci začať získavať prehľady z údajov. Vďaka nim sa budú môcť rýchlo zapojiť do prevádzky tak, že ich pripojíte k údajom. Aplikácie šablón im poskytujú vopred vytvorené zostavy, ktoré si môžu prispôsobiť podľa požiadaviek.

Zákazníci nie sú vždy oboznámení s podrobnosťami o tom, ako sa pripojiť k svojim údajom. Pri inštalácii aplikácie šablóny je nutné zadať tieto podrobnosti, čo môže byť pre nich problémové.

Ak ste poskytovateľom údajových služieb a vytvorili ste aplikáciu šablóny, ktorá má pomôcť vašim zákazníkom začať pracovať s ich údajmi vo vašej službe, môžete im uľahčiť inštaláciu aplikácie šablóny. Môžete automatizovať konfiguráciu parametrov svojej aplikácie šablóny. Keď sa zákazník prihlási na váš portál, vyberie špeciálne prepojenie, ktoré ste pripravili. Toto prepojenie:

  • Spustí automatizáciu, ktorá zhromažďuje potrebné informácie.
  • Vopred nakonfiguruje parametre aplikácie šablóny.
  • Presmeruje zákazníka na konto Power BI, kde môže aplikáciu nainštalovať.

Stačí vybrať možnosť Inštalovať a overiť zdroj údajov. To je všetko.

Toto prostredie pre zákazníkov je znázornené nižšie.

Illustration of user experience with an auto-installation application.

Tento článok popisuje základný postup, predpoklady, hlavné kroky a rozhrania API, ktoré sú potrebné na automatizáciu konfigurácie inštalácie aplikácie šablóny. Ak chcete začať, môžete prejsť na kurz , kde sa naučíte automatizovať konfiguráciu inštalácie aplikácie šablóny pomocou pripravenej jednoduchej ukážkovej aplikácie, ktorá používa funkciu Azure.

Základný postup

Základný postup automatizácie konfigurácie inštalácie aplikácie šablóny je nasledujúci:

  1. Používateľ sa prihlási na portál nezávislého dodávateľa softvéru a vyberie poskytnuté prepojenie. Týmto krokom sa spustí automatizovaný postup. V tejto fáze portál nezávislého dodávateľa softvéru pripraví konfiguráciu pre konkrétneho používateľa.

  2. Nezávislý dodávateľ softvéru získa token len na úrovni aplikácie založený na objekte služby (token len na úrovni aplikácie), ktorý je zaregistrovaný v nájomníkovi nezávislého dodávateľa softvéru.

  3. Nezávislý dodávateľ softvéru vytvorí pomocou rozhraní REST API služby Power BI žiadosti o inštaláciu, ktorá obsahuje konfiguráciu parametrov pripravenú nezávislým dodávateľom softvéru pre konkrétneho používateľa.

  4. Nezávislý dodávateľ softvéru presmeruje používateľa do služby Power BI pomocou POST metódy presmerovania, ktorá obsahuje žiadosti o inštaláciu.

  5. Používateľ je presmerovaný do svojho konta Power BI so žiadosti o inštaláciu. Zobrazí sa výzva na inštaláciu aplikácie šablóny. Keď používateľ vyberie možnosť Inštalovať, aplikácia šablóny sa im nainštaluje.

Poznámka

Hoci sú hodnoty parametrov pri vytváraní žiadosti o inštaláciu nakonfigurované nezávislým dodávateľom softvéru, prihlasovacie údaje týkajúce sa zdroja údajov poskytuje používateľ až v záverečných fázach inštalácie. Vďaka tomu sa zabráni ich vystaveniu tretej strane, čím sa zaistí zabezpečené prepojenie medzi používateľom a zdrojmi údajov aplikácie šablóny.

Predpoklady

Ak chcete poskytnúť vopred nakonfigurovanú inštaláciu aplikácie šablóny, musia byť splnené nasledujúce predpoklady:

  • Licenciu na Power BI Pro. Ak ste sa nezaregistrovaní v službe Power BI Pro, pred začatím si zaregistrujte bezplatnú skúšobnú verziu .

  • Nastavte si vlastného nájomníka spoločnosti Microsoft Entra. Pokyny na jeho nastavenie nájdete v téme Vytvorenie nájomníka služby Microsoft Entra.

  • Objekt služby (token len na úrovni aplikácie) zaregistrovaný v predchádzajúcom nájomníkovi. Ďalšie informácie nájdete v téme Vloženie obsahu služby Power BI pomocou objektu služby a tajného kódu aplikácie. Aplikáciu zaregistrujte ako webovú aplikáciu na strane servera. Registrujete webovú aplikáciu na strane servera, čím vytvoríte tajný kód aplikácie. Počas tohto procesu uložte ID aplikácie (ClientID) a tajný kód aplikácie (ClientSecret), ktoré použijete v nasledujúcich krokoch.

  • Parametrizovaná aplikácia šablóny, ktorá je pripravená na inštaláciu. Aplikácia šablóny sa musí vytvoriť v tom istom nájomníkovi, v ktorom ste zaregistrovali svoju aplikáciu v id Microsoft Entra. Ďalšie informácie nájdete v tipoch pre aplikáciu šablóny alebo v téme Vytvorenie aplikácie šablóny v službe Power BI. V aplikácii šablóny je potrebné zaznamenať si nasledujúce informácie, ktoré budete potrebovať v ďalších krokoch:

    • ID aplikácie, kľúč balíka a ID vlastníka v zobrazení v inštalačnej URL adrese na konci procesu definovania vlastností aplikácie šablóny po vytvorení aplikácie. Rovnaké prepojenie môžete získať aj výberom položky Získať prepojenie na table Spravovanie vydania aplikácie šablóny.
    • Názvy parametrov definované v sémantickom modeli aplikácie šablóny. Názvy parametrov sú reťazce rozlišujú veľké a malé písmená a možno ich načítať aj z karty Parameter Nastavenia pri definovaní vlastností aplikácie šablóny alebo zo sémantických nastavení modelu v službe Power BI.

  • Ak chcete otestovať pracovný postup automatizácie, pridajte objekt služby do pracovného priestoru aplikácie šablóny ako Spravovanie.

    Poznámka

    Ak je aplikácia šablóny pripravená na inštaláciu, môžete v nej otestovať svoju aplikáciu s vopred nakonfigurovanou inštaláciou, aj keď ešte nie je k dispozícii v službe AppSource. Ak chcete, aby aj používatelia mimo vášho nájomníka mohli používať automatizovanú inštalačnú aplikáciu na inštaláciu aplikácie šablóny, musí byť aplikácia šablóny verejne dostupná na lokalite Power BI Apps Marketplace. Pred distribúciou aplikácie šablóny pomocou vytváranej automatizovanej inštalačnej aplikácie ju nezabudnite publikovať v Centre pre partnerov.

Hlavné kroky a rozhrania API

Hlavné kroky konfigurácie inštalácie aplikácie šablóny a jej automatizácie, ako aj potrebné rozhrania API sú popísané v nasledujúcich častiach. Väčšina krokov sa vykonáva pomocou rozhraní REST API služby Power BI, ale príklady kódu popísané nižšie sú vytvorené pomocou súpravy .NET SDK.

Krok č. 1: Vytvorenie objektu klienta Power BI

Používanie rozhraní REST API služby Power BI vyžaduje získanie prístupového tokenu pre objekt služby z ID služby Microsoft Entra. Prístupový token Microsoft Entra pre aplikáciu Power BI musíte získať ešte predtým, než zavoláte rozhrania REST API služby Power BI. Ak chcete vytvoriť klienta Power BI pomocou prístupového tokenu, vytvorte objekt klienta Power BI, čo vám umožní pracovať s rozhraniami REST API služby Power BI. Objekt klienta Power BI vytvoríte zabalením prístupového tokenu AccessToken do objektu Microsoft.Rest.TokenCredentials .

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

Krok č. 2: Vytvorenie žiadosti o inštaláciu

Vytvorte žiadosť o inštaláciu, ktorá sa používa pri presmerování používateľov do služby Power BI. Rozhranie API, ktoré sa používa pre túto operáciu, je rozhranie API CreateInstallTicket .

Ukážka vytvorenia žiadosti o inštaláciu aplikácie šablóny a jej konfiguráciu je k dispozícii v súbore InstallTemplateApp/InstallAppFunction.cs v ukážkovej aplikácii.

Nasledujúci príklad kódu ukazuje, ako používať rozhranie REST API CreateInstallTicket aplikácie šablóny.

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

Krok č. 3: Presmerovanie používateľov do služby Power BI pomocou žiadosti

Keď vytvoríte žiadosť o inštaláciu, použite ju na presmerovanie používateľov do služby Power BI, kde môžu pokračovať v inštalácii a konfigurácii aplikácie šablóny. Použijete presmerovanie POST metódou na inštalačnú URL adresu aplikácie šablóny so žiadosťou o inštaláciu v texte požiadavky.

Existujú rôzne zdokumentované metódy popisujú, ako vytvoriť presmerovanie pomocou POST požiadaviek. Výber portálu alebo služby závisí od scenára a spôsobu, akým používatelia pracujú s vaším portálom alebo službou.

Jednoduchý príklad, ktorý sa používa hlavne na testovacie účely, používa formulár so skrytým poľom, ktorý sa automaticky odošle pri načítaní.

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

Nasledujúci príklad odpovede vzorovej aplikácie obsahuje žiadosť o inštaláciu a automaticky presmeruje používateľov do služby Power BI. Odpoveďou na túto funkciu Azure je ten istý automaticky odosielaný formulár, ktorý vidíme v príklade HTML vyššie.

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

Poznámka

Existujú rôzne metódy, ako používať POST presmerovania v prehliadači. Vždy by ste mali používať najbezpečnejšiu metódu, ktorá závisí od potrieb a obmedzení služby. Pamätajte, že niektoré formy nezabezpečeného presmerovania môžu viesť k ohrozeniu používateľov alebo služby.

Krok č. 4: Presunutie automatizácie do produkcie

Keď je automatizácia, ktorú ste navrhli, pripravená, nezabudnite ju presunúť do produkcie.

Súvisiaci obsah