Configuration automatisée d’une installation d’application modèle

Les applications modèles constituent un excellent moyen pour les clients de commencer à obtenir des insights à partir de leurs données. Les applications modèles les mettent rapidement en place en les connectant à leurs données. Les applications de modèle leur fournissent des rapports prédéfinis qu’elles peuvent personnaliser si elles le désirent.

Les clients ne connaissent pas toujours les détails de la connexion à leurs données. Avoir à fournir ces détails quand ils installent une application modèle peut être un point de douleur pour eux.

Si vous êtes un fournisseur de services de données et que vous avez créé une application modèle pour aider vos clients à commencer à utiliser leurs données sur votre service, vous pouvez faciliter l’installation de votre application modèle. Vous pouvez automatiser la configuration des paramètres de votre application modèle. Lorsque le client se connecte à votre portail, il sélectionne un lien spécial que vous avez préparé. Ce lien :

• Lance l’automatisation, qui collecte les informations dont elle a besoin.
• Préconfigure les paramètres de l’application modèle.
• Redirige le client vers son compte Power BI où il peut installer l’application.

Tout ce qu’ils doivent faire est de sélectionner Installer et s’authentifier sur leur source de données, et ils sont bons à aller !

L’expérience client est illustrée ici.

Cet article décrit le flux de base, les prérequis, les étapes principales et les API dont vous avez besoin pour automatiser la configuration d’une installation d’une application modèle. Si vous souhaitez vous plonger et commencer, vous pouvez passer au didacticiel où vous automatisez la configuration de l’installation de l’application modèle à l’aide d’un exemple d’application simple que nous avons préparé qui utilise une fonction Azure.

Flux de base pour la configuration automatisée

Le flux de base pour automatiser la configuration d’une installation d’une application modèle se poursuit comme suit :

1. L’utilisateur se connecte au portail du fournisseur de logiciels indépendants et sélectionne le lien fourni. Cette action lance le flux automatisé. Le portail de l’éditeur de logiciels indépendants prépare à ce stade une configuration personnalisée pour l’utilisateur.
2. L’ISV acquiert un jeton d’application uniquement basé sur un principal de service (jeton d’application uniquement) inscrit dans le locataire de l’ISV.
3. À l’aide des API REST Power BI, l’éditeur de logiciels indépendants crée un ticket d’installation, qui contient la configuration de paramètre spécifique à l’utilisateur telle qu’elle est préparée par l’éditeur de logiciels indépendants.
4. L'ISV redirige l'utilisateur vers Power BI à l'aide d'une POST méthode de redirection qui contient le ticket d'installation.
5. L’utilisateur est redirigé vers son compte Power BI avec le ticket d’installation et est invité à installer l’application modèle. Lorsque l’utilisateur sélectionne Installer, l’application modèle est installée pour eux.

Prerequisites

Pour fournir une expérience d’installation préconfigurée pour votre application modèle, les conditions préalables suivantes sont requises :

• Une licence Power BI Pro. Si vous n’êtes pas inscrit à Power BI Pro, inscrivez-vous à un essai gratuit avant de commencer.

• Configuration de votre tenant Microsoft Entra personnel. Pour obtenir des instructions sur la configuration d’une instance, consultez Créer une instance Microsoft Entra.

• Un principal de service (jeton uniquement pour l'application) enregistré dans l'entité précédente. Pour plus d’informations, consultez Incorporer du contenu Power BI avec un principal de service et une clé secrète d’application. Veillez à inscrire l’application en tant qu’application web côté serveur . Vous inscrivez une application web côté serveur pour créer un secret d’application. À partir de ce processus, vous devez enregistrer l’ID d’application (ClientID) et la clé secrète d’application (ClientSecret) pour les étapes ultérieures.

• Application de modèle paramétrable prête pour l’installation. L’application modèle doit être créée dans le même locataire dans lequel vous inscrivez votre application dans Microsoft Entra ID. Pour plus d’informations, consultez les conseils de l’application modèle ou Créer une application modèle dans Power BI. À partir de l’application modèle, vous devez noter les informations suivantes pour les étapes suivantes :

  • ID d’application, clé de package et ID de propriétaire lorsqu’ils apparaissent dans l’URL d’installation à la fin du processus de définition des propriétés de l’application modèle lors de la création de l’application . Vous pouvez également obtenir le même lien en sélectionnant Obtenir le lien dans le volet Gestion des versions de l’application modèle.
  • Noms de paramètres tels qu’ils sont définis dans le modèle sémantique de l’application modèle. Les noms de paramètres sont des chaînes sensibles à la casse et peuvent également être récupérés à partir de l’onglet Paramètres de paramètre lorsque vous définissez les propriétés de l’application modèle ou des paramètres de modèle sémantique dans Power BI.

• Pour pouvoir tester votre flux de travail Automation, ajoutez le principal de service à l’espace de travail de l’application modèle en tant qu’administrateur.

  Note

  Vous pouvez tester votre application d’installation préconfigurée sur votre application modèle si l’application modèle est prête pour l’installation, même si elle n’est pas encore disponible publiquement sur AppSource. Pour que les utilisateurs extérieurs à votre locataire puissent utiliser l’application d’installation automatisée pour installer votre application modèle, l’application modèle doit être disponible publiquement dans AppSource. Avant de distribuer votre application modèle à l’aide de l’application d’installation automatisée que vous créez, veillez à la publier dans l’Espace partenaires.

Étapes principales et API

Les principales étapes d’automatisation de la configuration d’une installation d’application modèle et des API dont vous aurez besoin sont décrites dans les sections suivantes. Bien que la plupart des étapes soient effectuées avec les API REST Power BI, les exemples de code décrits ici sont effectués avec le Kit de développement logiciel (SDK) .NET.

Étape 1 : Créer un objet client Power BI

L’utilisation des API REST Power BI vous oblige à obtenir un jeton d’accès pour votre principal de service à partir de l’ID Microsoft Entra. Vous devez obtenir un jeton d’accès Microsoft Entra pour votre application Power BI avant d’effectuer des appels aux API REST Power BI. Pour créer le client Power BI avec votre jeton d’accès, vous devez créer votre objet client Power BI, ce qui vous permet d’interagir avec les API REST Power BI. Vous créez l’objet client Power BI en encapsulant AccessToken avec un objet 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.
}

Étape 2 : Créer un ticket d’installation

Créez un ticket d’installation, qui est utilisé lorsque vous redirigez vos utilisateurs vers Power BI. L’API utilisée pour cette opération est l’API CreateInstallTicket .

• Applications modèles - Créer un ticket d’installation

Un exemple de création d’un ticket d’installation pour l’installation et la configuration de l’application modèle est disponible à partir du fichier InstallTemplateApp/InstallAppFunction.cs dans l’exemple d’application.

L’exemple de code suivant montre comment utiliser l’API REST CreateInstallTicket de l’application modèle.

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

Étape 3 : Rediriger les utilisateurs vers Power BI avec le ticket

Une fois que vous avez créé un ticket d’installation, vous l’utilisez pour rediriger vos utilisateurs vers Power BI pour poursuivre l’installation et la configuration de l’application modèle. Vous utilisez une méthode de redirection vers l’URL d’installation de l’application modèle, contenant le ticket d’installation dans le corps de sa requête.

Il existe différentes méthodes documentées pour émettre une redirection à l’aide de POST requêtes. Le choix d’un ou d’un autre dépend du scénario et de la façon dont vos utilisateurs interagissent avec votre portail ou service.

Un exemple simple, principalement utilisé à des fins de test, utilise un formulaire avec un champ masqué, qui se soumet automatiquement lors du chargement.

<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’exemple suivant de la réponse de l’exemple d’application contient le ticket d’installation et redirige automatiquement les utilisateurs vers Power BI. La réponse de cette fonction Azure est le même formulaire d’auto-envoi automatique que celui que nous voyons dans l’exemple HTML précédent.

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

Étape 4 : Déplacer votre automatisation en production

Lorsque l’automatisation que vous avez conçue est prête, veillez à la déplacer en production.

Contenu connexe

• Essayez notre tutoriel, qui utilise une fonction Azure simple pour automatiser la configuration d’une installation d’application modèle.
• Plus de questions ? Essayez d’interroger la communauté Power BI