Utiliser l'API Python d'ArcGIS pour administrer des utilisateurs et des groupes

Dans ce premier tutoriel de notre série de l'été consacrée à la prise en main de l'API Python d'ArcGIS, je vous propose de commencer par entamer le premier volet de capacités de l'API : l'organisation et l'administration du SIG. Cela comprend la gestion des utilisateurs, des groupes, des items et des serveurs. 

Dans cet article, nous allons nous concentrer sur l'automatisation de l'administration d'utilisateurs et de groupes et de leur contenu, en apprenant à ajouter et supprimer des utilisateurs et transférer le contenu d'un utilisateur supprimé, créer des groupes, ajouter des utilisateurs dans des groupes etc. 

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

 

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.

0 - Un mot sur l'environnement de développement

Quand il s'agit d'utiliser l'API Python d'ArcGIS, mon environnement de développement de prédilection est généralement ArcGIS Notebooks. Basé sur Jupyter Notebook, il me permet une connexion transparente à mon portail SIG, à ses données, ses utilisateurs, etc. et et il simplifie mon processus d'écriture via des extraits de code et des actions interactives. Il est accessible par défaut dans ArcGIS Online si vous avez les droits nécessaires (c'est l'interface que vous verrez ici), dans ArcGIS Pro, et via un rôle serveur additionnel dans ArcGIS Enterprise.C'est l'interface que vous verrez dans les captures d'écran de ces tutoriels.

Bien sûr, si vous avez déjà un IDE favori (je pense par exemple aux aficionados de VSCode), vous pouvez le conserver sans problème. Dans ce cas, veillez simplement à installer l'API et ses dépendances dans votre environnement.

J'ouvre donc un nouveau Notebook, en choisissant le runtime Standard qui sera suffisant pour les capacités auxquelles nous allons faire appel aujourd'hui.

1 -  Connexion au GIS

La première étape est de se connecter à votre portail SIG, nous la répèterons systématiquement au début de chaque tutoriel. Il faut pour cela commencer à importer la classe GIS du module gis, qui représente notre organisation.

Il va ensuite falloir vous authentifier. Pour cela, plusieurs options sont possibles :

 

Si vous utilisez un ArcGIS Notebook dans ArcGIS Online ou ArcGIS Enterprise, vous pouvez vous connecter de manière très simple avec la cellule déjà écrite à l'ouverture de votre Notebook  :

Cela vous authentifie directement avec le profil de l'utilisateur avec lequel vous êtes actuellement connectés. 

 

Si écrivez votre script depuis un Notebook ArcGIS Pro et que vous êtes bien connectés à un portail, vous pouvez également utiliser cette méthode, ou bien opter pour :

Si vous travaillez dans un environnement qui n'est pas directement connecté à votre portail, il va falloir passer vos informations d'authentifications et l'url du portail auquel vous souhaitez vous connecter en paramètre de la fonction GIS : 

Cela s'appelle une connexion depuis un compte intégré, lorsque vous utilisez le magasin d'identité d'ArcGIS. Notez que si votre environnement d'exécution est interactif, vous n'êtes pas obligés de rentrer directement votre mot de passe dans le code. Dans ce cas, l'exécution sera suspendue et il vous sera demandé de le compléter interactivement au moment de l'exécution de la cellule contenant ce code. L'exécution reprendra après que vous ayez indiqué des identifiants valides.

D'autres méthodes d'authentification sont disponibles, notamment pour ArcGIS Enterprise si vous utilisez d'autres magasins d'identité (LDAP, Active Directory, etc.). Nous ne les verrons pas en détail dans cet article, mais vous pouvez obtenir plus d'information sur la page de l'aide en ligne dédiée aux méthodes d'authentification avec l'API Python.

2 - Ajouter des utilisateurs à votre portail depuis un fichier CSV

2a - Lecture du CSV en tant que dataframe pandas

Les DataFrames pandas permettent de gérer les données tabulaires de manière très efficace dans Python. Nous allons donc transformer nos données csv en pandas dataframe. Pour cela, il faut importer la bibliothèque tierce pandas puis utiliser sa fonction read_csv() :

Notez que nous passons en paramètre de la fonction le chemin d'accès vers le CSV. Pour la démo, j'en héberge un sur Github que vous pouvez utiliser si vous le souhaitez.Vous trouverez le lien complet vers ce CSV à cet url, veillez à le remplacer dans le code. Vous pouvez également renseigner le chemin d'accès vers votre propre CSV. 

Si vous utilisez ArcGIS Notebooks, notez que l'environnement d'exécution n'a pas accès à vos fichiers locaux enregistrés sur votre machine. Vous pouvez ajouter le CSV dans l'environnement du Notebook en suivant les étapes montrées ci-dessous :

Vous verrez aussi que si vous utilisez un environnement interactif, vous obtenez une visualisation du dataframe, ce qui vous permet de voir si les données sont correctement importées :

2b - Itérer dans la liste des utilisateurs et les ajouter au portail

Pour ajouter les utilisateurs au portail, nous allons utiliser la fonction create() de la classe UserManager de l'API. 

Comprendre la fonction gis.users.create() :

Voici la description de la fonction dans la doc :

create(username, password, firstname, lastname, email, role, description=None, provider='arcgis', idp_username=None, level=2, thumbnail=None, user_type=None, credits=- 1, groups=None, email_text=None)

Nous allons renseigner les paramètres utiles. Pour savoir à quoi sert quel paramètre, vous pouvez consulter la documentation de la classe UserManager, ou bien exécuter la cellule ci-dessous :

Pour chaque fonction de l'API Python d'ArcGIS, vous pouvez accéder à la doc sans sortir de votre IDE en ajoutant un ? à la fin du nom complet de la fonction.

La fonction vous demande notamment de renseigner le rôle et le type d'utilisateur du nouvel utilisateur que vous souhaitez inscrire dans votre organisation. Si besoin, vous pouvez savoir quels rôles et types d'utilisateurs sont disponibles au sein de votre organisation en exécutant les deux cellules ci-dessous :

Utiliser la fonction gis.users.create() : 

Nous allons parcourir chacun des utilisateurs du dataframe (le tableau importé juste avant) avec une boucle d'itération for. Pour chaque itération, nous allons utiliser la fonction create() en allant récupérer les valeurs du tableau pour renseigner les paramètres de la fonction.
df["element_entete"][i] permet d'aller récupérer l'information qui se trouve dans la colonne "element_entete" (par exemple dans notre dataframe : "Prenom") et dans la ligne i. A la première itération de la boucle, i aura une valeur de 0, puis de 1 à la deuxième itération, etc. jusqu'à avoir parcouru la totalité des lignes du tableau :

3 - Supprimer un utilisateur et transférer son contenu

3a - Accéder à l'utilisateur à supprimer

Pour accéder à un utilisateur, nous allons utiliser la fonction get() de la classe UserManager de l'API :

3b - Supprimer l'utilisateur et réassigner son contenu

Nous allons pour cela utiliser la fonction delete de la classe User :

La fonction delete nous permet de tirer parti du paramètre reassign_to, qui nous permet de transférer le contenu de l'utilisateur supprimé à un autre utilisateur. Je vais donc accéder à un autre utilisateur pour lui transférer le contenu.
J'aurais également pu transférer le contenu à mon propre profil en indiquant gis.users.me. 

Notez que si vous souhaitez réassigner un contenu sans supprimer un utilisateur, vous pouvez utiliser la fonction reassign_to de la classe Item.

3bis - Supprimer par lots tous les utilisateurs inactifs de votre portail 

Maintenant que nous savons supprimer des utilisateurs, nous pouvons nous en servir par exemple pour supprimer tous les utilisateurs de type viewer inactifs de notre portail.

3bis a - Rechercher tous les utilisateurs du portail

Pour rechercher les viewers, nous allons utiliser la fonction search() de la classe UserManager de l'API :

3bis b - Création d'une liste de viewers à conserver

Si vous savez que certains utilisateurs particuliers doivent être conservés, vous pouvez créer une liste avec le nom de ces utilisateurs : 

3bis c - Itération dans la liste et vérification de l'inactivité du viewer avant suppression

Nous pouvons maintenant itérer dans la liste de tous nos viewers. Nous utilisons la propriété lastLogin de la classe User pour vérifier que le viewer est bien inactif. Vous pouvez si vous le souhaitez rajouter d'autres conditions de suppression basées sur d'autres propriétés de cette classe.

Notez que sans itération, il est également possible de supprimer en lot une liste d'utilisateurs avec la fonction delete_users() de la classe UserManager. 

3bis d - Supprimer les utilisateurs tests de la démo

Nous allons maintenant supprimer les utilisateurs ayant servi pour cette démo pour qu'ils n'encombrent pas votre portail :

4 -  Automatiser la gestion des groupes (création, inscription d'utilisateurs)

4a - Création des groupes

De la même manière que nous avons pu utiliser l'API pour ajouter des utilisateurs par lot, nous allons pouvoir créer des groupes dans notre org à partir d'un fichier csv. Pour cela, nous utiliserons la fonction create() de la classe GroupManager. Comme tout à l'heure, nous commencerons par transformer le csv en dataframe pandas, que nous parcourons ensuite avec une boucle for pour créer les groupes les uns après les autres.Vous trouverez le csv à cet url, remplacez-le dans le code.

A nouveau, un environnement interactif vous permet de voir vos groupes être créés au fur et à mesure directement dans votre IDE:

4b - Ajouter des utilisateurs dans les groupes

Je veux maintenant faire en sorte d'ajouter tous les membres de mon organisation appartenant à la catégorie "Direction des solutions" au groupe de contenus partagés pour l'équipe de la direction des solutions.
Pour cela, vous devez avoir défini des catégories dans votre org (disponible dans ArcGIS Online, et depuis la v11.1 d'ArcGIS Enterprise) et les avoir attribuées au membre de votre organisation. Plus d'infos dans cette doc sous le chapitre "Classer les membres". 

Je commence par accéder à la liste de tous les utilisateurs de mon org appartenant à la catégorie "Direction des Solutions" (à adapter selon les catégories de votre org) avec la fonction search() de la classe UserManager de l'API : 

 

 

J'accède ensuite au groupe contenant les démos partagées avec la fonction search() de la classe GroupManager de l'API , en faisant une query sur le titre (title) du groupe:

 

Notez que nous faisons ici une utilisation assez simple de la fonction search(), en faisant une requête uniquement sur le titre du groupe. Il est en réalité possible de faire des recherches avec des query beaucoup plus élaborées, car cette méthode implémente les opérations de l'API REST. Si vous souhaitez faire des recherches plus avancées, vous pouvez voir la liste complète des champs sur lesquels vous pouvez baser votre recherche en vous rendant dans la section de la Search Reference dédiée aux groupes dans la documentation.

 

Je peux ensuite récupérer la liste des inscrits dans ce groupe avec la fonction get_members() de la classe Group de l'API : 

Je vais ensuite itérer parmi tous les utilisateurs de la catégorie Direction des Solutions récupérés précédemment, vérifier s'ils sont déjà membres du groupe, les ajouter à une liste s'ils ne le sont pas, puis ajouter tous les membres de cette liste au groupe avec la fonction add_users() de la classe Group de l'API :

Je peux maintenant réutiliser la fonction get_members() pour vérifier que les utilisateurs ont bien été rajoutés au groupe : 

L'API permet également de retirer les membres d'un groupe avec la fonction remove_users(). Nous allons l'utiliser ici par exemple pour retirer tous les utilisateurs dont le nom d'utilisateur commence par un "a" (oui, c'est complètement arbitraire). Notez qu'il n'est pas possible de supprimer le propriétaire ("owner") du groupe. 

Je peux à nouveau vérifier que tout s'est bien passé, toujours avec la fonction get_members() appliquée au groupe.

Maintenant que nous savons créer des groupes et y inscrire des utilisateurs, il serait bien de pouvoir y partager du contenu non? Cette fonctionnalité est disponible dans l'API Python, mais nous le verrons dans un autre tutoriel de cette série, qui sera consacré à la création, à la publication et au partage du contenu dans votre SIG web. Pour aujourd'hui, nous nous contenterons de supprimer ces groupes de démo pour ne pas encombrer votre organisation.

4c - Suppression des groupes

Nous pouvons supprimer les groupes de démo pour ne pas laisser de trace de nos tests :

C'est terminé pour cette semaine ! Vous pouvez dès à présent vous rendre sur le deuxième tutoriel de la série qui se penche sur un autre processus d'administration : la gestion les crédits d'une organisation ArcGIS Online (affectation, suivi, notifications d'alerte) et la planification de l'exécution d'un Notebook. Si vous êtes utilisateurs d'ArcGIS Enterprise, alors ce tutoriel ne vous concernera pas (vous pourrez cependant jeter un coup d’œil pour l'utilisation des notifications, qui peut également fonctionner chez vous). Dans ce cas, je vous donne rendez-vous dans 2 semaines où nous créerons un Dashboard de supervision de notre organisation, qui fonctionnera aussi bien dans Online que dans Enterprise !