API Tutoriel 1 : description du bâtiment

Prérequis

  • une plateforme Spinalcore fonctionnelle

  • un jumeau numérique initialisé avec un contexte géographique paramétré

  • le serveur d'API Spinalcore déployé

Objectifs

Un bâtiment est un "asset physique" compose d'étages, d'infrastructure, de murs, de portes, d'équipement, de mobilier... Toute les applications digitales fonctionnant en interaction avec le bâtiment doivent donc mettre en œuvre une description abstraite du bâtiment et de ses composantes afin de fournir un service concret. La description du bâtiment la plus commune est son arborescence géographique :

  • bâtiment

      • étage

          • locale

              • équipement

Une fonction de base du BOS Spinalcore est la gestion du cette arborescence géographique, que nous appelons aussi "référentiel géographique" du bâtiment. Ce premier tutoriel a pour objectif de vous montrer comment récupérer automatiquement ce référentiel à partir des API du BOS Spinalcore.

Deux méthodes sont présentées :

  • la méthode simple via l'API Géographique

  • la méthode graph via les API graph (à venir)

L'illustration suivante vous montre l'arborescence géographique que nous allons récupérer.

Méthode simple : API géographique

Requêtes utiles

GET "http://api.devv1.spinalcom.com/api/v1/geographicContext/tree"

GET "http://api.devv1.spinalcom.com/api/v1/floor/{dynamic_id}/floor_details"

GET "http://api.devv1.spinalcom.com/api/v1/room/{dynamic_id}/room_details"


Démarche

Pour récupérer l'arborescence géographique du bâtiment, rien de plus simple, c'est fait en une seule requête qui ne prend aucun paramètre :

  • identifiez-vous sur le serveur d'API (sur les versions "sandbox" cette étape n'est pas nécessaire pour tester l'API)

  • appelez l'API de récupération de l'arborescence géographique au format json

GET "http://api.devv1.spinalcom.com/api/v1/geographicContext/tree"

  • Si vous souhaitez obtenir les surface de chaque étage et chaque pièce

    • boucle sur les étages, récupérer l'identifiant dynamique de chaque étage puis :

GET "http://api.devv1.spinalcom.com/api/v1/floor/{dynamic_id}/floor_details"

    • boucle sur les pièces, récupérer l'identifiant dynamique de chaque pièce puis :

GET "http://api.devv1.spinalcom.com/api/v1/room/{dynamic_id}/room_details"

Voila!


Résultat

Vous obtenez comme résultat une arborescence json dans laquelle les objets context / bâtiment / étage / local / équipement sont fournie avec :

  • leur nom

  • leur identifiant dynamique (cette identifiant fonctionne comme un pointeur dans la base graph et permet une récupération très rapide d'un nœud du graph. Il peut par contre évoluer au redémarrage du serveur Spinalcore, nous conseillons donc, si vous souhaitez l'utiliser, ce qui est très utile pour obtenir de meilleur performances, de le remettre à jour à chaque nouvelle session)

  • leur identifiant statique (identifiant utilisé pour faire une recherche dans la base

  • leur type : geographicContext / geographicBuilding / geographicFloor / geographicRoom / BIMObject