Automatyczna konfiguracja instalacji aplikacji w postaci szablonu

Aplikacje szablonów to doskonały sposób na rozpoczęcie uzyskiwania szczegółowych informacji z danych przez klientów. Aplikacje szablonów umożliwiają szybkie rozpoczęcie pracy, łącząc je z danymi. Aplikacje szablonu udostępniają wstępnie utworzone raporty, które można dostosować, jeśli tego chcą.

Klienci nie zawsze znają szczegóły dotyczące tego, jak nawiązać połączenie ze swoimi danymi. Podanie tych szczegółów podczas instalacji aplikacji szablonu może być dla nich problemem.

Jeśli jesteś dostawcą usług danych i utworzono aplikację szablonu, aby ułatwić klientom rozpoczęcie pracy z danymi w usłudze, możesz ułatwić im instalowanie aplikacji szablonu. Możesz zautomatyzować konfigurację parametrów aplikacji wzorcowej. Gdy klient zaloguje się do portalu, wybierze specjalnie przygotowany link. Ten odnośnik:

• Uruchamia automatyzację, która zbiera potrzebne informacje.
• Wstępnie konfiguruje parametry aplikacji szablonu.
• Przekierowuje klienta do konta usługi Power BI, na którym można zainstalować aplikację.

Wystarczy wybrać pozycję Zainstaluj i uwierzytelnić się w swoim źródle danych, a będą gotowi do działania!

Doświadczenie klienta jest zilustrowane tutaj.

W tym artykule opisano podstawowy przepływ, wymagania wstępne, główne kroki i interfejsy API potrzebne do zautomatyzowania konfiguracji aplikacji na podstawie szablonu. Jeśli chcesz od razu zanurzyć się i zacząć, możesz przejść do samouczka, w którym zautomatyzujesz konfigurację instalacji aplikacji szablonu, korzystając z prostej przykładowej aplikacji, którą przygotowaliśmy i która wykorzystuje funkcję platformy Azure.

Podstawowy przepływ na potrzeby automatycznej konfiguracji

Podstawowy przepływ automatyzowania konfiguracji instalacji aplikacji opartej na szablonie przebiega w następujący sposób:

1. Użytkownik loguje się do portalu niezależnego dostawcy oprogramowania i wybiera podany link. Ta akcja inicjuje zautomatyzowany przepływ. Portal niezależnego dostawcy oprogramowania przygotowuje konfigurację specyficzną dla użytkownika na tym etapie.
2. Niezależny dostawca oprogramowania uzyskuje token tylko dla aplikacji na podstawie jednostki usługi (tokenu tylko dla aplikacji) zarejestrowanej w swojej dzierżawie.
3. Używając interfejsów API REST usługi Power BI, niezależny dostawca oprogramowania tworzy zlecenie instalacji, które zawiera konfigurację parametrów specyficznych dla użytkownika przygotowaną przez dostawcę.
4. Niezależny dostawca oprogramowania (ISV) przekierowuje użytkownika do usługi Power BI przy użyciu metody przekierowania zawierającej POST zgłoszenie instalacji.
5. Użytkownik jest przekierowywany do swojego konta usługi Power BI z biletem instalacyjnym i otrzymuje prośbę o zainstalowanie aplikacji wzorcowej. Gdy użytkownik wybierze pozycję Zainstaluj, zostanie zainstalowana aplikacja szablonu.

Wymagania wstępne

Aby zapewnić wstępnie skonfigurowane środowisko instalacji aplikacji szablonu, wymagane są następujące wymagania wstępne:

• Licencja usługi Power BI Pro. Jeśli nie masz konta w usłudze Power BI Pro, przed rozpoczęciem utwórz konto bezpłatnej wersji próbnej .

• Własna konfiguracja instancji Microsoft Entra. Aby uzyskać instrukcje dotyczące sposobu ich konfigurowania, zobacz Tworzenie dzierżawy firmy Microsoft Entra.

• Jednostka usługi (token tylko dla aplikacji) zarejestrowana w poprzedniej dzierżawie. Aby uzyskać więcej informacji, zobacz Osadź zawartość Power BI za pomocą jednostki usługi oraz sekretu aplikacji. Pamiętaj, aby zarejestrować aplikację jako aplikację internetową po stronie serwera . Rejestrujesz aplikację internetową po stronie serwera, aby utworzyć tajny klucz aplikacji. W tym procesie należy zapisać identyfikator aplikacji (ClientID) i klucz tajny aplikacji (ClientSecret), aby wykonać późniejsze kroki.

• Sparametryzowana aplikacja szablonowa, która jest gotowa do instalacji. Aplikacja szablonu musi zostać utworzona w tej samej dzierżawie, w której rejestrowano Twoją aplikację w usłudze Microsoft Entra ID. Aby uzyskać więcej informacji, zobacz Porady dotyczące aplikacji szablonu lub Tworzenie aplikacji szablonu w usłudze Power BI. W aplikacji szablonu należy zanotować następujące informacje dotyczące następnych kroków:

  • Identyfikator aplikacji, klucz pakietu i identyfikator właściciela wyświetlany w adresie URL instalacji na końcu procesu definiowania właściwości aplikacji szablonu podczas tworzenia aplikacji. Możesz również uzyskać ten sam link, wybierając pozycję Pobierz link w okienku Zarządzanie wydaniami aplikacji szablonu.
  • Nazwy parametrów, jak są zdefiniowane w modelu semantycznym aplikacji szablonu. Nazwy parametrów są wrażliwe na wielkość liter i można je uzyskać z karty Ustawienia parametrów podczas definiowania właściwości aplikacji szablonu lub z ustawień modelu semantycznego w Power BI.

• Aby móc przetestować przepływ pracy automatyzacji, dodaj jednostkę usługi do obszaru roboczego aplikacji szablonu jako administrator.

  Uwaga / Notatka

  Możesz przetestować wstępnie skonfigurowaną aplikację instalacji w aplikacji szablonu, jeśli aplikacja szablonu jest gotowa do instalacji, nawet jeśli nie jest jeszcze publicznie dostępna w usłudze AppSource. Aby użytkownicy spoza dzierżawy mogli użyć automatycznego instalatora do zainstalowania aplikacji szablonowej, aplikacja szablonowa musi być publicznie dostępna w usłudze AppSource. Przed dystrybucją aplikacji szablonu, którą tworzysz za pomocą aplikacji automatycznej instalacji, pamiętaj, aby opublikować ją w Centrum partnerskim.

Główne kroki i interfejsy API

Główne kroki automatyzowania konfiguracji instalacji aplikacji szablonowej oraz potrzebne interfejsy API zostały opisane w poniższych sekcjach. Większość kroków jest wykonywana za pomocą interfejsów API REST usługi Power BI, ale przykłady kodu opisane tutaj są wykonywane przy użyciu zestawu SDK platformy .NET.

Krok 1. Tworzenie obiektu klienta usługi Power BI

Korzystanie z interfejsów API REST usługi Power BI wymaga uzyskania tokenu dostępu dla jednostki usługi z identyfikatora Entra firmy Microsoft. Przed wykonaniem wywołań do interfejsów API REST usługi Power BI wymagane jest uzyskanie tokenu dostępu firmy Microsoft Entra dla aplikacji usługi Power BI. Aby utworzyć klienta usługi Power BI przy użyciu tokenu dostępu, należy utworzyć obiekt klienta usługi Power BI, który umożliwia interakcję z interfejsami API REST usługi Power BI. Obiekt klienta usługi Power BI można utworzyć, opakowując obiekt AccessToken za pomocą obiektu 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. Tworzenie biletu instalacji

Utwórz bilet instalacji, który jest używany podczas przekierowywania użytkowników do usługi Power BI. Interfejs API używany do tej operacji to CreateInstallTicket.

• Aplikacje szablonowe — Utwórz bilet instalacyjny

Przykład tworzenia zgłoszenia instalacyjnego do instalacji i konfiguracji aplikacji z szablonu jest dostępny w pliku InstallTemplateApp/InstallAppFunction.cs w przykładowej aplikacji.

W poniższym przykładzie kodu pokazano, jak za pomocą interfejsu API REST aplikacji szablonowej CreateInstallTicket można realizować różne operacje.

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. Przekierowywanie użytkowników do usługi Power BI przy użyciu biletu

Po utworzeniu zlecenia instalacji z jego pomocą możesz przekierować użytkowników do usługi Power BI, aby kontynuować instalację i konfigurację aplikacji wzorcowej. Używasz metody przekierowania na adres URL instalacyjny aplikacji z szablonu, zawierający bilet instalacyjny w treści żądania.

Istnieją różne udokumentowane metody na wystawianie przekierowania przy użyciu żądań POST. Wybór jednego lub drugiego zależy od scenariusza i sposobu interakcji użytkowników z portalem lub usługą.

Prosty przykład, najczęściej używany do celów testowych, używa formularza z ukrytym polem, które automatycznie przesyła się po załadowaniu.

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

Poniższy przykład odpowiedzi przykładowej aplikacji zawiera bilet instalacji i automatycznie przekierowuje użytkowników do usługi Power BI. Odpowiedzią tej funkcji Azure jest taki sam automatyczny formularz samo-przesyłający się, jaki widzimy w poprzednim przykładzie HTML.

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

Krok 4. Przenoszenie automatyzacji do środowiska produkcyjnego

Gdy zaprojektowana automatyzacja jest gotowa, pamiętaj, aby przenieść ją do środowiska produkcyjnego.

Treści powiązane

• Wypróbuj nasz samouczek, który używa prostej funkcji platformy Azure do zautomatyzowania konfiguracji instalacji aplikacji szablonu.
• Więcej pytań? Spróbuj zapytać Społeczność usługi Power BI.