Condividi tramite

Configurazione automatica di un'installazione di un'app modello

  • Articolo

Le app modello sono un ottimo modo per consentire ai clienti di iniziare a ottenere informazioni dettagliate dai dati. Le app modello li attivano e vengono eseguiti rapidamente connettendoli ai dati. Le app modello forniscono loro report predefiniti che possono personalizzare se lo desiderano.

I clienti non hanno sempre familiarità con i dettagli su come connettersi ai dati. La necessità di fornire questi dettagli quando installano un'app modello può essere un punto di dolore per loro.

Se si è un provider di servizi dati e si è creata un'app modello per aiutare i clienti a iniziare a usare i dati nel servizio, è possibile semplificare l'installazione dell'app modello. È possibile automatizzare la configurazione dei parametri dell'app modello. Quando il cliente accede al portale, seleziona un collegamento speciale preparato. Questo collegamento:

  • Avvia l'automazione, che raccoglie le informazioni necessarie.
  • Preconfigura i parametri dell'app modello.
  • Reindirizza il cliente al proprio account Power BI in cui può installare l'app.

Tutto ciò che devono fare è selezionare Installa ed eseguire l'autenticazione con l'origine dati, quindi è consigliabile procedere.

L'esperienza del cliente è illustrata qui.

Illustration of user experience with an auto-installation application.

Questo articolo descrive il flusso di base, i prerequisiti e i passaggi principali e le API necessari per automatizzare la configurazione di un'installazione di un'app modello. Per iniziare, è possibile passare all'esercitazione in cui automatizzare la configurazione dell'installazione dell'app modello usando una semplice applicazione di esempio preparata che usa una funzione di Azure.

Flusso di base

Il flusso di base dell'automazione della configurazione di un'installazione di un'app modello è il seguente:

  1. L'utente accede al portale dell'ISV e seleziona il collegamento fornito. Questa azione avvia il flusso automatizzato. Il portale isv prepara la configurazione specifica dell'utente in questa fase.

  2. L'ISV acquisisce un token solo app basato su un'entità servizio (token solo app) registrato nel tenant dell'ISV.

  3. Usando le API REST di Power BI, l'ISV crea un ticket di installazione che contiene la configurazione dei parametri specifica dell'utente come preparato dall'ISV.

  4. L'ISV reindirizza l'utente a Power BI usando un POST metodo di reindirizzamento che contiene il ticket di installazione.

  5. L'utente viene reindirizzato al proprio account Power BI con il ticket di installazione e viene richiesto di installare l'app modello. Quando l'utente seleziona Installa, l'app modello viene installata per loro.

Nota

Mentre i valori dei parametri sono configurati dall'ISV durante il processo di creazione del ticket di installazione, le credenziali correlate all'origine dati vengono fornite solo dall'utente nelle fasi finali dell'installazione. Questa disposizione impedisce che vengano esposte a terze parti e garantisce una connessione sicura tra l'utente e le origini dati dell'app modello.

Prerequisiti

Per offrire un'esperienza di installazione preconfigurata per l'app modello, sono necessari i prerequisiti seguenti:

  • Una licenza Power BI. Se non si è iscritti a Power BI Pro, iscriversi a una versione di valutazione gratuita prima di iniziare.

  • Il tenant microsoft Entra è configurato. Per istruzioni su come configurare un tenant, vedere Creare un tenant di Microsoft Entra.

  • Un'entità servizio (token solo app) registrata nel tenant precedente. Per altre informazioni, vedere Incorporare contenuto di Power BI con un'entità servizio e un segreto dell'applicazione. Assicurarsi di registrare l'applicazione come app applicazione Web sul lato server. È possibile registrare un'applicazione Web sul lato server per creare un segreto dell'applicazione. Da questo processo è necessario salvare l'ID applicazione (ClientID) e il segreto dell'applicazione (ClientSecret) per i passaggi successivi.

  • Un'app modello con parametri pronta per l'installazione. L'app modello deve essere creata nello stesso tenant in cui si registra l'applicazione in Microsoft Entra ID. Per altre informazioni, vedere Suggerimenti per le app modello o Creare un'app modello in Power BI. Dall'app modello è necessario prendere nota delle informazioni seguenti per i passaggi successivi:

    • ID app, chiave pacchetto e ID proprietario così come vengono visualizzati nell'URL di installazione alla fine del processo di definizione delle proprietà dell'app modello al momento della creazione dell'app. È anche possibile ottenere lo stesso collegamento selezionando Ottieni collegamento nel riquadro Gestione delle versioni dell'app modello.
    • Nomi di parametri definiti nel modello semantico dell'app modello. I nomi dei parametri fanno distinzione tra maiuscole e minuscole e possono essere recuperati anche dalla scheda Parametro Impostazioni quando si definiscono le proprietà dell'app modello o dalle impostazioni del modello semantico in Power BI.

  • Per poter testare il flusso di lavoro di automazione, aggiungere l'entità servizio all'area di lavoro dell'app modello come Amministrazione.

    Nota

    È possibile testare l'applicazione di installazione preconfigurata nell'app modello se l'app modello è pronta per l'installazione, anche se non è ancora disponibile pubblicamente in AppSource. Per consentire agli utenti esterni al tenant di usare l'applicazione di installazione automatica per installare l'app modello, l'app modello deve essere disponibile pubblicamente nel marketplace delle app di Power BI. Prima di distribuire l'app modello usando l'applicazione di installazione automatica che si sta creando, assicurarsi di pubblicarla nel Centro per i partner.

Passaggi principali e API

I passaggi principali per automatizzare la configurazione di un'installazione di un'app modello e le API necessarie sono descritti nelle sezioni seguenti. Anche se la maggior parte dei passaggi viene eseguita con le API REST di Power BI, gli esempi di codice descritti di seguito vengono creati con .NET SDK.

Passaggio 1: Creare un oggetto client di Power BI

L'uso delle API REST di Power BI richiede di ottenere un token di accesso per l'entità servizio da Microsoft Entra ID. È necessario ottenere un token di accesso Microsoft Entra per l'applicazione Power BI prima di effettuare chiamate alle API REST di Power BI. Per creare il client Power BI con il token di accesso, è necessario creare l'oggetto client di Power BI, che consente di interagire con le API REST di Power BI. Per creare l'oggetto client di Power BI, eseguire il wrapping di AccessToken con un oggetto 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.
}

Passaggio 2: Creare un ticket di installazione

Creare un ticket di installazione, che viene usato quando si reindirizza gli utenti a Power BI. L'API usata per questa operazione è l'API CreateInstallTicket .

Un esempio di come creare un ticket di installazione per l'installazione e la configurazione dell'app modello è disponibile nel file InstallTemplateApp/InstallAppFunction.cs nell'applicazione di esempio.

L'esempio di codice seguente illustra come usare l'API REST CreateInstallTicket dell'app modello.

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

Passaggio 3: Reindirizzare gli utenti a Power BI con il ticket

Dopo aver creato un ticket di installazione, usarlo per reindirizzare gli utenti a Power BI per continuare con l'installazione e la configurazione dell'app modello. Si usa un POST reindirizzamento del metodo all'URL di installazione dell'app modello, con il ticket di installazione nel corpo della richiesta.

Esistono diversi metodi documentati su come eseguire un reindirizzamento usando POST le richieste. La scelta di uno o un altro dipende dallo scenario e dal modo in cui gli utenti interagiscono con il portale o il servizio.

Un semplice esempio, usato principalmente a scopo di test, usa un modulo con un campo nascosto, che si invia automaticamente al caricamento.

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

L'esempio seguente della risposta dell'applicazione di esempio contiene il ticket di installazione e reindirizza automaticamente gli utenti a Power BI. La risposta per questa funzione di Azure è lo stesso modulo di invio automatico visualizzato nell'esempio HTML precedente.

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

Nota

Esistono vari metodi di utilizzo POST dei reindirizzamenti del browser. È consigliabile usare sempre il metodo più sicuro, che dipende dalle esigenze e dalle restrizioni del servizio. Tenere presente che alcune forme di reindirizzamento non sicuro possono comportare l'esposizione di utenti o servizi a problemi di sicurezza.

Passaggio 4: Spostare l'automazione nell'ambiente di produzione

Quando l'automazione progettata è pronta, assicurarsi di spostarla nell'ambiente di produzione.

Contenuto correlato