L’API Piano Analytics permet très facilement d’extraire une importante quantité d’informations stockées dans la solution.

On peut vouloir importer les données Piano Analytics dans Excel pour réaliser une analyse ponctuelle, réaliser des tableaux de bord ou encore nourrir un reporting Power Point.

Dans un autre contexte, on peut également utiliser Power Bi pour créer des rapports décisionnels avec ses données analytics et toute autre source de données.

Nous allons voir à travers cet article que la solution est la même dans les 2 cas : Power Query.

En effet cet outil est disponible aussi bien dans Excel que dans Power Bi, et permet (entre autres) le requêtage de toute API externe pour importer les données et les remanipuler dans exploitation via un langage de programmation (le mashup).

Lancer Power Query dans Power BI ou dans Excel

Les présentations étant maintenant faites, rentrons dans le vif du sujet ! Pour suivre ce guide, vous pouvez utiliser de manière indifférente Power Bi ou Excel

Dans power Bi, Power Query est disponible dans l’onglet Accueil > Transformer les données :

Dans Excel, l’outil est disponible dans l’onglet Données > Obtenir des données > Lancer l’éditeur Power Query :

Création de la clé API

Pour requêter vos données Piano Analytics depuis l’extérieur de l’interface, vous allez devoir obtenir une clé API. Cette clé est liée à votre compte Piano Analytics, vous n’aurez donc pas la même que votre collègue. Vous aurez également accès au même périmètre que celui disponible dans votre interface (même liste de niveaux 1).

Une fois connecté à votre compte, allez dans votre profil puis dans l’onglet Api Keys.

 Générez une nouvelle clé et conservez bien l’Access key et surtout la secret key, qui ne vous sera plus donnée par la suite.

Récupération de l’appel API

A partir de la documentation API, il est tout à fait possible de créer votre appel de zéro. Il est cependant plus confortable de partir de l’outil Data Query, qui sera capable de vous restituer un appel API clé en main.

Rendez-vous donc dans l’interface Data Query, où je vous invite à créer l’appel de votre choix, peu importe la période (nous verrons cette question plus tard). Dans mon cas je vais simplement prendre le nombre de pages vues et de visites pour mes pages avec aux moins 10 pages vues :

Pour récupérer l’appel API correspondant, ouvrez l’onglet de partage et sélectionnez « Copier l’URL API (GET) » (nous reviendrons sur la notion d’API Post dans un autre article).

L’url est maintenant présente dans votre presse papier. Si vous la coller dans un bloc-notes, vous verrez que celle-ci est encodée. Pour y voir plus clair, je vous conseille de la désencoder via l’outil de votre choix. De mon côté je vais utiliser l’outil du site Meyerweb. On obtient donc ce résultat :

https://api.atinternet.io/v3/data/getData?param={"columns":["page","m_visits","m_page_loads"],"sort":["-m_visits"],"space":{"s":[592201]},"period":{"p1":[{"type":"D","start":"2022-04-12","end":"2022-04-18"}]},"max-results":50,"page-num":1,"options":{}}

Cet article n’est pas là pour apprendre à décortiquer la structure de cet appel (pour rappel, la documentation est ici), retenez simplement que le paramètre « param » de l’url est au format Json et est composé de plusieurs propriétés (columns, sort, period, max-results…).

Test de l’API Piano Analytics

On peut maintenant tester si notre clé API fonctionne ! Pour cela collez l’url dans votre navigateur. Un popup va s’afficher et vous demander un nom d’utilisateur et un mot de passe. Mettez votre Access key en tant que Nom d’utilisateur et la secret Key en mot de passe :

Vous obtiendrez normalement un json, que vous pourrez rendre plus lisible avec une petite extension chrome du type Json Viewer. On retrouve bien dans la propriété « rows » nos pages avec leurs données :

Créer son appel Power Query

Ouvrez Power Query et créez une nouvelle source de données avec le type « web », qui correspond au requêtage des API et des pages web :

Placez votre requête API dans le champ et sélectionnez le mode avancé :

Nous allons maintenant gérer l’authentification de l’API, qui se fait via le header de la requête.

On ajoute pour cela un paramètre « x-api-key », avec pour valeur la concaténation de votre access key et de votre secret key séparées d’un « _ » : accessKey_secretKey

Power Query vous demandera alors le type de connexion que vous souhaitez mettre en place. Comme le système d’authentification est déjà présent dans l’appel en lui-même via x-api-key, on peut rester sur le mode anonyme :

Power Query vous affiche maintenant les données qu’il a récupérées, et nous allons tâcher de les déployer afin de pouvoir les utiliser. Procédez comme ceci :

• Cliquez sur la valeur « Record » à gauche de « DataFeed » (Non nécéssaire pour Power Bi)
• Cliquez sur la valeur « List » associée à « Rows »
• Dans l’onglet « Transformer », sélectionnez « convertir vers la table » puis « OK » dans la popin « vers la table » qui s’affiche
• A droite de l’entête de colonne « Column1 » cliquez sur le petit icône avec les 2 flèches qui s’opposent et sélectionnez les colonnes que vous souhaitez extraire.

Vous avez maintenant vos données qui s’affichent dans Power Query. Vous pouvez renommer les colonnes qui ont toutes le préfixe « columns1 », pour plus de clarté. Vous pouvez maintenant cliquer sur « Fermer et charger » (« fermer et appliquer » pour Power Bi) pour que les données soient chargées dans le document :

Libre à vous de créer maintenant autant d’appels que vous le souhaitez en suivant cette méthode !

Dynamiser les périodes d’appel de vos API

Vous l’aurez peut-être remarqué mais la période donnée par Data Query dans l’API est toujours une période dite « fixe », c’est-à-dire avec une date de début et une date de fin, et cela même si vous sélectionnez une période relative (hier, la semaine dernière, le mois en cours) dans l’interface :

period »:{« p1 »:[{« type »:"D","start":"2022-04-12","end":"2022-04-18"}]}

Pour changer la période d’appel, il faudrait donc théoriquement éditer notre requête dans Power Query et changer manuellement la date, ce qui n’est pas très pratique (notamment si vous avez des dizaines d’appels) :

Fort heureusement la documentation nous donne les outils pour récréer une période relative dans l’appel API.

Si on reprend notre json de base gérant la date « period »:{« p1 »:[{« type »: »D », »start »: »2022-04-12″, »end »: »2022-04-18″}]} » voici ce que cela deviendrait pour des périodes relatives :

Comme vous le voyez, le patern se répète et il n’y a en réalité que 3 éléments à changer :

• Granularity, qui indique la granularité de la période (Days, Week, Month, Quarter, Year)
• StartOffset, qui indique la période à laquelle il faut faire remonter l’appel. 0 correspond à la période en cours, -1 la période précédente, -2 la période encore précédente…
• EndOffset, qui indique la période à laquelle il faut arrêter l’appel. Le format est le même que pour StartOffset

Ainsi, « granularity »: « W », »startOffset »: -2, »endOffset »: -1 » veut dire « sélectionne moi les 2 dernières semaines par rapport à la date actuelle ». Ou encore « granularity »: « D », »startOffset »: -366, »endOffset »: -1 » veut dire « sélectionne moi les 365 derniers jours par rapport à la date actuelle ».

Vous pouvez ainsi imaginer une multitude de combinaisons pour vos appels en mixant ces 3 paramètres.

Si on souhaite maintenant modifier la période de départ de notre appel pour la rendre dynamique par rapport à la date actuelle, par exemple en sélectionnant la semaine précédente :

• Ouvrez Power Query et sélectionnez la requête à modifier
• Dans « étapes appliquées », double cliquez sur « Source » pour afficher à nouveau le champ contenant l’appel API
• Remplacez la propriété « period » avec la période relative.

Validez vos changements en cliquant sur « OK » :

Votre appel s’adaptera donc bien maintenant à la date à laquelle vous actualisez votre document !

Bonus 1 : modifiez la période de tous vos appels API en une seule fois

Comme vous l’aurez compris, pour modifier la période de vos appels API, il faudra alors le faire manuellement (pour passer de la période « semaine -1 » à « semaine -2 » par exemple). Si vous devez régulièrement changer les périodes d’appels, le travail peut vite devenir fastidieux.

Une solution pour contourner ce problème est de créer une valeur unique, qui sera automatiquement prise en compte comme période dans tous les appels.

Nous allons utiliser pour cela les paramètres power query :

• Allez dans accueil > Gérer les paramètres > Nouveau Paramètre
• Nommez-la avec le nom de votre choix (« periode_analyse » dans mon cas) 
• placez le json de la période souhaitée dans le champ « valeur actuelle ». dans mon cas je souhaite le mois précédent, donc {« p1 »:[{« type »: « R », »granularity »: « M », »startOffset »: –1, »endOffset »: -1}]}

Maintenant que notre paramètre existe, nous allons remplacer la période présente dans les appels par notre paramètre. Pour cela :

• Sélectionnez la requête à modifier et placez-vous sur l’étape « Source »
• Dépliez via la flèche le code m correspondant à cette étape et repérez la zone où est écrite la période
• Supprimez la période présente et concaténez le début de l’appel API avec notre paramètre période_analyse, puis concaténez à nouveau avec la fin de l’API via le format début_requete’&période_analyse&’fin_requete (cf. capture)

Effectuez cette opération sur l’ensemble des appels à dynamiser. Et voilà ! Vous pouvez maintenant changer à loisir votre période d’analyse, l’ensemble des appels seront mis à jour. A noter que vous pouvez effectuer exactement la même démarche pour une éventuelle période de comparaison.

Bonus 2 : Dynamiser la période à partir de dates fixes

Le format relatif des dates est très pratique, mais très spécifique à Piano Analytics. Si d’autres sources que vos données analytics sont appelées, vous aurez potentiellement besoin d’utiliser le même format de date partout afin d’avoir la même période dans toutes vos tables.

L’idéal serait donc de pouvoir repasser dans un format de dates plus conventionnelles (AAAA-MM-JJ par exemple) mais tout en gardant le système de dynamisation.

C’est ce que nous allons faire ici ensemble, via l’écriture d’un peu de mashup ! Pour rappel, Power Query n’est « qu’un » générateur de code en langage m (ou aussi appelé Mashup), dont vous pouvez voir l’appercu dans Power Query > Accueil > Editeur avancé. Si on en comprend la nomenclature il est possible d’écrire son propre code sans passer par l’interface.

Notre objectif va être simple : Recréer dynamiquement au format AAAA-MM-JJ les dates de début et de fin du mois précédent afin de pouvoir les placer dans mes appels (à noter que la même logique pourra être appliquée pour les autres types de périodes). Si je suis par exemple le 3 mai 2022, le code devra alors me donner 2022-04-01 et 2022-04-30.

Construction de la requête

La première étape va être pour nous de créer une requête vite. Pour cela allez dans Accueil > Nouvelle Source > Requête vide.

Allez maintenant dans Accueil > Editeur avancé pour afficher le code. Vous devriez avoir quelque chose comme ceci :

La première étape pour nous va être de récupérer la date du jour, afin d’en déduire le mois précédent. Ainsi, à chaque mise à jour du fichier, la date du jour sera automatiquement updatée. Nous allons pouvoir utiliser la fonction DateTime.LocalNow() pour cela. On va également renommer l’étape en « today » afin que cela soit plus explicite.

Vous devriez avoir un code comme ceci, et obtenir la date du jour dans l’éditeur :

On ajoute maintenant une étape, permettant d’enlever 1 mois à la date du jour via la méthode Date.AddMonths et en y plaçant la valeur -1. Nous sommes maintenant dans le bon mois :

Notre objectif va maintenant être de construire les dates de début et de fin, à partir de la variable lastMonth en extrayant l’année et le mois puis en créant le jour. Commençons par la date de début.

Pour extraire l’année d’une date, on va pouvoir utiliser la méthode Date.year. On va également convertir la valeur au format string via la méthode Number.toText car nous en aurons besoin plus tard :

On va appliquer la même logique pour récupérer le mois, avec la méthode date.Month :

On va ici avoir une difficulté qui n’était pas présente sur l’année : on ne souhaite pas récupérer « 3 » comme valeur mais « 03 », sinon la date ne sera pas au bon format (AAAA-MM-JJ). Pour corriger cela il suffirait de concaténer la valeur récupérée avec « 0 » afin d’obtenir le bon format :

startDateMonth = « 0 »& Number.ToText(Date.Month(LastMonth))

Cependant cette méthode ne fonctionnera pas pour les mois contenant 2 chiffres (octobre, novembre, décembre) puisque cela va nous générer des valeurs du type « 010 ».

Pour prendre en compte des mois particuliers, on va demander à tronquer la valeur pour ne conserver que les 2 derniers caractères, via la méthode text.end :

startDateMonth = Text.End(« 0″& Number.ToText(Date.Month(LastMonth)),2)

Finalement la valeur du jour sera toujours la même : « 01 » pas besoin de code spécifique pour cela !

Il ne reste plus qu’à concaténer l’ensemble dans une variable :

startDate = startDateYear& »-« &startDateMonth& »-01″

Construire la date de fin

Récupérer l’année et le mois de la date de fin ne comporte aucune nouveauté, vous pourrez donc récupérer les valeurs de la même manière que la date de début.

Le jour va en revanche nous poser un peu plus de problème. En effet cette valeur doit représenter le dernier jour du mois, il peut donc être égal à 28,29,30 ou 31.

Dans un premier temps nous appliquons la méthode Date.EndOfMonth pour obtenir la date du dernier jour du mois :

    endDateMonth = Date.EndOfMonth(LastMonth)

On extrait maintenant le jour de cette date via la méthode date.Day et on transforme la valeur en texte :

 endDateMonth = Number.ToText(Date.Day(Date.EndOfMonth(LastMonth)))

Il n’y a plus qu’à concaténer l’ensemble des valeurs pour créer la date de fin (je vais le faire ici en un seul bloc :

endDate = Number.ToText(Date.Year(LastMonth))& »-« &Text.End(« 0″ & Number.ToText(Date.Month(LastMonth)),2)& »-« &Number.ToText(Date.Day(Date.EndOfMonth(LastMonth)))

Retourner les 2 valeurs sous la forme d’une liste et les injecter dans nos appels

Il ne reste plus qu’à retourner les 2 dates sous la forme d’une liste pour en finir avec notre code :

Nous allons maintenant pourvoir intjecter les 2 dates crées dans toutes les sources qui nous intéressent et pas uniquement l’API Piano Analytics.

Pour cela, on édite l’appel en question et on va placer chaque item de notre liste au bon emplacement via la sélection {0} et {1} :

Conclusion

Nous avons vu à travers cet article comment effectuer nos appels API Piano Analytics et comment dynamiser les dates d’appels. Ayez bien en tête que n’importe quelle période est dynamisable et si le cas dont vous aviez besoin n’a pas été vu dans cet article, je vous renvoie vers l’ensemble des méthodes M autour des dates.