Αυτοματοποιημένη ρύθμιση παραμέτρων εγκατάστασης εφαρμογής προτύπουAutomated configuration of a template app installation

Οι εφαρμογές προτύπου είναι ένας πολύ καλός τρόπος για τους πελάτες να ξεκινήσουν να λαμβάνουν δεδομενικές πληροφορίες από τα δεδομένα τους.Template apps are a great way for customers to start getting insights from their data. Οι εφαρμογές προτύπου τους βοηθούν να αρχίζουν γρήγορα τις εργασίες τους παρέχοντας σύνδεση με τα δεδομένα τους.Template apps get them up and running quickly by connecting them to their data. Οι εφαρμογές προτύπου τους παρέχουν προενσωματωμένες αναφορές που μπορούν να προσαρμόσουν εάν το επιθυμούν.The template apps provide them with prebuilt reports that they can customize if they so desire.

Οι πελάτες δεν είναι πάντα εξοικειωμένοι με τις λεπτομέρειες του τρόπου σύνδεσης των δεδομένων σας.Customers aren't always familiar with the details of how to connect to their data. Η παροχή αυτών των λεπτομερειών όταν εγκαθιστούν μια εφαρμογή προτύπου μπορεί να αποτελεί σημείο αιχμής για αυτούς.Having to provide these details when they install a template app can be a pain point for them.

Εάν παρέχετε υπηρεσίες δεδομένων και έχετε δημιουργήσει μια εφαρμογή προτύπου για να βοηθήσει τους πελάτες σας να ξεκινήσουν με τα δεδομένα τους στην υπηρεσία σας, μπορείτε να διευκολύνετε την εγκατάσταση της εφαρμογής προτύπου σας.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. Μπορείτε να αυτοματοποιήσετε τη ρύθμιση των παραμέτρων της εφαρμογής προτύπου σας.You can automate the configuration of your template app's parameters. Όταν ο πελάτης εισέρχεται στην πύλη σας, επιλέγει μια ειδική σύνδεση που έχετε προετοιμάσει.When the customer signs in to your portal, they select a special link you've prepared. Αυτή η σύνδεση:This link:

  • Εκκινεί την αυτοματοποίηση, που συγκεντρώνει τις απαραίτητες πληροφορίες.Launches the automation, which gathers the information it needs.
  • Ρυθμίζει τις παραμέτρους εφαρμογής προτύπου εκ των προτέρων.Preconfigures the template app parameters.
  • Ανακατευθύνει τον πελάτη στον λογαριασμό του Power BI όπου μπορεί να εγκαταστήσει την εφαρμογή.Redirects the customer to their Power BI account where they can install the app.

Το μόνο που πρέπει να κάνει είναι να επιλέξει Εγκατάσταση και να εκτελέσει έλεγχο ταυτότητας σε σχέση με την προέλευση δεδομένων του και θα είναι έτοιμος να ξεκινήσει!All they have to do is select Install and authenticate against their data source, and they're good to go!

Εδώ παρουσιάζεται η εμπειρία του πελάτη.The customer experience is illustrated here.

Εικόνα της εμπειρίας χρήστη με μια εφαρμογή αυτόματης εγκατάστασης.

Αυτό το άρθρο περιγράφει τη βασική ροή, τις προϋποθέσεις, τα κύρια βήματα και τα API που χρειάζεστε για την αυτοματοποίηση της ρύθμισης παραμέτρων μιας εγκατάστασης εφαρμογής προτύπου.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. Εάν θέλετε να ξεκινήσετε αμέσως, μπορείτε να μεταβείτε απευθείας στο εκπαιδευτικό βοήθημα όπου μπορείτε να αυτοματοποιήσετε τη ρύθμιση παραμέτρων της εγκατάστασης της εφαρμογής προτύπου, χρησιμοποιώντας ένα απλό δείγμα εφαρμογής που έχουμε προετοιμάσει, το οποίο χρησιμοποιεί μια συνάρτηση Azure.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.

Βασική ροήBasic flow

Η βασική ροή αυτοματοποίησης της ρύθμισης παραμέτρων μιας εγκατάστασης εφαρμογής προτύπου είναι η εξής:The basic flow of automating the configuration of a template app installation is as follows:

  1. Ο χρήστης εισέρχεται στην πύλη ISV και επιλέγει την παρεχομένη σύνδεση.The user signs in to the ISV's portal and selects the supplied link. Αυτή η ενέργεια εκκινεί την αυτοματοποιημένη ροή.This action initiates the automated flow. Η πύλη ISV προετοιμάζει τη ρύθμιση παραμέτρων του συγκεκριμένου χρήστη σε αυτό το στάδιο.The ISV's portal prepares the user-specific configuration at this stage.

  2. Ο ISV αποκτά ένα διακριτικό μόνο εφαρμογής που βασίζεται σε μια οντότητα υπηρεσίας (διακριτικό μόνο εφαρμογής), που έχει καταχωρηθεί στον μισθωτή του ISV.The ISV acquires an app-only token based on a service principal (app-only token) that's registered in the ISV's tenant.

  3. Με τη χρήση του Power BI REST API, ο ISV δημιουργεί ένα Δελτίο εγκατάστασης το οποίο περιέχει το σύνολο παραμέτρων για τον συγκεκριμένο χρήστη, όπως εκπονήθηκε από τον ISV.Using Power BI REST APIs, the ISV creates an install ticket, which contains the user-specific parameter configuration as prepared by the ISV.

  4. Ο ISV ανακατευθύνει τον χρήστη στο Power BI χρησιμοποιώντας μια μέθοδο ανακατεύθυνσης POST, η οποία περιέχει το δελτίο εγκατάστασης.The ISV redirects the user to Power BI by using a POST redirection method that contains the install ticket.

  5. Ο χρήστης ανακατευθύνεται στον λογαριασμό του Power BI με το δελτίο εγκατάστασης και του ζητείται να εγκαταστήσει την εφαρμογή προτύπου.The user is redirected to their Power BI account with the install ticket and is prompted to install the template app. Όταν ο χρήστης επιλέγει Εγκατάσταση, η εφαρμογή προτύπου εγκαθίσταται αυτόματα.When the user selects Install, the template app is installed for them.

Σημείωση

Παρόλο που οι τιμές παραμέτρων ρυθμίζονται από τον ISV κατά τη δημιουργία του δελτίου εγκατάστασης, τα διαπιστευτήρια που σχετίζονται με την προέλευση δεδομένων παρέχονται από τον χρήστη μόνο στα τελικά στάδια της εγκατάστασης.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. Αυτή η διάταξη αποτρέπει την έκθεσή τους σε έναν τρίτο και εξασφαλίζει μια ασφαλή σύνδεση μεταξύ των προελεύσεων δεδομένων εφαρμογής προτύπου και χρήστη.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.

Προαπαιτούμενα στοιχείαPrerequisites

Για την παροχή μιας προρυθμισμένης εμπειρίας εγκατάστασης για την εφαρμογή προτύπου σας, απαιτούνται οι εξής προϋποθέσεις:To provide a preconfigured installation experience for your template app, the following prerequisites are required:

  • Μια άδεια χρήσης Power BI Pro.A Power BI Pro license. Εάν δεν έχετε εγγραφεί για το Power BI Pro, εγγραφείτε για μια δωρεάν δοκιμαστική έκδοση προτού ξεκινήσετε.If you're not signed up for Power BI Pro, sign up for a free trial before you begin.

  • Η δική σας ρύθμιση μισθωτή Azure Active Directory (Azure AD).Your own Azure Active Directory (Azure AD) tenant set up. Για οδηγίες σχετικά με τον τρόπο ρύθμισης ενός, ανατρέξτε στη Δημιουργία ενός μισθωτή Azure AD.For instructions on how to set one up, see Create an Azure AD tenant.

  • Μια κύρια υπηρεσία (διακριτικό μόνο για εφαρμογή) καταχωρημένη στον προηγούμενο μισθωτή.A service principal (app-only token) registered in the preceding tenant. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Ενσωμάτωση περιεχομένου Power BI με κύρια υπηρεσία και μυστικό κωδικό εφαρμογής.For more information, see Embed Power BI content with service principal and an application secret. Βεβαιωθείτε ότι έχετε καταχωρήσει την εφαρμογή ως Εφαρμογή Web από την πλευρά του διακομιστή.Make sure to register the application as a server-side web application app. Μπορείτε να καταχωρήσετε μια εφαρμογή Web από την πλευρά του διακομιστή για να δημιουργήσετε έναν μυστικό κωδικό εφαρμογής.You register a server-side web application to create an application secret. Από αυτήν τη διαδικασία θα χρειαστεί να αποθηκεύσετε το αναγνωριστικό εφαρμογής (Αναγνωριστικό προγράμματος-πελάτη) και τον μυστικό κωδικό εφαρμογής (μυστικός κωδικός πελάτη) για τα επόμενα βήματα.From this process, you need to save the application ID (ClientID) and application secret (ClientSecret) for later steps.

  • Μια παραμετροποιημένη εφαρμογή προτύπου που είναι έτοιμη για εγκατάσταση.A parameterized template app that's ready for installation. Η εφαρμογή προτύπου πρέπει να δημιουργηθεί στον ίδιο μισθωτή στον οποίο καταχωρείτε την εφαρμογή σας στο Azure AD.The template app must be created in the same tenant in which you register your application in Azure AD. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Συμβουλές εφαρμογής προτύπου ή Δημιουργία εφαρμογής προτύπου στο Power BI.For more information, see Template app tips or Create a template app in Power BI. Από την εφαρμογή προτύπου πρέπει να λάβετε υπόψη τις ακόλουθες πληροφορίες για τα επόμενα βήματα:From the template app, you need to note the following information for the next steps:

    • το Αναγνωριστικό εφαρμογής, το Κλειδί πακέτου και το Αναγνωριστικό κατόχου, όπως εμφανίζονται στη διεύθυνση URL εγκατάστασης στο τέλος της διαδικασίας ορισμού των ιδιοτήτων της εφαρμογής προτύπου όταν δημιουργηθεί η εφαρμογή.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. Μπορείτε επίσης να λάβετε την ίδια σύνδεση, επιλέγοντας το στοιχείο Λήψη σύνδεσης στο παράθυρο Διαχείριση εκδόσεων της εφαρμογής προτύπου.You can also get the same link by selecting Get link in the template app's Release Management pane.
    • Τα Ονόματα παραμέτρων όπως ορίζονται στο σύνολο δεδομένων της εφαρμογής προτύπου.Parameter names as they're defined in the template app's dataset. Τα ονόματα παραμέτρων χρησιμοποιούν συμβολοσειρές με διάκριση πεζών-κεφαλαίων και μπορούν επίσης να ανακτηθούν από την καρτέλα Ρυθμίσεις παραμέτρων την καρτέλα κατά τον Ορισμό ιδιοτήτων της εφαρμογής προτύπου ή από τις ρυθμίσεις του συνόλου δεδομένων στο Power BI.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.
  • Για να μπορέσετε να ελέγξετε τη ροή εργασίας αυτοματισμού, προσθέστε την αρχή υπηρεσίας στο χώρο εργασίας του προτύπου app ως διαχειριστής.To be able to test your automation work flow, add the service principal to the template app workspace as an Admin.

    Σημείωση

    Μπορείτε να ελέγξετε την προρυθμισμένη εφαρμογή εγκατάστασης στην εφαρμογή προτύπου σας, εάν η εφαρμογή προτύπου είναι έτοιμη για εγκατάσταση, ακόμα και αν δεν είναι διαθέσιμη για το κοινό στο AppSource.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. Για να μπορούν οι χρήστες εκτός του μισθωτή σας να χρησιμοποιήσουν την αυτοματοποιημένη εφαρμογή εγκατάστασης για να εγκαταστήσουν την εφαρμογή του προτύπου σας, η εφαρμογή προτύπου πρέπει να είναι δημόσια διαθέσιμη στο Power BI Apps marketplace.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. Προτού διανείμετε τη δική σας εφαρμογή προτύπου χρησιμοποιώντας την εφαρμογή αυτοματοποιημένης εγκατάστασης που δημιουργείτε, φροντίστε να τη δημοσιεύσετε στο Κέντρο συνεργατών.Before you distribute your template app by using the automated installation application you're creating, be sure to publish it to Partner Center.

Κύρια βήματα και APIMain steps and APIs

Τα κύρια βήματα για την αυτοματοποίηση της ρύθμισης παραμέτρων μιας εγκατάστασης εφαρμογής προτύπου και τα API που θα χρειαστείτε, περιγράφονται στις παρακάτω ενότητες.The main steps for automating the configuration of a template app installation, and the APIs you'll need, are described in the following sections. Παρόλο που τα περισσότερα από τα βήματα γίνονται με Power BI REST API, τα παραδείγματα κώδικα που περιγράφονται εδώ γίνονται με το .NET SDK.While most of the steps are done with Power BI REST APIs, the code examples described here are made with the .NET SDK.

Βήμα 1: Δημιουργία αντικειμένου πελάτη Power BIStep 1: Create a Power BI client object

Η χρήση του Power BI REST API απαιτεί να λάβετε ένα διακριτικό πρόσβασης για την οντότητα υπηρεσίας σας από το Azure AD.Using Power BI REST APIs requires you to get an access token for your service principal from Azure AD. Είναι απαραίτητο να λάβετε ένα διακριτικό πρόσβασης Azure AD για την εφαρμογή Power BI που χρησιμοποιείτε, προτού πραγματοποιήσετε κλήσεις στα API REST του Power BI.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. Για να δημιουργήσετε το πρόγραμμα-πελάτη του Power BI με το διακριτικό πρόσβασης, πρέπει να δημιουργήσετε το αντικείμενο προγράμματος-πελάτη του Power BI που σας επιτρέπει να αλληλεπιδράσετε με τα REST API του Power BI.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. Δημιουργείτε το αντικείμενο προγράμματος-πελάτη του Power BI με την περιτύλιξη του AccessToken με ένα αντικείμενο Microsoft.Rest.TokenCredentials.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: Δημιουργία δελτίου εγκατάστασηςStep 2: Create an install ticket

Δημιουργήστε ένα δελτίο εγκατάστασης, το οποίο χρησιμοποιείται όταν ανακατευθύνετε τους χρήστες σας στο Power BI.Create an install ticket, which is used when you redirect your users to Power BI. Το API που χρησιμοποιείται για αυτήν τη λειτουργία είναι το API CreateInstallTicket.The API used for this operation is the CreateInstallTicket API.

Ένα δείγμα του τρόπου δημιουργίας ενός δελτίου εγκατάστασης για την εγκατάσταση και τη ρύθμιση παραμέτρων της εφαρμογής προτύπου είναι διαθέσιμο από το αρχείο InstallTemplateApp/InstallAppFunction.cs αρχείο στο δείγμα εφαρμογής.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.

Το παρακάτω παράδειγμα κώδικα εμφανίζει τον τρόπο χρήσης του API REST της εφαρμογής προτύπου CreateInstallTicket.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: Ανακατεύθυνση χρηστών στο Power BI με το δελτίοStep 3: Redirect users to Power BI with the ticket

Αφού δημιουργήσετε ένα δελτίο εγκατάστασης, μπορείτε να το χρησιμοποιήσετε για να ανακατευθύνετε τους χρήστες σας στο Power BI για να συνεχίσετε με την εγκατάσταση και τη ρύθμιση παραμέτρων της εφαρμογής προτύπου.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. Χρησιμοποιείτε μια ανακατεύθυνση μεθόδου POST στη διεύθυνση URL εγκατάστασης της εφαρμογής προτύπου, με το δελτίο εγκατάστασης στο σώμα της αίτησης.You use a POST method redirection to the template app's installation URL, with the install ticket in its request body.

Υπάρχουν διάφορες τεκμηριωμένες μέθοδοι σχετικά με τον τρόπο έκδοσης μιας ανακατεύθυνσης με χρήση αιτημάτων POST.There are various documented methods of how to issue a redirection by using POST requests. Η επιλογή της μίας ή τις άλλης εξαρτάται από το σενάριο και τον τρόπο με τον οποίο οι χρήστες αλληλεπιδρούν με την πύλη ή την υπηρεσία σας.Choosing one or another depends on the scenario and how your users interact with your portal or service.

Ένα απλό παράδειγμα, το οποίο χρησιμοποιείται κυρίως για σκοπούς δοκιμής, χρησιμοποιεί μια φόρμα με ένα κρυφό πεδίο, το οποίο υποβάλλει αυτόματα τον εαυτό του κατά τη φόρτωση.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>

Το παρακάτω παράδειγμα της απόκρισης του δείγματος εφαρμογής διατηρεί το δελτίο εγκατάστασης και ανακατευθύνει αυτόματα τους χρήστες στο Power BI.The following example of the sample application's response holds the install ticket and automatically redirects users to Power BI. Η απόκριση για αυτήν τη συνάρτηση Azure είναι η ίδια αυτόματη φόρμα αυτόματης υποβολής που εμφανίζεται στο προηγούμενο παράδειγμα HTML.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();
}

Σημείωση

Υπάρχουν διάφορες μέθοδοι χρήσης ανακατευθύνσεων προγράμματος περιήγησης POST.There are various methods of using POST browser redirects. Θα πρέπει να χρησιμοποιείτε πάντα την πλέον ασφαλή μέθοδο, η οποία εξαρτάται από τις ανάγκες και τους περιορισμούς σας για υπηρεσίες.You should always use the most secure method, which depends on your service needs and restrictions. Μην ξεχνάτε ότι ορισμένες μορφές μη ασφαλούς ανακατεύθυνσης μπορεί να έχουν ως αποτέλεσμα την έκθεση των χρηστών ή της υπηρεσίας σας σε ζητήματα ασφάλειας.Remember that some forms of insecure redirection can result in exposing your users or service to security issues.

Βήμα 4: Μεταφορά του αυτοματισμού στην παραγωγήStep 4: Move your automation to production

Όταν ο αυτοματισμός που έχετε σχεδιάσει είναι έτοιμος, φροντίστε να τον μεταφέρετε στην παραγωγή.When the automation you've designed is ready, be sure to move it to production.

Επόμενα βήματαNext steps