Créer une carte, y ajouter des données, la publier et la partager avec l'API Python d'ArcGIS

Dans ce quatrième tutoriel de la série de l'été consacrée à la prise en main de l'API Python d'ArcGIS, nous allons passer au deuxième volet de workflows réalisables avec l'API : la gestion de contenu. Cette semaine, nous commencerons par apprendre à créer une carte, à y ajouter des couches, à la sauvegarder et à la partager.

Contrairement aux scripts précédents consacrés à l'administration et demandant de facto un compte avec des privilèges administrateur, ce tutoriel et les prochains ne nécessitent pas ces privilèges. Notez cependant qu'un compte Creator ou supérieur sont nécessaires. 

Comme chaque semaine, 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 - Connexion au GIS

Nous commençons par importer les différentes bibliothèques nécessaires, puis par nous connecter au SIG. Pour cela, nous importons l'objet GIS du module gis, qui représente notre organisation. La connexion est ensuite à adapter selon votre environnement et votre méthode d'authentification. Vous pouvez consulter l'aide en ligne pour plus d'informations.
Si vous êtes connectés en tant qu'admin, la cellule va vous renvoyer un message rouge pour vous prévenir 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 - Créer et paramétrer une carte

2a - Faire appel au widget de carte

L'objet GIS inclut un widget de cartographie permettant d'afficher des cartes de manière interactive dans un Notebook, et de travailler avec. Pour pouvoir l'utiliser, il faut appeler la fonction gis.map() et l'assigner à une variable. Cela créée une instance de la classe MapView sur laquelle nous allons pouvoir travailler ensuite. Faire appel à la variable permet ensuite d'afficher une carte interactive directement dans le Notebook. 

2b - Modifier le zoom et le centre

Il est possible d'accéder à différente propriété du widget de carte afin d'en modifier l'affichage. Par exemple ci-dessous, nous allons modifier le zoom et le centre (center) de la carte :

Notez qu'il est possible de modifier ces propriétés directement au moment de la construction de la carte utilisant les paramètres de gis.map(), par exemple carte2 = gis.map(location = [46.855,2.33],zoomlevel = 10) 

2c - Changer la basemap

Nous allons également accéder à la propriété régissant le fond de carte. Pour savoir quels fonds de carte vous pouvez utiliser, il suffit d'interroger la propriété basemaps qui renverra la liste de tous les fonds de carte disponibles :

Nous pouvons ensuite changer la valeur de la propriété basemap (attention, sans 's' à la fin cette fois-ci) de notre carte avec l'une des basemaps de la liste ci-dessus :

Si vous retournez voir votre carte ci-dessus, elle devrait ressembler à cela :

2d - Et en 3D?

Les fonctionnalités que nous venons de voir sont aussi disponibles avec les scènes 3D ! Pour cela, il faut utiliser le mode 3D, par exemple lors de l'instanciation de la carte :

Vous pouvez également passer de la 3D à la 2D une fois la carte construite en accédant à la propriété mode du MapView, par exemple : carte.mode = '3D', ou encore le faire manuellement en cliquant sur le bouton de bascule entre les modes directement dans le widget de carte :

La 3D vous donne accès à deux paramètres supplémentaires pour le contrôle de la caméra : tilt et heading.

3 - Ajouter des couches

Nous allons maintenant voir comment ajouter des couches à notre carte.

 

3a - Accéder à une collection de Feature Layers

Pour cela, commençons à rechercher un feature layer. Pour cela, nous allons utiliser la méthode search() du ContentManager, qui nous permet de rechercher du contenu en le renvoyant sous la forme d'une liste d'item. Par défaut, la recherche du contenu se fait au sein de l'organisation.
Pour trouver un item en particulier, vous pouvez vous baser sur une query, qui peut rechercher des items via leur nom, leur id, leur propriétaire, leur type, etc. 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 items de la documentation.

 

Selon que vous soyez utilisateur ArcGIS Online ou ArcGIS Enterprise, nous n'allons pas faire exactement la même chose :

• Si vous êtes utilisateur ArcGIS Online, alors vous pouvez accéder à des items dont le partage niveau de partage est public hébergés en dehors de votre organisation en utilisant le le paramètre outside_org=True. Accédez à l'item dont l'identifiant est 726e437f738349729d021d1cfb40a813 publié par Esri France comme dans la cellule ci-dessous. Cet item contient les séismes historiques et récentes sur la France entière.
• Si vous êtes utilisateurs ArcGIS Enterprise, alors vous ne pourrez pas accéder à des items publiés en dehors de votre organisation, à moins d'une collaboration distribuée. Dans ce cas, accédez à un feature layer que vous possédez déjà, et qui possède plusieurs couches si possible. Utilisez pour cela la partie commentée de la cellule ci-dessous, en requêtant sur le titre (title) de votre feature layer (et pensez à supprimer la partie consacrée aux utilisateurs Online).

Vous constatez que search() renvoie bel et bien une liste. Pour accéder à l'item qui nous intéresse, nous récupérons le premier élément de la liste dans une nouvelle variable :

Notez que si vous accédez à du contenu interne à votre organisation et dont vous connaissez l'identifiant, il est possible de récupérer directement l'item en utilisant la méthode get() du ContentManager, par exemple : item_seismes = gis.content.get("726e437f738349729d021d1cfb40a813")

3b - Vérifier toutes les couches présentes dans la collection

L'item que nous que nous venons d'ajouter est de type Feature Layer Collection, et possède plusieurs couches. Il est possible d'y accéder via la propriété layers.
En itérant dans la liste des couches, nous pouvons accéder à son nom en appelant la propriété name accessible via la propriété properties :

3c - Accéder à une couche en particulier et l'ajouter à la carte

• Pour les utilisateurs ArcGIS Online, nous ajouterons à la carte uniquement la couche des séismes ayant eu lieu entre 1980 et 2023 en France métropolitaine, c'est-à-dire la deuxième couche du feature layer collection. Nous allons l'assigner à une nouvelle variable en y accédant en précisant son index (ici, 1 pour la deuxième couche car Python compte à partir de 0) lorsque nous appelons la propriété layers comme ci-dessous.
• Si vous êtes utilisateur ArcGIS Enterprise, vous pouvez accédez à la couche de votre choix en en précisant son index (par exemple, 1 pour la deuxième couche car Python compte à partir de 0) lorsque vous appelez la propriété layers. Assignez cette couche à une nouvelle variable comme ci-dessous.

Nous pouvons ensuite ajouter cette couche à la carte créée plus tôt, grâce à la méthode add_layer() du MapView.

Notez ici que j'appelle une nouvelle fois ma carte, ce qui va créer une nouvelle carte interactive dans mon Notebook. Celle-ci pointe toujours sur la même instance de MapView que celle créée au tout début du Notebook, donc les deux cartes affichent exactement la même chose. En général, nous évitons d'afficher trop de fois la même carte dans le même Notebook pour ne pas le surcharger, mais je le fais ici par confort visuel pour que vous puissiez observer les changements facilement. 

 

3d - Zoomer la carte à l'emprise du Feature Layer

La carte ne possède pas forcément la bonne emprise pour voir la couche entière. J'utilise la méthode zoom_to_layer() du MapView afin de modifier l'étdendue de la carte à l'empreinte de la couche :

Voici ce que vous devriez observer maintenant :

3e - Accéder à un second Feature Layer

Comme tout à l'heure, nous allons accéder à un item de type Feature Layer Collection.

• Pour les utilisateurs ArcGIS Online, vous pouvez rechercher l'item dont l'identifiant est a2910f64a47248beb3f280a0f323e4d5, que j'ai publié sur mon organisation et partagé en public. Veillez à ce que le paramètre outside_org soit égal à True. Cet item contient les failles potentiellement actives ainsi que les centrales nucléaires de France métropolitaine, et une zone tampon de 50km autour de ces dernières.
• Pour les utilisateurs ArcGIS Enterprise, vous pouvez au choix ajouter un Feature Layer contenant plusieurs couches de la même manière que précédemment, ou bien si vous souhaitez travailler avec les mêmes données que moi, vous pouvez télécharger directement les données que j'ai utilisées depuis le BDFA (Base de données des failles actives) et les publier sur votre portail en tant que couche d'entités hébergée pour les utiliser ci-dessous.
  

3f - Itérer dans toutes les couches du Feature Layer et les ajouter à la carte

Nous allons à nouveau itérer parmi les couches de notre collection de feature layer en accédant à la propriété layers. Cette fois-ci, nous utiliseront directement la méthode add_layer() pour ajouter toutes les couches à notre carte.

Notez qu'au lieu de parcourir mes couches dans leur ordre classique, je les parcoure en sens inverse grâce à la fonction reversed(). En réalité, dans la collection de feature layers, mes couches apparaissent dans l'ordre suivant : couche ponctuelle (centrales nucléaires), couche linéaire (failles) et couche surfacique (zone tampon de 50km autour des centrales), comme dans la plupart des carte pour éviter les problèmes de lecture. Hors, si j'ajoute mes données dans cet ordre à la carte, mes points vont se retrouver sous mes polygones. En parcourant la liste en sens inverse, j'ajoute ainsi mes données dans l'ordre polygone-lignes-points.

Vous pouvez aller jeter un coup d'oeil à la carte pour voir si vos couches se sont bien ajoutées.

Au lieu de parcourir ainsi les couches et les ajouter une par une, il est possible de passer directement l'item à la méthode add_layer(), par exemple ici carte.add_layer(item_failles_centrales). Cependant, cela peut créer des problèmes de symbologie dans la visualisation de la carte, notamment si vos différentes couches n'ont pas la même géométrie. Voici la liste des types de données que vous pouvez ajouter à la carte avec add_layer(), que ça soit en accédant aux couches ou à l'item: FeatureLayer, FeatureCollection, ImageryLayer et MapImageLayer.

4 - Supprimer une couche

4a - Lister les couches de la carte

Je peux très facilement accéder à la liste des couches présentes dans ma carte grâce à la propriété layers du MapView : 

Comme tout à l'heure, nous allons itérer dans la liste des couches pour afficher leur nom en appelant la propriété name accessible via la propriété properties :

4b - Supprimer une couche spécifique

J'aimerais supprimer la couche contenant les zones tampons autour de mes centrales nucléaires, qui finalement ne me conviennent plus (si êtes utilisateur ArcGIS Enterprise et que vous utilisez vos propres feature layer, supprimez la couche de votre choix). Je vais pour cela utiliser la méthode remove_layers() sur ma carte, et je cible ici la deuxième couche de ma carte (celle qui contient les zones tampons si je me réfère à la liste ci-dessus) en utilisant l'index de la liste renvoyée par la propriété layers.

5 - Publier la carte

Maintenant que la carte me convient, je peux la publier en tant que webmap sur mon organisation grâce à la méthode save() de la Mapview.
Pour cela, je crée dans un premier temps un dictionnaire qui va contenir les propriétés de ma carte : son nom, son résumé, ses tags... D'autres propriétés sont accessibles, vous pouvez consulter la liste complète dans la documentation.
J'appelle ensuite la fonction save() sur ma carte en passant en paramètre le dictionnaire des propriétés tout en l'assignant à une variable.
Je peux enfin appeler la variable qui me renvoie la webmap sauvegardée sur mon portail.

6 - Modifier les paramètres de partage

Pour partager la webmap, j'utilise ici la nouvelle implémentation du SharingManager, disponible depuis la version 2.3.0 de l'API. Si vous avez un doute sur la version de l'API que vous utilisez, vous pouvez exécuter le code suivant : print(arcgis.__version__).

Si vous utilisez une version antérieure à la 2.3.0, vous pouvez utiliser la méthode share() et la propriété shared_with de l'Item comme montré dans les commentaires des cellules, mais notez que celle-ci est dépréciée en 2.3.0 et sera retirée à partir de la version 3.0.0 de l'API.

6a - Partage dans un groupe

Nous allons commencer par partager la webmap dans un groupe. Nous pouvons obtenir la liste des groupes dans lesquels l'item est partagé de la manière suivante :

Pour l'instant, vous constatez que la webmap n'est pas partagée.
Nous allons rechercher le groupe dans lequel nous voulons partager la webmap avec la méthode search() du GroupManager.
Comme pour la recherche du contenu, nous allons utiliser une requête pour chercher le groupe de notre choix, cette fois-ci via le titre.
Ici, je recherche un groupe que j'ai créé spécialement pour l'occasion dans mon organisation et que j'ai appelé "Groupe partage API Python". Vous pouvez utiliser le groupe de votre choix dans votre organisation.
A nouveau, search() renvoie une liste. Nous accédons donc au premier élément de cette liste pour accéder directement à notre groupe.

Nous accédons au SharingManager en utilisant la propriété sharing de l'Item. Pour les groupes, nous accédons ensuite à la propriété groups qui nous donne accès au SharingGroupManager, sur lequel nous pouvons utiliser la méthode add(). En paramètre de la fonction, nous passons le ou les groupes dans lesquels nous souhaitons ajouter notre carte :

Nous pouvons ré-accéder à la liste des groupes dans lequel notre item est partagé pour vérifier que tout a bien fonctionné :

6b - Niveau de partage

Nous allons maintenant modifier le niveau de partage, qui peut être privé, au niveau de l'organisation ou public. Nous pouvons savoir quel est le niveau de partage actuel en accédant à la propriété sharing_level du SharingManager :

Le niveau de partage de la webmap est actuellement privé. Je peux modifier la valeur de la propriété, en choisissant entre PRIVATE (accessible uniquement pour le propriétaire), ORG (accessible à tous les utilisateurs de mon organisation) et EVERYONE (public). Partageons ici à l'organisation :

Imprimons une fois de plus le niveau de partage pour vérifier que cela a bien fonctionné :

C'est fini pour ajourd'hui ! Nous avons vu comment créer une carte de zéro en créant une nouvelle instance de carte et en l'enregistrant en tant que webmap dans notre portail.
Dans deux semaines, nous verrons comment l'API peut aussi permettre d'accéder à des données existantes (webmap ou couche), les cloner et les mettre à jour. Ce type de workflow permet notamment de pousser de nouvelles données sur votre portail et de vous en servir pour mettre à jour vos couches et carte, en updatant automatiquement les applications dans lesquelles elles sont utilisées. La semaine prochaine, nous apprendrons à préparer les données que nous utiliserons dans le workflow de mise à jour, en utilisant l'API Python pour faire du data engineering et en tirant parti des spatially enabled dataframes (sedf).