Tutoriel : Créer un flux de tâches translytical (aperçu)

Dans ce tutoriel de bout en bout, vous créez un exemple de flux de tâches transanalytique qui écrit dans une base de données SQL avec Fabric. Pour illustrer l’expérience complète de montée en puissance, nous nous concentrons sur un flux de tâches translytique pour un scénario d’annotation de données.

Dans ce tutoriel, vous allez apprendre à :

Si vous n’avez pas de capacité Fabric existante, démarrez une version d’évaluation Fabric.

Conditions préalables

• Activez les fonctionnalités d’évaluation requises dans Power BI Desktop.
• Power BI Desktop. Si Power BI Desktop n’est pas installé sur votre appareil, suivez les instructions fournies dans Obtenir Power BI Desktop.

Aperçu

La création d’un flux de tâches translytical nécessite trois tâches pour activer vos scénarios automatisés :

• Stocker des données

  Commencez par une source de données Fabric existante. Dans ce tutoriel, nous utilisons une base de données SQL avec des exemples de données.

• Développer des données

  Écrivez une fonction de données utilisateur Fabric qui est appelée à partir d’un rapport Power BI. Cette fonction peut effectuer n’importe quel nombre d’actions, de la modification de la source de données du rapport à l’envoi d’une notification à la création d’un élément de travail dans un pipeline d’approbations. Dans ce tutoriel, nous créons une fonction de données utilisateur qui prend une nouvelle description de produit et l’écrit dans la base de données SQL.

• Visualiser les données

  Créez un rapport Power BI qui affiche les données sources et les éléments interactifs qui appellent la fonction de données. Dans ce tutoriel, nous utilisons un segment de texte pour collecter la description du produit auprès de l’utilisateur et l’envoyer à la fonction de données utilisateur. Ensuite, le rapport s’actualise pour afficher la table mise à jour.

Créer une base de données SQL

Ce scénario utilise l’exemple de jeu de données AdventureWorksLT dans la base de données SQL.

1. Suivez les étapes décrites dans Créer une base de données SQL dans le portail Fabric.

   Notez le nom que vous donnez à la base de données SQL. Vous utilisez cette valeur plus loin dans le tutoriel.

2. Après avoir créé la base de données, choisissez l’option Exemple de données pour charger les exemples de données AdventureWorksLT dans votre base de données vide.

Créer une fonction de données utilisateur

Créez une fonction de données utilisateur dans un espace de travail.

1. Accédez à l’espace de travail de votre choix dans Power BI ou Fabric.

2. Sélectionnez Nouvel élément.

3. Sélectionnez Fonctions de données utilisateur dans le groupe Développer des données .

   

4. Fournissez un nom pour la nouvelle fonction de données utilisateur, par exemple sqlwriteback, puis sélectionnez Créer.

   Notez le nom que vous utilisez et le nom de l’espace de travail. Vous utilisez ces deux valeurs plus loin dans le tutoriel.

5. Sélectionnez Nouvelle fonction.

Se connecter à votre base de données SQL

Connectez la fonction de données utilisateur à la base de données SQL que vous avez créée précédemment. Vérifiez que vous disposez des autorisations d’accès à la base de données SQL avant de continuer.

1. Sélectionnez Gérer les connexions sur la page de votre nouvelle fonction de données utilisateur.

   

2. Sélectionnez Ajouter une connexion de données.

3. Sélectionnez la base de données SQL AdventureWorksLT que vous avez créée précédemment, puis sélectionnez Se connecter.

4. Lorsque la connexion est créée, un alias est automatiquement créé pour la connexion. Notez la valeur alias à utiliser plus loin dans le didacticiel.

   

5. Fermez la page Connexions pour revenir à votre fonction de données utilisateur.

Ajouter du code de fonction

Ajoutez du code à votre fonction de données utilisateur afin qu’elle écrive des données dans la table [SalesLT].[ProductDescription], dans l’exemple AdventureWorksLT dans la base de données SQL.

Les fonctions de données utilisateur utilisent pyodbc par défaut pour les connexions SQL, et nous recommandons cette bibliothèque pour ce scénario.

Pour connecter une fonction de données utilisateur à un bouton Power BI, la fonction doit retourner une chaîne.

1. Remplacez le code par défaut dans votre fonction de données utilisateur par l’exemple suivant :

   import fabric.functions as fn
   import uuid
   
   udf = fn.UserDataFunctions()
   
   @udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>") 
   @udf.function() 
   
   # Take a product description and product model ID as input parameters and write them back to the SQL database
   # Users will provide these parameters in the PowerBI report
   def write_one_to_sql_db(sqlDB: fn.FabricSqlConnection, productDescription: str, productModelId:int) -> str: 
   
       # Error handling to ensure product description doesn't go above 200 characters
       if(len(productDescription) > 200):
           raise fn.UserThrownError("Descriptions have a 200 character limit. Please shorten your description.", {"Description:": productDescription})
   
       # Establish a connection to the SQL database  
       connection = sqlDB.connect() 
       cursor = connection.cursor() 
   
       # Insert data into the ProductDescription table  
       insert_description_query = "INSERT INTO [SalesLT].[ProductDescription] (Description) OUTPUT INSERTED.ProductDescriptionID VALUES (?)" 
       cursor.execute(insert_description_query, productDescription) 
   
       # Get the result from the previous query 
       results = cursor.fetchall() 
   
       # In real-world cases, call an API to retrieve the cultureId
       # For this example, generate a random Id instead
       cultureId = str(uuid.uuid4()) 
   
       # Insert data into the ProductModelProductDescription table 
       insert_model_description_query = "INSERT INTO [SalesLT].[ProductModelProductDescription] (ProductModelID, ProductDescriptionID, Culture) VALUES (?, ?, ?);" 
       cursor.execute(insert_model_description_query, (productModelId, results[0][0], cultureId[:6])) 
   
       # Commit the transaction 
       connection.commit() 
       cursor.close() 
       connection.close()  
   
       return "Product description was added" 
   

2. Recherchez la ligne de code suivante dans l’exemple :

   @udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>")
   

3. Remplacez le placeholder alias par la valeur de l’alias de la section précédente.

   Vous pouvez rouvrir la page Gérer les connexions pour afficher l’alias de connexion.

Tester l’exemple de code

Utilisez les étapes de cette section si vous souhaitez tester l’exemple de code jusqu’à présent.

1. Cliquez sur Publier.

2. Une fois la fonction publiée, pointez sur la fonction write_one_to_sql_db dans le menu de l’Explorateur Functions , puis sélectionnez l’icône Exécuter .

3. Dans la page Exécuter, fournissez des exemples de données pour les deux paramètres requis :

   • productDescription : chaîne
   • productModelId : entier compris entre 1 et 127

4. Sélectionnez Exécuter.

5. Examinez la sortie de cette fonction et les journaux générés.

6. Fermez la page Exécuter lorsque vous avez terminé le test.

Si vous recevez des erreurs lors de l’exécution de l’exemple de code, vérifiez que votre compte dispose des autorisations d’accès à la base de données.

Accorder des autorisations utilisateur (facultatif)

Si d’autres utilisateurs interagissent avec le rapport Power BI qui appelle cette fonction, accordez-leur des autorisations Exécuter des fonctions .

1. Dans la page fonctions, sélectionnez Partager.

2. Sélectionnez la première zone de la fenêtre contextuelle Créer et envoyer un lien .

3. Sélectionnez Exécuter des fonctions et afficher les journaux des fonctions dans la liste Des autorisations supplémentaires , puis sélectionnez Appliquer.

   

4. Dans la zone Entrer un nom ou une adresse e-mail , indiquez les utilisateurs ou les groupes que vous souhaitez disposer d’autorisations pour cette fonction.

5. Sélectionnez Envoyer.

Créer un rapport Power BI

Dans cette section, vous allez créer un rapport Power BI qui extrait les données de la base de données SQL que vous avez créée dans la section précédente.

Se connecter à la base de données SQL

Connectez-vous à votre base de données SQL comme source de données pour votre rapport.

1. Dans Power BI Desktop, créez un rapport.

2. Sélectionnez le catalogue OneLake>la base de données SQL.

   

3. Dans la fenêtre du catalogue OneLake , sélectionnez la base de données que vous avez créée dans la section précédente. Par exemple, AdventureWorksLT. Ensuite, sélectionnez Se connecter.

4. Suivez les instructions pour vous authentifier auprès de la base de données.

5. Une fois que vous vous connectez à la base de données, la fenêtre navigateur s’ouvre. Sélectionnez les tableaux suivants, puis sélectionnez Charger :

   • SalesLT.ProductDescription
   • SalesLT.ProductModel
   • SalesLT.ProductModelProductDescription

   

6. Lorsque vous y êtes invité, choisissez DirectQuery comme mode de connexion, puis sélectionnez Ok.

   Le mode DirectQuery est une connexion active qui permet au rapport d’actualiser les données et de refléter les modifications de données. Pour plus d’informations, consultez DirectQuery dans Power BI.

Générer le rapport Power BI

Dans cette section, générez des visuels avec les données que vous avez chargées dans votre rapport Power BI.

1. Dans le menu Données , sélectionnez les colonnes suivantes :

   • SalesLT.ProductModel > Name
   • SalesLT.ProductModelProductDescription > ProductModelID

   

   Une table à deux colonnes apparaît dans votre fenêtre de rapport.

   

2. Dans le menu Visualisations , sélectionnez l’icône de segment de texte .

   

   Conseil / Astuce

   Si vous ne voyez pas l’icône de segment de texte, vérifiez que la fonctionnalité d’aperçu du segment de texte est activée dans Power BI Desktop. Pour plus d’informations, consultez Fonctionnalités de préversion requises.

   Un visuel de segmenteur de texte apparaît dans votre fenêtre de rapport.

   

3. Sélectionnez le trancheur de texte et utilisez les options Format du visuel>Général>Titre pour donner au trancheur de texte le titre suivant : Write a new product description.

4. Dans la barre d'outils, sélectionnez le menu Insérer et ajoutez un bouton Nouveau au rapport. Faites glisser le bouton sous le filtre de texte.

   

5. Sélectionnez le bouton et développez les options Action dans le volet du bouton Format. Réglez le bouton radio Action sur Activé.

6. Fournissez les valeurs suivantes pour votre bouton :

   Paramètre	Valeur
   Type	Sélectionner la fonction Données
   Espace de travail	Sélectionnez l’espace de travail qui contient la fonction de données utilisateur que vous avez effectuée dans la section précédente.
   Jeu de fonctions	Sélectionnez le jeu de fonctions qui contient votre fonction de données. Par exemple, sqlwriteback.
   Fonction de données	Sélectionnez votre fonction de données. Par exemple, write_one_to_sql_db.

   Conseil / Astuce

   Si vous ne voyez pas l’option de fonction Données , vérifiez que la fonctionnalité d’aperçu des flux de tâches Translytical est activée dans Power BI Desktop.

   Si vous voyez l'option Fonction de données mais que votre fonction de données utilisateur ne s’affiche pas, assurez-vous que votre fonction de données retourne une chaîne.

7. Une fois que vous avez sélectionné votre fonction de données, d’autres paramètres apparaissent pour représenter les paramètres que la fonction prend. Renseignez les valeurs suivantes :

   Paramètre	Valeur
   productDescription	Sélectionnez le segment de texte dans votre rapport, écrivez une nouvelle description de produit.
   productModelId	Sélectionnez le bouton Mise en forme conditionnelle (fx). Une nouvelle fenêtre s’ouvre. Pour le paramètre de style Format , conservez la valeur de champ par défaut. Pour le paramètre « Sur quel champ devrions-nous baser ceci ? », sélectionnez Toutes les données>>.
   Résumé	Sélectionnez Maximum.

8. Sélectionnez OK pour terminer la configuration de l’action. Les détails de l’action doivent ressembler à l’exemple suivant :

   

9. Sélectionnez le bouton et développez les options style dans le volet Bouton Format . Activez le bouton radio Texte sur Activé et étiquetez votre bouton Enter.

10. Dans les options Style, changez l'option Appliquer les paramètres à en Chargement.

    L’état de chargement est un état unique disponible pour les boutons de fonction de données que vous pouvez utiliser pour définir des options de style qui s’affichent pendant l’exécution de la fonction de données.

    

11. Développez le menu Texte et remplacez la valeur de texte du bouton par Submitting.

12. Développez le menu Icône .

    Par défaut, un bouton de fonction de données a un type d’icône Spinner pour l’état de chargement.

13. Ajustez le style d’icône avec les modifications suivantes :

    Paramètre	Valeur
    Remplissage	Changez la marge gauche à 20 px.
    Taille de l’icône	Remplacez la valeur automatique par défaut par 20.

14. Dans le volet Visualisations , sélectionnez l’icône Tableau pour insérer une nouvelle table.

15. Dans le volet Données , sélectionnez les colonnes suivantes à ajouter à votre table :

    • SalesLT.ProductModel > Name
    • SalesLT.ProductDescription > Description
    • SalesLT.ProductDescription > ModifiedDate

    

Modifications facultatives du rapport

Comme pour n’importe quel rapport Power BI, il existe de nombreuses façons de personnaliser l’apparence et d’améliorer les fonctionnalités de ce rapport. Tenez compte de certaines de ces options :

• Ajoutez des titres aux deux tableaux. Par exemple, sélectionnez un produit et unedescription de produit.
• Réglez le contrôleur de texte sur effacement automatique après avoir soumis une nouvelle description de produit. Pour ce faire, sélectionnez le bouton qui déclenche la fonction de données utilisateur. Dans le menu Action du >, définissez le Effacement automatique sur Activé.
• Désactiver l’autorefresh pour le rapport après avoir déclenché la fonction de données utilisateur. Dans ce scénario, il est utile d’actualiser les données et de voir la nouvelle description du produit apparaître dans le tableau. Dans d’autres scénarios, vous n’avez peut-être pas besoin ou souhaitez actualiser le rapport. Pour désactiver ce paramètre, sélectionnez le bouton qui déclenche la fonction de données utilisateur. Dans le menu Action du >, définissez le bouton bascule Actualiser le rapport après un résultat réussi sur Désactivé.

Exécutez votre flux de tâches translytique

Vous pouvez tester les fonctionnalités de votre flux de tâches translytics dans Power BI Desktop. Toutefois, si vous souhaitez voir l’expérience de l’utilisateur final la plus précise, publiez le rapport sur le service Power BI et testez-le sur le web.

Publier votre rapport

Vous avez créé votre rapport dans Power BI Desktop. Dans cette section, vous publiez le rapport afin que vos utilisateurs puissent interagir avec celui-ci dans le portail web.

1. Dans le menu de la barre d’outils Accueil , sélectionnez Publier.

2. Sélectionnez l’espace de travail Power BI dans lequel vous souhaitez publier ce rapport, puis sélectionnez Sélectionner.

3. Une fois votre rapport publié, sélectionnez le lien vers Ouvrir <REPORT_NAME.pbix> dans Power BI.

   Conseil / Astuce

   Lorsque vous ouvrez votre rapport dans le portail web Power BI, vous pouvez voir une erreur indiquant que la source de données manque d’informations d’identification et ne peut pas être accessible. Pour résoudre cette erreur, procédez comme suit :

   1. Ouvrez le modèle sémantique de votre rapport et accédez auxparamètres>.
   2. Développez le paramètre d’informations d’identification de la source de données si ce n’est pas déjà fait.
   3. Sélectionnez Modifier les informations d’identification.
   4. Choisissez votre méthode d’authentification dans le menu déroulant. Par exemple, Basic prend un nom d’utilisateur et un mot de passe, et OAuth2 active l’authentification unique avec votre compte actuel.
   5. Fournissez les informations requises, le cas échéant, puis sélectionnez Se connecter.

Vous disposez maintenant d’un flux de tâches translytique dans un rapport Power BI disponible dans le service Power BI.

Exécutez votre flux de tâches translytique

Dans cette section, vous interagissez avec votre rapport dans le portail web Power BI pour tester le flux de tâches translytics que vous avez créé.

Seuls les utilisateurs autorisés à déclencher des fonctions de données peuvent utiliser cette fonctionnalité. Tous les utilisateurs non autorisés reçoivent une réponse Quelque chose a mal tourné.

1. Ouvrez votre rapport dans Power BI.
2. Sélectionnez un produit dans la table de produits qui répertorie le nom et l’ID. Cette sélection transmet le contexte à l'outil de découpe de texte pour le produit que vous souhaitez mettre à jour. Vous voyez également que le tableau de description du produit filtre pour afficher toutes les descriptions actuelles du produit sélectionné.
3. Écrivez une nouvelle description de produit dans la zone de texte d’entrée.
4. Sélectionnez l’icône de flèche ou utilisez la touche Tab pour envoyer l’entrée. Une fois qu’un produit est sélectionné et qu’une description est fournie, vous voyez que le bouton bascule vers un état activé.
5. Sélectionnez le bouton pour exécuter la fonction de données utilisateur.

Si le flux de tâches translytical a fonctionné correctement, vous recevez un message indiquant que l’action sur votre rapport a été envoyée avec succès. La table de description du produit s’actualise pour afficher la nouvelle description.

Si quelque chose ne va pas avec le flux de tâche translytical, vous recevez un message indiquant que quelque chose s’est mal passé. Sélectionnez Afficher les détails pour obtenir plus d’informations sur la raison de l’échec. Voici quelques raisons courantes pour une exécution de fonction infructueuse :

• Validation des données : les valeurs d’entrée ne répondent pas aux règles de validation des données définies dans la fonction de données utilisateur.
• Erreur de délai d’expiration : une fonction ou un processus prend plus de temps que le temps autorisé.
• Configuration incorrecte : les erreurs de configuration des éléments de rapport, généralement le bouton, peuvent entraîner l’échec du flux de tâches ou des résultats inattendus du produit.
• Utilisateur non autorisé : l’utilisateur n’a pas les autorisations nécessaires pour déclencher la fonction de données.

Étapes suivantes

• Pour obtenir des idées de flux de tâches translyticaux que vous pouvez incorporer dans vos flux de travail, consultez des exemples de flux de tâches Translytical.
• Pour en savoir plus sur les options d’intégration des boutons de fonction de données dans les rapports Power BI, consultez Créer un bouton de fonction de données dans Power BI.