Aller au contenu principal
Nous avons lancé notre nouvelle base de connaissances ! Lire l'annonce →

Traitement des données SoSafe dans PowerBI via Power Query M

Mise à jour

Introduction

Les clients SoSafe peuvent récupérer des données analytiques/brutes directement via l'SoSafe API, qui peut également être utilisée avec PowerBI.

Ce guide explique comment utiliser les flux de données Gen 2 de Microsoft Fabric pour récupérer et afficher des données dans PowerBI, avec des exemples basés sur les informations de la version navigateur . Il montre comment configurer des requêtes pour une visualisation efficace des données et un stockage futur à l'aide d'un modèle fourni.

Modèle PowerBI SoSafe

De quoi s'agit-il ?

Le téléchargement est disponible en bas de cet article.

SoSafe a créé un modèle qui peut être facilement importé dans PowerBI pour récupérer et visualiser les données de la SoSafe API. Ce modèle inclut des fonctionnalités de base permettant de récupérer des données depuis l'API, de les traiter et de créer des structures de type Table.

Diagramme de flux de données Power Query montrant les paramètres APIKey, KeyID et SoSafeHost alimentant les fonctions performGetRequest et convertToTable, qui produisent les tables Users, Campaigns et CampaignAnalytics.

Le modèle récupère uniquement les données dans un flux de données Gen 2 et ne prend pas en compte leur utilisation ultérieure dans des rapports PowerBI ou des espaces de stockage de données.

Utilisation du modèle

  1. Chargez-le directement dans PowerBI en créant un nouveau flux de données et en utilisant le fichier fourni ci-dessus comme modèle. De plus amples informations sur la procédure à suivre dans PowerBI sont disponibles ici et ici.

  2. Ajoutez la clé API et l'identifiant de clé fournis via le SoSafe Manager dans les deux paramètres proposés par le modèle : APIKey et KeyID. Si vous n'avez pas encore obtenu ces valeurs, consultez ce guide.

    Panneau de paramètres Power Query pour la saisie de la valeur de la clé API, avec une info-bulle indiquant qu'elle est fournie par le SoSafe Manager. En dessous, une flèche pointe vers le champ de valeur actuelle, intitulé Valor atual, à côté du bouton Gerir parametro.

  3. Une fois les deux valeurs ajoutées, vous pouvez cliquer sur les tables correspondantes dans la partie droite du flux de données pour les charger une par une et visualiser les données :

Flux de données Power Query avec une info-bulle sur la table Campaigns décrivant les informations et analyses de campagne. En dessous, le script convertToTable et un aperçu de table avec des colonnes pour id, name, description, status, created et modulesplit.

  1. Terminé ! Les données sont disponibles pour être visualisées et traitées !

Modification des requêtes de base

Le modèle inclut trois tables pour trois types de données fournis par la SoSafe API :

Ces endpoints contiennent cependant différents types de filtres de données qui peuvent être modifiés pour obtenir des résultats différents de l'API. En prenant la table Users comme exemple, nous pouvons modifier la requête.

  1. Faites un clic droit sur la carte de la table Users et commencez à modifier le script.

  2. En vous basant sur la documentation disponible dans la spécification SoSafe Open API, ajoutez les paramètres correspondants comme indiqué ci-dessous et enregistrez le script.

    Script Power Query pour la table Users, avec une annotation pointant vers l'enregistrement params où un paramètre limit est ajouté à l'appel performGetRequest. En dessous, convertToTable définit les champs firstname, lastname, email et userGroup.

  3. Terminé !

Ajout de nouvelles requêtes

L'ajout d'une nouvelle requête/table est également assez simple ! Avant de créer vos propres requêtes, n'oubliez pas de consulter la spécification SoSafe Open API pour comprendre ce qu'il est possible de récupérer depuis l'API.

  1. Créez une nouvelle requête vide et ouvrez l'éditeur de script.
  2. Dans le bloc let, utilisez la fonction performGetRequest pour récupérer des données JSON.
  3. Toujours dans le bloc let, utilisez le résultat de performGetRequest pour récupérer la liste des enregistrements et transmettez-la comme argument à la fonction convertToTable pour convertir les données JSON en table Power Query.

  4. Terminé ! Vous pouvez désormais voir votre nouvelle requête aux côtés de toutes les autres !

Fonctions personnalisées

Le modèle fournit deux fonctions personnalisées qui peuvent être utilisées tout au long du pipeline pour vous faciliter la tâche.

performGetRequest

Cette fonction appelle directement la SoSafe API et récupère les données au format JSON (des exemples de réponses sont disponibles dans la spécification SoSafe Open API). Elle gère également l'authentification automatiquement, en fonction des identifiants fournis à la première étape, et ajoute Accept et Content-Type comme en-têtes par défaut.

De plus, performGetRequest prend également en charge la récupération des données par blocs, en utilisant plusieurs requêtes pour récupérer l'intégralité du jeu de données en plusieurs parties. Cela améliore les performances et offre plus de flexibilité et de contrôle selon vos besoins. Par exemple, si chunkBy et chunkSize sont tous deux transmis avec les valeurs d'exemple id et 5 respectivement, et qu'il y a 15 valeurs dans le paramètre de requête id, cette fonction effectuera 3 requêtes et retournera un tableau de 3 éléments contenant chaque réponse.

Cette fonction prend deux arguments :

  • path (text) : Le chemin de la requête GET, par exemple `/v1/users`
  • options (nullable record) : Les options à transmettre à cette requête, qui incluent :
    • headers (record) : Un enregistrement clé/valeur de tous les en-têtes à transmettre, à l'exclusion des en-têtes par défaut
    • params (record) : Un enregistrement clé/valeur des paramètres à ajouter à cette requête. Accepte des valeurs de type text, number et list
    • chunkBy (text) : Le champ texte selon lequel diviser les valeurs en blocs ; à fournir conjointement avec chunkSize et uniquement si le paramètre à diviser est présent dans params
    • chunkSize (number) : Le nombre d'enregistrements à demander à la fois via l'API ; à fournir conjointement avec chunkBy

Exemple de requête avec des requêtes par blocs :

responses = performGetRequest(
  "/v1/analytics/elearning",
  [
    params = [ campaignId = Table.Column(Campaigns, "id"),
    chunkBy = "campaignId",
    chunkSize = 5
  ]
),

convertToTable

Il s'agit d'une fonction simple qui convertit une liste donnée d'enregistrements en table Power Query. Dans le contexte de la SoSafe API, cela signifie que les données JSON d'une réponse récupérée avec performGetRequest peuvent être utilisées comme argument ici. De plus, elle accepte un argument pour déterminer la clé primaire du jeu de données à utiliser dans la table, ainsi que des clés étrangères facultatives. Les arguments sont les suivants :

  • records (list de records) : La liste des enregistrements à convertir en table
  • types (list de lists) : Une liste avec le nom des champs et leurs types Power Query respectifs. Elle convertit les types de la réponse en types de table appropriés. Par exemple :
    • {
  { "id", Int64.Type },
  { "name", Text.Type }
}
  • primaryKey (text) : Le nom du champ contenant la clé primaire de cette table
  • foreignKey (nullable list) : Une liste facultative pouvant être transmise avec tous les noms des champs devant être des clés étrangères

Exemple de conversion avec des requêtes par blocs :

table = convertToTable(
  // convert all responses to a list of records containing the correct data
  List.Accumulate(
    responses,
    {},
    (acc, current) => List.Combine({ acc, current[data] })
  ),
  // assign types
  {
    { "customerId", Int64.Type },
    { "campaignId", Int64.Type },
    { "campaignName", Text.Type },
    { "firstname", Text.Type },
    { "lastname", Text.Type },
    { "email", Text.Type },
    { "language", Text.Type },
    { "userGroup", Text.Type },
    { "userCreated", Date.Type },
    { "registrationDate", Date.Type },
    { "isActive", Logical.Type },
    { "progress", Percentage.Type },
    { "achievedLevel", Percentage.Type },
    { "allPassed", Text.Type },
    { "passedModules", Int64.Type },
    { "overdueMandatoryModules", Int64.Type },
    { "passedMandatoryModules", Int64.Type },
    { "passedOptionalModules", Int64.Type },
    { "recentlyFinishedModule", Date.Type }
  },
  // assign primary key
  "email"
)

Cette traduction est automatisée. En cas de doute, consultez la version anglaise.

Articles associés