Partager via

Guide pratique pour utiliser les API de gestion Azure Digital Twins

  • Article

Important

Une nouvelle version du service Azure Digital Twins a été publiée. En fonction des fonctionnalités étendues du nouveau service, le service Azure Digital Twins d’origine (décrit dans ce jeu de documentation) a été supprimé.

Pour afficher la documentation du nouveau service, consultez la documentation Azure Digital Twins active.

Les API de gestion Azure Digital Twins fournissent de puissantes fonctionnalités pour vos applications IoT. Cet article montre comment naviguer dans la structure des API.

Résumé des API

La liste suivante montre les composants des API Digital Twins.

  • /spaces : ces API interagissent avec les emplacements physiques de votre configuration. Elles vous aident à créer, supprimer et gérer les mappages numériques de vos emplacements physiques sous la forme d’un graphe spatial.

  • /devices : ces API interagissent avec les appareils de votre configuration. Ces appareils peuvent gérer un ou plusieurs capteurs. Il peut s’agir par exemple de votre téléphone, d’un pod de capteur Raspberry Pi, d’une passerelle Lora, et ainsi de suite.

  • /sensor : ces API vous aident à communiquer avec les capteurs associés à vos appareils et à vos emplacements physiques. Les capteurs enregistrent et envoient des valeurs ambiantes, qui peuvent ensuite être utilisées pour manipuler votre environnement spatial.

  • /resources : ces API vous aident à configurer des ressources, telles qu’un hub IoT, pour votre instance Digital Twins.

  • /types : ces API vous permettent d’associer des types étendus à vos objets Digital Twins pour ajouter des caractéristiques spécifiques à ces objets. Ces types facilitent le filtrage et le regroupement d’objets dans l’interface utilisateur et les fonctions personnalisées qui traitent vos données de télémétrie. DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType et SpaceResourceType sont des exemples de types étendus.

  • /ontologies : ces API vous aident à gérer les ontologies, qui sont des collections de types étendus. Les ontologies fournissent des noms pour les types d’objets en fonction de l’espace physique qu’ils représentent. Par exemple, l’ontologie BACnet fournit des noms spécifiques pour sensortypes, datatypes, datasubtypes et dataunittypes. Les ontologies sont gérées et créées par le service. Les utilisateurs peuvent charger et décharger des ontologies. Quand une ontologie est chargée, tous ses noms de types associés sont activés et prêts à être provisionnés dans votre graphe spatial.

  • /propertyKeys : vous pouvez utiliser ces API pour créer des propriétés personnalisées pour vos espaces, appareils, utilisateurs et capteurs. Ces propriétés sont créées en tant que paires clé/valeur. Vous pouvez définir le type de données pour ces propriétés en définissant leur PrimitiveDataType. Par exemple, vous pouvez définir une propriété nommée BasicTemperatureDeltaProcessingRefreshTime de type uint pour vos capteurs, puis attribuer une valeur à cette propriété pour chacun de vos capteurs. Vous pouvez également ajouter des contraintes pour ces valeurs lors de la création de la propriété, telles que des plages d’adresses Min et Max, ainsi que des valeurs autorisées en tant que ValidationData.

  • /matchers : ces API vous permettent de spécifier les conditions que vous souhaitez évaluer à partir de vos données d’appareil entrantes. Pour plus d’informations, voir cet article.

  • /userDefinedFunctions : ces API vous permettent de créer, supprimer ou mettre à jour une fonction personnalisée qui s’exécutera lorsque les conditions définies par les matcheurs se produisent, pour traiter les données provenant de votre configuration. Pour plus d’informations sur ces fonctions personnalisées, également appelées fonctions définies par l’utilisateur, consultez cet article.

  • /endpoints : ces API vous permettent de créer des points de terminaison afin que votre solution Digital Twins puisse communiquer avec d’autres services Azure pour le stockage et l’analytique des données. Pour plus d’informations, consultez cet article.

  • /keyStores : ces API vous permettent de gérer les magasins de clés de sécurité pour vos espaces. Ces magasins peuvent contenir une collection de clés de sécurité. Ils vous permettent de récupérer facilement les dernières clés valides.

  • /users : ces API vous permettent d’associer des utilisateurs à vos espaces pour localiser ces personnes lorsque nécessaire.

  • /system : ces API vous permettent de gérer les paramètres à l’échelle du système, tels que les types par défaut d’espaces et de capteurs.

  • /roleAssignments : ces API vous permettent d’associer des rôles à des entités telles que l’ID utilisateur, l’ID de fonction défini par l’utilisateur, etc. Chaque attribution de rôle inclut l’ID de l’entité à associer, le type d’entité, l’ID du rôle à associer, l’ID de locataire et un chemin qui définit la limite supérieure de la ressource que l’entité peut accéder à cette association. Pour plus d’informations, consultez cet article.

Navigation parmi les API

Les API Digital Twins prennent en charge le filtrage et la navigation dans l’ensemble de votre graphe spatial avec les paramètres suivants :

  • spaceId : l’API filtre les résultats par l’ID d’espace donné. En outre, l’indicateur booléen useParentSpace s’applique aux API /spaces. Il indique que l’ID d’espace spécifié fait référence à l’espace parent plutôt qu’à l’espace actuel.

  • minLevel et maxLevel : les espaces racines sont considérés comme étant au niveau 1. Les espaces avec un espace parent au niveau n sont au niveau n+1. Avec ces valeurs définies, vous pouvez filtrer les résultats à des niveaux spécifiques. Une fois définies, il s’agit de valeurs inclusives. Les appareils, capteurs et autres objets sont considérés comme étant au même niveau que leur espace le plus proche. Pour obtenir tous les objets à un niveau donné, affectez la même valeur aux options minLevel et maxLevel.

  • minRelative et maxRelative : lorsque ces filtres sont donnés, le niveau correspondant est relatif au niveau de l’ID d’espace donné :

    • Le niveau relatif 0 est au même niveau que l’ID d’espace spécifié
    • Le niveau relatif 1 représente les espaces au même niveau que les enfants de l’ID d’espace spécifié. Le niveau relatif n représente les espaces inférieurs à l’espace spécifié de n niveaux
    • Le niveau relatif -1 représente les espaces au même niveau que l’espace parent de l’espace spécifié

  • traverse : vous permet de parcourir dans les deux sens à partir d’un ID d’espace donné, comme spécifié par les valeurs suivantes.

    • Aucun : cette valeur par défaut filtre l’ID d’espace donné.
    • Bas : cela filtre par l’ID d’espace donné et ses descendants.
    • Haut : cela filtre par l’ID d’espace donné et ses ancêtres.
    • Étendue : cela filtre une partie horizontale du graphique spatial, au même niveau que l’ID d’espace donné. Il faut pour cela que minRelative ou maxRelative ait la valeur true.

Exemples

La liste suivante présente quelques exemples de navigation parmi les API /devices. Notez que l’espace réservé YOUR_MANAGEMENT_API_URL fait référence à l’URI des API Digital Twins au format https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/, où YOUR_INSTANCE_NAME est le nom de votre instance Azure Digital Twins et YOUR_LOCATION correspond à la région où votre instance est hébergée.

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 retourne tous les appareils connectés aux espaces racines.
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 retourne tous les appareils connectés aux espaces de niveaux 2, 3 ou 4.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId retourne tous les appareils connectés directement à mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down retourne tous les appareils connectés à mySpaceId ou l’un de ses descendants.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true retourne tous les appareils connectés aux descendants de mySpaceId, à l’exclusion de mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true retourne tous les appareils connectés à des enfants immédiats de mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true retourne tous les appareils connectés à l’un des ancêtres de mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 retourne tous les appareils connectés aux descendants de mySpaceId situés à un niveau inférieur ou égal à 5.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true retourne tous les appareils connectés aux espaces situés au même niveau que mySpaceId.

Prise en charge d’OData

La plupart des API qui retournent des collections, comme un appel GET sur /spaces, prennent en charge le sous-ensemble suivant des options de requête système OData génériques :

  • $filter
  • $orderby
  • $top
  • $skip : si vous souhaitez afficher l’ensemble de la collection, vous devez la demander en entier dans un même appel, puis exécuter la pagination dans votre application.

Notes

Certaines options OData (telles que les options $count, $expand et $search) ne sont pas prises en charge actuellement.

Exemples

La liste suivante décrit plusieurs requêtes avec une syntaxe OData valide :

  • YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
  • YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
  • YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
  • YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
  • YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
  • YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

Étapes suivantes

Pour découvrir quelques modèles de requête d’API courants, consultez Guide pratique pour interroger des API Azure Digital Twins pour des tâches courantes.

Pour en savoir plus sur vos points de terminaison d’API, consultez Comment utiliser Digital Twins Swagger.

Pour connaître la syntaxe OData et les opérateurs de comparaison disponibles, voir Opérateurs de comparaison OData dans la Recherche cognitive Azure.