Sablonalkalmazás telepítésének automatizált konfigurálásaAutomated configuration of a template app installation

A sablonalkalmazásokkal az ügyfelek hasznos megállapításokat nyerhetnek adataikból.Template apps are a great way for customers to start getting insights from their data. A sablonalkalmazások gyorsan beállíthatók az adatokhoz való kapcsolódással.Template apps get them up and running quickly by connecting them to their data. A sablonalkalmazások előre elkészített jelentéseket nyújtanak, amelyek igény szerint testreszabhatók.The template apps provide them with prebuilt reports that they can customize if they so desire.

Az ügyfelek nem feltétlenül tudják, hogyan kapcsolódhatnak az adatokhoz.Customers aren't always familiar with the details of how to connect to their data. Az is nehézséget okozhat nekik, hogy a sablonalkalmazás telepítésekor megadják a helyes konfigurációt.Having to provide these details when they install a template app can be a pain point for them.

Ha Ön adatszolgáltató, és létrehozott egy sablonalkalmazást, amellyel az ügyfeleket segíti a szolgáltatásában lévő adatok kezelésében, megkönnyítheti számukra a telepítést.If you are a data services provider and have created a template app to help your customers get started with their data on your service, you can make it easier for them to install your template app. Ehhez automatikusan konfigurálhatja a sablonalkalmazás paramétereit.You can automate the configuration of your template app's parameters. Amikor az ügyfél bejelentkezik a portálra, egy külön erre a célra létrehozott hivatkozást kell kiválasztania.When the customer signs in to your portal, they select a special link you've prepared. Ez a hivatkozás:This link:

  • Elindítja az automatizálást, amely összegyűjti a szükséges információkat.Launches the automation, which gathers the information it needs.
  • Előre konfigurálja a sablonalkalmazás paramétereit.Preconfigures the template app parameters.
  • Átirányítja az ügyfelet a Power BI-fiókjába, ahol telepítheti az alkalmazást.Redirects the customer to their Power BI account where they can install the app.

Az ügyfélnek mindössze annyit kell tennie, hogy kiválasztja a Telepítés lehetőséget, és hitelesíti az adatforrását.All they have to do is select Install and authenticate against their data source, and they're good to go!

Ezt a folyamatot az alábbi ábra szemlélteti.The customer experience is illustrated here.

Az automatikus alkalmazástelepítési felhasználói élmény szemléltetése.

Ez a cikk a sablonalkalmazás telepítésekor végrehajtott automatikus konfiguráláshoz kapcsolódó alapszintű folyamatot, előfeltételeket, valamint a főbb lépéseket és API-kat ismerteti.This article describes the basic flow, the prerequisites, and the main steps and APIs you need to automate the configuration of a template app installation. Ha egyből a mély vízbe ugrana, kihagyhatja a cikket, és folytathatja az oktatóanyaggal, amelyben automatizálhatja a sablonalkalmazás telepítésének konfigurálását egy Azure-függvényt alkalmazó egyszerű mintaalkalmazásnak a használatával.If you want to dive in and get started, you can skip to the tutorial where you automate the configuration of the template app installation by using a simple sample application we've prepared that uses an Azure function.

Alapszintű folyamatBasic flow

A sablonalkalmazás-telepítés konfigurálásának automatizálása:The basic flow of automating the configuration of a template app installation is as follows:

  1. A felhasználó bejelentkezik az ISV-portálra, és kiválasztja a megadott hivatkozást.The user signs in to the ISV's portal and selects the supplied link. Ezzel elindítja az automatikus folyamatot.This action initiates the automated flow. Az ISV-portálja ebben a fázisban készíti elő a felhasználóspecifikus konfigurációt.The ISV's portal prepares the user-specific configuration at this stage.

  2. Az ISV egy csak az alkalmazásban használható tokent szerez be egy szolgáltatásnév (csak az alkalmazásban használható token) alapján, amely az ISV-bérlőben van regisztrálva.The ISV acquires an app-only token based on a service principal (app-only token) that's registered in the ISV's tenant.

  3. A Power BI REST API-khasználatával az ISV létrehoz egy telepítési jegyet, amely tartalmazza az ISV által előkészített felhasználóspecifikus paraméterkonfigurációt.Using Power BI REST APIs, the ISV creates an install ticket, which contains the user-specific parameter configuration as prepared by the ISV.

  4. Az ISV átirányítja a felhasználót a Power BI-ba egy POST átirányítási metódus használatával, amely magában foglalja a telepítési jegyet.The ISV redirects the user to Power BI by using a POST redirection method that contains the install ticket.

  5. A rendszer átirányítja a felhasználót a Power BI-fiókjába a telepítési jeggyel, és a rendszer felkéri a sablonalkalmazás telepítésére.The user is redirected to their Power BI account with the install ticket and is prompted to install the template app. Amikor a felhasználó kiválasztja a Telepítés gombot, a rendszer telepíti a sablonalkalmazást.When the user selects Install, the template app is installed for them.

Megjegyzés

A paraméterek értékeit az ISV ugyan a telepítési jegy létrehozásakor konfigurálja, az adatforráshoz kapcsolódó hitelesítő adatokat azonban a felhasználó csak a telepítés utolsó szakaszaiban adja meg.While parameter values are configured by the ISV in the process of creating the install ticket, data source-related credentials are only supplied by the user in the final stages of the installation. Az adatok ezért nem juthatnak harmadik felek tudomására, így biztosítható a felhasználó és a sablonalkalmazás adatforrásai közötti biztonságos kapcsolat.This arrangement prevents them from being exposed to a third party and ensures a secure connection between the user and the template app data sources.

ElőfeltételekPrerequisites

A sablonalkalmazás előre konfigurált telepítéséhez az alábbi feltételeknek kell teljesülniük:To provide a preconfigured installation experience for your template app, the following prerequisites are required:

  • Power BI Pro-licenc.A Power BI Pro license. Ha még nem regisztrált a Power BI Pro szolgáltatásra, a kezdés előtt hozzon létre egy ingyenes próbaverziós fiókot.If you're not signed up for Power BI Pro, sign up for a free trial before you begin.

  • Saját Azure Active Directory- (Azure AD-) bérlő beállítása.Your own Azure Active Directory (Azure AD) tenant set up. A beállítás lépéseit az Azure AD-bérlő létrehozása című cikkben olvashatja.For instructions on how to set one up, see Create an Azure AD tenant.

  • A fenti bérlőben regisztrált alkalmazáspéldány (csak az alkalmazásban használható token) .A service principal (app-only token) registered in the preceding tenant. A Power BI-tartalom beágyazása szolgáltatásnévvel és titkos alkalmazáskulccsal című cikkben talál további információt.For more information, see Embed Power BI content with service principal and an application secret. Regisztrálja az alkalmazást kiszolgálóoldali webalkalmazásként.Make sure to register the application as a server-side web application app. A kiszolgálóoldali webalkalmazás egy titkos alkalmazáskód létrehozásához kell regisztrálnia.You register a server-side web application to create an application secret. Ebből a folyamatból el kell mentenie az Alkalmazásazonosító (ClientID) és a Titkos alkalmazáskulcs (ClientSecret) értékeket a későbbi lépésekhez.From this process, you need to save the application ID (ClientID) and application secret (ClientSecret) for later steps.

  • Egy telepítésre kész paraméteres sablonalkalmazás.A parameterized template app that's ready for installation. A sablonalkalmazást ugyanabban a bérlőben kell létrehozni, amelyben az alkalmazást az Azure AD-ben regisztrálja.The template app must be created in the same tenant in which you register your application in Azure AD. További információt a sablonalkalmazással kapcsolatos tippek között és a Sablonalkalmazás létrehozása a Power BI-ban című cikkben talál.For more information, see Template app tips or Create a template app in Power BI. A sablonalkalmazásból az alábbi adatokat jegyezze fel a későbbi lépésekhez:From the template app, you need to note the following information for the next steps:

    • A telepítési URL-címen A sablonalkalmazások tulajdonságainak meghatározása folyamat végén, az alkalmazás létrehozásakor megjelenő Alkalmazásazonosító, Csomagkulcs és Tulajdonosazonosító.App ID, Package Key, and Owner ID as they appear in the installation URL at the end of the process of defining the properties of the template app when the app was created. Ezt a hivatkozást a sablonalkalmazás Kiadáskezelés területén található Hivatkozás kérése panelét kiválasztva is láthatja.You can also get the same link by selecting Get link in the template app's Release Management pane.
    • A sablonalkalmazás adatkészletében meghatározott paraméternevek.Parameter names as they're defined in the template app's dataset. A paraméternevekben megkülönböztetjük a kis- és nagybetűket, illetve megismerhetők A sablonalkalmazások tulajdonságainak meghatározása során a Paraméterbeállítások lapon vagy a Power BI-ban az adatkészlet-beállítások között is.Parameter names are case-sensitive strings and can also be retrieved from the Parameter Settings tab when you define the properties of the template app or from the dataset settings in Power BI.
  • Az automatizálási munkafolyamat teszteléséhez adja hozzá a szolgáltatásnevet a sablon alkalmazás munkaterületéhez rendszergazdaként.To be able to test your automation work flow, add the service principal to the template app workspace as an Admin.

    Megjegyzés

    Az előre konfigurált telepítőalkalmazást tesztelheti a sablonalkalmazásban, ha a sablonalkalmazás készen áll a telepítésre még akkor is, ha még nem érhető el nyilvánosan az AppSource-ban.You can test your preconfigured installation application on your template app if the template app is ready for installation, even if it isn't publicly available on AppSource yet. Ha a bérlőn kívüli felhasználók számára is lehetővé szeretné tenni az automatizált telepítőalkalmazás használatát a sablonalkalmazás telepítéséhez, akkor a sablonalkalmazásnak nyilvánosan elérhetőnek kell lennie a Power BI-alkalmazások piacterén.For users outside your tenant to be able to use the automated installation application to install your template app, the template app must be publicly available in the Power BI apps marketplace. Ezért mielőtt a sablonalkalmazást a létrehozott automatikus telepítőalkalmazással terjeszti, tegye közzé a Partnerközpontban.Before you distribute your template app by using the automated installation application you're creating, be sure to publish it to Partner Center.

Fő lépések és API-kMain steps and APIs

A sablonalkalmazások telepítési konfigurációjának automatizálását és a szükséges API-kat a következő szakaszokban ismertetjük.The main steps for automating the configuration of a template app installation, and the APIs you'll need, are described in the following sections. A lépések többségében ugyan Power BI REST API-kkal kell dolgozni, a lent leírt kódpéldák azonban a .NET SDK-val készültek.While most of the steps are done with Power BI REST APIs, the code examples described here are made with the .NET SDK.

1. lépés: Egyéni Power BI-ügyfélobjektum létrehozásaStep 1: Create a Power BI client object

A Power BI REST API-k használatához be kell szereznie egy hozzáférési jogkivonatot az Azure AD-ből a szolgáltatásnévhez.Using Power BI REST APIs requires you to get an access token for your service principal from Azure AD. Mielőtt hívásokat intézhetne a Power BI REST API-khoz, be kell szereznie egy Azure AD hozzáférési jogkivonatot a Power BI-alkalmazáshoz.You're required to get an Azure AD access token for your Power BI application before you make calls to the Power BI REST APIs. A Power BI-ügyfél hozzáférési jogkivonattal való létrehozásához célszerű létrehozni a Power BI-ügyfélobjektumot, amely lehetővé teszi a Power BI REST API-k használatát.To create the Power BI client with your access token, you need to create your Power BI client object, which allows you to interact with the Power BI REST APIs. A Power BI-ügyfél létrehozásához az AccessToken hozzáférési jogkivonatot a Microsoft.Rest.TokenCredentials objektummal kell becsomagolni.You create the Power BI client object by wrapping the AccessToken with a 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.
}

2. lépés: Telepítési jegy létrehozásaStep 2: Create an install ticket

Hozzon létre egy telepítési jegyet, amellyel a felhasználóit átirányítja a Power BI-ba.Create an install ticket, which is used when you redirect your users to Power BI. Ehhez a művelethez a CreateInstallTicket API-t használjuk.The API used for this operation is the CreateInstallTicket API.

A sablonalkalmazás telepítésére és konfigurálására szolgáló telepítési jegy létrehozására szolgáló minta a sablonalkalmazásInstallTemplateApp/InstallAppFunction.cs fájljában érhető el.A sample of how to create an install ticket for template app installation and configuration is available from the InstallTemplateApp/InstallAppFunction.cs file in the sample application.

Alább látható egy példa a sablonalkalmazás CreateInstallTicket REST API-jának használatára.The following code example shows how to use the template app 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);

3. lépés: Felhasználók átirányítása a Power BI-ba a jegy használatávalStep 3: Redirect users to Power BI with the ticket

Miután létrehozott egy telepítési jegyet, a segítségével átirányíthatja a felhasználókat a Power BI-ba, hogy folytatódhasson a sablonalkalmazás telepítése és konfigurálása.After you've created an install ticket, you use it to redirect your users to Power BI to continue with the template app installation and configuration. Ezt egy POST metódusnak a sablonalkalmazás telepítési URL-címére való átirányításával végezheti el a kérelem törzsében lévő telepítési jegy használatával.You use a POST method redirection to the template app's installation URL, with the install ticket in its request body.

A POST-kérések használatával különböző dokumentált módszerekkel lehet átirányítást elrendelni.There are various documented methods of how to issue a redirection by using POST requests. A módszert a forgatókönyv függvényében és az alapján kell kiválasztani, hogy a felhasználók hogyan használják az Ön portálját vagy szolgáltatását.Choosing one or another depends on the scenario and how your users interact with your portal or service.

Egy egyszerű példa, amely többnyire tesztelési célokat szolgál, és egy rejtett mezővel rendelkező űrlapot használ, amely betöltés után automatikusan beküldi magát.A simple example, mostly used for testing purposes, uses a form with a hidden field, which automatically submits itself upon loading.

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

Alább látható egy példa a sablonalkalmazás válaszára, amelyben szerepel a telepítési jegy, és amely a felhasználókat automatikusan a Power BI-hoz irányítja.The following example of the sample application's response holds the install ticket and automatically redirects users to Power BI. Ennek az Azure-függvénynek a válasza valójában ugyanaz az automatikusan önküldő űrlap, amelyet a fenti HTML-példában láthattunk.The response for this Azure function is the same automatically self-submitting form that we see in the preceding HTML example.

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

Megjegyzés

A POST böngészőátirányítások használatára többféle módszer is létezik.There are various methods of using POST browser redirects. A szolgáltatása igényeinek és korlátozásainak megfelelően mindig a legbiztonságosabbat válassza.You should always use the most secure method, which depends on your service needs and restrictions. Ne feledje, hogy a nem biztonságos átirányítás egyes formái miatt a felhasználók vagy a szolgáltatások biztonsági problémákba ütközhetnek.Remember that some forms of insecure redirection can result in exposing your users or service to security issues.

4. lépés: Az automatizálás élesítéseStep 4: Move your automation to production

Ha elkészült az automatizálás, próbálja ki éles környezetben.When the automation you've designed is ready, be sure to move it to production.

További lépésekNext steps