Obtenir des métriques de supervision de votre organisation avec l'API Python d'ArcGIS

Avec ce troisième tutoriel de notre série de l'été de prise en main de l'API Python d'ArcGIS, nous allons terminer les workflows d'administration en récupérant plusieurs données et métriques sur notre organisation que nous allons publier et à partir desquelles nous allons créer un tableau de bord. Pour rappel, nous avons vu durant les semaines précédentes comment administrer les utilisateurs et les groupes, et comment gérer les crédits, envoyer des notifications et planifier l'exécution d'un Notebook.

Le but de ce tutoriel est de récupérer plusieurs métriques sur notre organisation (historique d'utilisation, rapports sur les contenus, validation des métadonnées, nombre d'utilisateurs, etc) et de les afficher dans un Dashboard ArcGIS. Vous apprendrez également les bases de la publication de contenu sur votre portail, car nous publierons également les métriques sous forme de service de table.  

Notez que vous aurez pour cela besoin d'un compte possédant les privilèges administrateur dans votre organisation.  

 

Comme d'habitude, vous pouvez suivre le tutoriel ci-dessous pas à pas pour obtenir les explications des différentes étapes, et écrire le code par vous-même ou retrouver le code complet et commenté sur mon Github ou alors le récupérer via cet item ArcGIS. 

Vous pouvez exécuter ce Notebook directement dans ArcGIS Notebooks sur ArcGIS Online (disponible par défaut si votre administrateur vous a accordé les droits nécessaires), dans ArcGIS Enterprise (disponible avec le rôle serveur correspondant) ou en le téléchargeant et en l'ouvrant sur ArcGIS Pro (plus d'infos dans la doc). Vous pouvez également l'exécuter dans n'importe quel environnement d'exécution de votre choix, mais veillez dans ce cas à avoir installé les packages nécessaires.

1 - Import des bibliothèques et connexion au GIS

Nous commençons par importer les différentes bibliothèques nécessaires, puis par nous connecter au SIG.

La connexion est à adapter selon votre environnement et votre méthode d'authentification. Vous retrouverez toutes les méthodes de connexion possibles sur l'aide en ligne.
La cellule va peut-être vous renvoyer un message rouge pour vous prévenir que vous êtes connectés en tant qu'administrateur, et qu'il faut faire attention aux opérations que vous utilisez. Cela n'empêche pas votre code de s'exécuter correctement.

Si votre environnement n'est pas directement connecté à votre SIG, vous devrez lui passer vos informations d'authentification via la cellule suivante, que vous devez bien sûr mettre à jour avec vos propres informations :

2 - Récupération de la date du jour et du premier jour du mois

Dans ce tutoriel, nous allons obtenir des informations sur notre organisation au global, mais nous allons également chercher à avoir des données spécifiques pour le mois en cours. Pour cela, nous utiliserons la bibliothèque datetime. Cela nous permet d'obtenir la date du jour, la date du premier jour du mois, ainsi que la date du jour au format annee_mois_jour. Cette dernière nous servira pour nommer les items que nous allons créer et sauvegarder dans la suite du script.

3 - Nombre d'utilisateurs selon leur type de licence

Les premières métriques que nous allons récupérer concernent les utilisateurs de notre organisation.

 

3a - Recherche de tous les utilisateurs et calcul de leur nombre total

Nous allons commencer par utiliser la fonction search() de la classe UserManager de l'API, qui va nous renvoyer tous les utilisateurs de l'org dans une liste.

Il est ensuite très simple d'obtenir le nombre total d'utilisateurs, en utilisant la fonction len() sur notre liste d'utilisateurs.

3b - Calcul du nombre d'utilisateurs par type de licence (Viewer, Creator, GIS Professional) et du nombre d'utilisateurs actifs ce mois-ci

Nous aimerions maintenant avoir des informations plus précises sur ces utilisateurs, à savoir quel type de licence (Viewer, Creator, GIS Professional ou autre) est attribuée à combien d'utilisateurs, et combien d'utilisateurs ont été actifs dans le mois en cours. Pour cela, nous commencerons par initialiser les variables devant contenir le décompte à 0.
Nous itérons ensuite dans la liste des utilisateurs, et nous accédons à la propriété userLicenseTypeId pour savoir si l'utilisateur est un Viewer, un Creator, un GIS Professional (nous avons ici regroupé Basic, Standard et Advanced mais il est possible de les décompter séparément), ou autre. Nous incrémentons alors le décompte correspondant de 1.
Nous obtenons ensuite la date de dernière connexion de l'utilisateur grâce à sa propriété lastLogin. Celle-ci renvoie une valeur en milisecondes décomptées depuis le 1er janvier 1970 (c'est de l'Heure Unix). Nous utilisons une fois de plus la bibliothèque datetime pour convertir cette heure Unix en heure UTC, et la comparer au premier jour du mois que nous avons récupéré plus tôt. Si la date de dernière connexion de l'utilisateur est supérieure à la date du premier jour du mois, c'est que l'utilisateur a été actif ce mois-ci et que nous pouvons incrémenter le compte d'utilisateurs actifs de 1.

3c - Publication des données en tant que service de table hébergé

Ces données se suffisent si elles sont uniquement destinées à être lues dans ce Notebook au moment de son exécution. Cependant, je vais vous montrer comment les publier en tant que table hébergée. Cela nous permettra de les utiliser pour en faire un Dashboard.
Afin de publier les donnée, nous allons suivre 4 étapes :

• création d'un dataframe contenant les données ;
• transformation du dataframe en CSV
• ajout du CSV au contenu de notre portail ;
• publication du CSV en tant que service.

Création d'un dataframe contenant les données

Commençons par écrire les données sous forme de dataframe grâce à la bibliothèque pandas que nous avons déjà utilisée lors des précédents tutoriels de cette série. Pour cela, nous utilisons la fonction Dataframe(). En exécutant la cellule, vous pouvez voir à quoi ressemble ce dataframe.

Transformation du dataframe en CSV

Passons à la deuxième étape, où nous utilisons la fonction to_csv() afin de transformer le dataframe en CSV. Notez que nous déclarons dans une variable le nom du CSV, en y concaténant la date du jour récupérée au début du Notebook. Ainsi, si vous éxécutez le Notebook une fois par mois, vous n'aurez pas de conflit avec les données publiées les mois précédents.

Ajout du CSV au contenu du portail

Nous ajoutons ensuite ce CSV au contenu de notre portail grâce à la méthode add() de la classe ContentManager de l'API.

Si vous inspectez votre contenu, vous devriez voir le CSV apparaître :

Publication du CSV en tant que service

Enfin, ce CSV doit être publié en tant que service de table pour pouvoir être facilement être utilisé dans votre SIG. La méthode publish() de la classe Item permet justement de publier des services hébergés à partir d'un item source, ici notre CSV. 

Le service de table est maintenant publié dans votre contenu :

4 - Historique des actions des utilisateurs

Le module arcgis.gis.admin de l'API nous permet d'accéder à la méthode history(). Celle-ci retourne un fichier CSV contenant un historique d'action de tous les utilisateurs. Nous utilisons ensuite la fonction read_csv() de la bibliothèque pandas pour pouvoir manipuler ce CSV très dense et le rendre plus lisible. Nous pouvons par exemple filtre le type d'action pour ne pas prendre en compte les login, puis nous affichons les données sous forme de diagramme.

Comme tout à l'heure, nous allons publier les données en tant que service de table, en suivant les 4 mêmes étapes que tout à l'heure. Nous créons pour cela un dataframe qui ne contient que les données qui seront utiles pour afficher le diagramme dans un tableau de bord. Nous le transformons ensuite en CSV, que nous ajoutons à notre portail avant de le publier en tant que table.

5 - Rapport sur les contenus

5a - Création et lecture du rapport

La méthode report() permet d'obtenir divers rapport sur l'utilisation de votre organisation. Cela peut par exemple être sur les crédits, comme nous l'avons vu lors du tuto numéro 2, ou encore sur le contenu, les utilisateurs, l'utilisation des services et des items... Pour tester les différents types de rapports, il suffit de changer la valeur du paramètre report_type. Ici, nous allons générer un rapport sur les contenus. 

Un rapport administratif a été ajouté à vos contenus :

Nous allons maintenant lire le contenu de ce rapport dans un dataframe.

5b - Récupération des métriques

Ce rapport contient beaucoup de données intéressantes. Pour ce tutoriel, nous allons nous contenter de récupérer 4 métriques : le nombre d'items total, le nombre d'items créés pour le mois en cours, la taille de stockage totale des items et la taille de stockage des items créés durant le mois en cours.

• Il est très simple d'obtenir le nombre total d'items, en utilisant la fonction shape() du dataframe. Celle-ci nous renvoie un tuple des dimensions du dataframe, sous la forme (nombre de lignes, nombre de colonnes). shape([0]) nous renvoie ainsi uniquement le nombre de lignes, ce qui nous permet d'obtenir le nombre total d'enregistrements dans le dataframe, c'est-à-dire le nombre d'items dans notre organisation.
  
• Pour obtenir le nombre d'items pour le mois en cours, nous commençons par convertir la colonne 'Date Created' de notre dataframe en datetime avec la fontion to_datetime(). Il est ensuite possible de créer un nouveau dataframe qui filtre uniquement les items créés après la date du premier jour du mois. Enfin, nous réutilisons la fonction shape() pour obtenir le nombre d'items dans ce nouveau dataframe.
  
• Pour les tailles de stockage, il suffit d'additionner avec la fonction sum() les colonnes File Storage Size, d'une part du dataframe complet et d'autre part du dataframe filtré sur le mois en cours. Grâce à la fonction round(), nous arrondissons à 2 chiffres après la virgule.
  

Nous pouvons désormais imprimer toutes nos trouvailles : 

5c - Publication des données en tant que service de table hébergé

Comme lors des deux précédentes étapes, nous publions les données obtenues sous forme de service de table hébergé.

6 - Validation des métadonnées

6a - Recherche du contenu créé ce mois-ci

La méthode search() appliquée à la classe ContentManager retourne le contenu de notre organisation sous la forme d'une liste. A l'intérieur de celle-ci, nous passons en argument une query qui nous permet de récupérer uniquement le contenu ayant été créé entre le premier jour du mois et aujourd'hui.

Nous allons maintenant itérer parmi tous les items de cette liste un à un, pour vérifier si les métadonnées ont bien été complétées.

 

6b - Vérification de la complétion des métadonnées

Les items possèdent un certain nombre de propriétés relatives à leurs métadonnées (titre, description, miniature, tags, ...), que nous pouvons requêter pour savoir si elles ont été complétées ou non. La liste complète des propriétés accessibles pour les items est disponible dans la documentation de l'API REST. Ci-dessous, grâce à la fonction len() nous récupérons le nombre total d'items renvoyés par la fonction search() précedemment. Puis, pour chaque item, nous vérifions une à une chacune des métadonnées. Si toutes les métadonnées sont complètes, nous incrémentons le décompte de métadonnées complètes de 1. 

Finalement, il est assez simple d'obtenir le pourcentage d'items créés ce mois-ci pour lequel les métadonnées sont complétées, en comparant le nombre d'items pour lequel les métadonnées sont complète au nombre total d'items. 

Imprimons le résultat, mais je vous préviens, il n'est en général pas glorieux... (à moins que vous ne travailliez avec des cracks des métadonnées, mais ce n'est a priori pas mon cas 👀)

 

6c - Publication des données en tant que service de table hébergé

Pour la dernière fois aujourd'hui, nous publions le résultat sur notre portail. 

7 - Affichage dans un Dashboard

Avec ArcGIS Dashboards, vous pouvez utiliser tous les services de table que nous avons publiés précédemments pour créer facilement un tableau de bord compilant toutes les métriques que nous avons obtenues. Voici par exemple celui que j'ai réalisé pour mon organisation :

Cependant, il existe plusieurs manières d'automatiser ce processus :

• Premièrement, en utilisant le module arcgis.apps.dashboard pour créer de zéro un tout nouveau Dashboard.
• La seconde option est de créer un Dashboard contenant déjà tous les indicateurs et qui servira de modèle. Vous pouvez ensuite mettre à jour les données contenues dans le Dashboard modèle avec les résultats de votre script, en mettant à jour les services publiés.

La deuxième méthode demandant plus de préparation, nous allons nous contenter de la première pour aujourd'hui. Notez cependant que l'API n'automatise pour l'instant que les Dashboards classiques, qui sont désormais dépréciés. Certaines fonctionnalités ne fonctionnant plus que partiellement, nous allons simplement afficher nos résultats sous forme de texte sans utiliser de diagrammes. Si vous souhaitez plutôt passer par la seconde méthode, je vous renvoie vers le tutoriel 6 où nous apprenons à mettre à jour des données du portail.

 

7a - Import des éléments du Dashboard

Commençons par importer tous les modules spécifiques à la création d'un Dashboard via l'API.

7b - Entête (Header)

Le Header est assez simple a construire, et tous ses paramètres sont facultatifs. Ici, nous renseignons un titre, un sous-titre, une taille ainsi qu'un logo. Nous faisons en sorte que le nom du portail analysé soit affiché dans le titre en y accédant grâce à la propriété properties du GIS. Nous ajoutons aussi le nom du mois en toutes lettres dans le sous-titre, ce qui nous demande un petit effort de traduction. 

7c - Création des indicateurs

Pour les indicateurs, nous allons utiliser la classe RichText qui nous permet d'ajouter du texte au tableau de bord, en accédant à toutes les variables calculées précedemment dans le Notebook. Notez que le texte prend en charge le formatage HTML.

7d - Création et sauvegarde du Dashboard

La dernière étape est de créer une instance de Dashboard. Nous pouvons paramétrer son entête en lui passant le header que nous avons construit en premier, puis choisir le thème (ici, sombre). Ensuite, nous ajoutons les lignes et les colonnes qui contiendront chacun des indicateurs que nous avons créés. Enfin, nous sauvegardons le dashboard qui va s'ajouter en tant que nouvel item à notre portail.

Voici le résultat que vous devriez obtenir, avec vos propres indicateurs :

 

Pour aller un peu plus loin... 

Si vous utilisez ArcGIS Notebooks, sachez qu'il est possible de créer une tâche pour planifier l'exécution de ce script de manière très facile. Cela vous permet par exemple d'obtenir automatiquement à la fin de chaque mois un nouveau Dashboard contenant toutes les métriques, sans avoir à aller exécuter le Notebook par vous-même. Nous avions vu ensemble les très courtes étapes pour mettre cela en place à la fin du tutoriel de la semaine dernière, que je vous laisse retourner consulter pour faire de même avec ce Notebook si vous le souhaitez.

C'est terminé pour cette semaine ! La semaine prochaine, nous nous retrouverons pour passer à la deuxième grande famille de workflows réalisables avec l'API Python d'ArcGIS : la gestion du contenu. Nous allons apprendre à créer une carte, à l'alimenter avec des couches, à la publier sur notre portail et à choisir son niveau de partage.