API et SDK Azure Digital Twins
Cet article donne une vue d’ensemble des API Azure Digital Twins disponibles, ainsi que des méthodes d’interaction avec elles. Vous pouvez utiliser les API REST directement avec les Swaggers qui y sont associés (via un outil tel que Postman), ou via un Kit de développement logiciel (SDK).
Azure Digital Twins est fourni avec des API de plan de contrôle, des API de plan de données et des kits de développement logiciel (SDK) pour la gestion de votre instance et de ses éléments.
- Les API de plan de contrôle sont des API Azure Resource Manager (ARM) qui couvrent les opérations de gestion des ressources, telles que la création et la suppression de votre instance.
- Les API de plan de données sont des API Azure Digital Twins qui sont utilisées pour les opérations de gestion des données, telles que la gestion des modèles, des représentations et du graphique.
- Les kits de développement logiciel (SDK) tirent parti des API existantes pour faciliter le développement d’applications personnalisées utilisant Azure Digital Twins.
API de plan de contrôle
Les API de plan de contrôle sont des API ARM utilisées pour la gestion de votre instance Azure Digital Twins dans son ensemble. Elles permettent donc d’effectuer des opérations telles que la création ou la suppression de votre instance dans son intégralité. Vous utiliserez également ces API afin de créer et de supprimer des points de terminaison.
Pour appeler les API directement, référencez le dossier Swagger le plus récent dans le référentiel Swagger du plan de contrôle. Ce dossier contient également un dossier d’exemples qui en montrent l’utilisation.
Voici les KITS SDK actuellement disponibles pour les API de plan de contrôle Azure Digital Twins.
Vous pouvez également exercer les API du plan de contrôle en interagissant avec Azure Digital Twins via les Portail Azure et l’interface CLI.
API de plan de données
Les API de plan de données sont les API Azure Digital Twins utilisées pour gérer les éléments compris dans votre instance Azure Digital Twins. Elles incluent des opérations telles que la création d’itinéraires, le chargement de modèles, la création de relations et la gestion de jumeaux, lesquelles peuvent être réparties dans les catégories suivantes :
DigitalTwinModels- La catégorie DigitalTwinModels contient des API permettant de gérer des modèles dans une instance Azure Digital Twins. Les activités de gestion incluent le chargement, la validation, la récupération et la suppression des modèles créés dans DTDL.DigitalTwins- La catégorie DigitalTwins contient les API qui permettent aux développeurs de créer, de modifier et de supprimer les jumeaux numériques et leurs relations dans une instance Azure Digital Twins.Query- La catégorie Query permet aux développeurs de trouver des jeux de jumeaux numériques dans le graphe jumeau parmi les relations.Event Routes- La catégorie Event Routes contient des API permettant d’acheminer des données via le système et vers les services en aval.Import Jobs- L’API Importer des travaux vous permet de gérer une action asynchrone de longue durée pour importer des modèles, des jumeaux et des relations en bloc.Delete Jobs- L’API Supprimer les travaux vous permet de gérer une action asynchrone longue et longue pour supprimer tous les modèles, jumeaux et relations dans une instance.
Pour appeler les API directement, référencez le dossier Swagger le plus récent dans le référentiel Swagger du plan de données. Ce dossier contient également un dossier d’exemples qui en montrent l’utilisation. Vous pouvez également consulter la documentation de référence de l’API du plan de données.
Voici les KITS SDK actuellement disponibles pour les API de plan de données Azure Digital Twins.
Vous pouvez également exercer les API de plan de données en interagissant avec Azure Digital Twins via l’interface CLI.
Notes d’utilisation et d’authentification
Cette section contient des informations plus détaillées sur l’utilisation des API et des SDK.
Notes d’API
Voici quelques informations générales pour appeler directement les API Azure Digital Twins.
- Vous pouvez utiliser un outil de test REST HTTP comme Postman pour effectuer des appels directs aux API Azure Digital Twins. Pour plus d’informations sur ce processus, consultez Appel des API Azure Digital Twins avec Postman.
- Azure Digital Twins ne prend pas actuellement en charge le partage des ressources cross-origin (CORS). Pour plus d’informations sur les stratégies d’impact et de résolution, consultez Partage des ressources cross-origin (CORS) pour Azure Digital Twins.
Voici quelques informations supplémentaires sur l’authentification pour les demandes d’API.
- Une façon de générer un jeton du porteur pour les demandes d’API Azure Digital Twins est avec la commande az account get-access-token CLI. Pour obtenir des instructions détaillées, consultez Obtenir le jeton du porteur.
- Les demandes adressées aux API Azure Digital Twins nécessitent un utilisateur ou un principal de service qui fait partie du même locataire Microsoft Entra ID où existe l’instance Azure Digital Twins. Pour empêcher l’analyse malveillante des points de terminaison Azure Digital Twins, les demandes avec des jetons d’accès qui ne proviennent pas du locataire d’origine recevront le message d’erreur « 404 Sous-domaine introuvable ». Cette erreur est retournée même si l’utilisateur ou le principal de service a reçu un rôle de propriétaire de données Azure Digital Twins ou lecteur de données Azure Digital Twins via Microsoft Entra B2B Collaboration. Pour savoir comment accéder à plusieurs locataires, consultez Écrire le code d’authentification de l’application.
Notes du Kit de développement logiciel (SDK
Le Kit de développement logiciel (SDK) sous-jacent pour Azure Digital Twins est Azure.Core. Pour plus d’informations sur l’infrastructure et les types de SDK, consultez la documentation sur les espaces de noms Azure.
Voici quelques informations supplémentaires sur l’authentification avec les kits sdk.
- Commencez par instancier la
DigitalTwinsClientclasse. Le constructeur exige des informations d’identification qui peuvent être obtenues par le biais de diverses méthodes d’authentification dans le packageAzure.Identity. Pour plus d’informations surAzure.Identity, consultez la documentation sur son espace de noms. - Vous pourrez trouver
InteractiveBrowserCredentialutile dans les débuts. Toutefois, il existe plusieurs autres options, comme les informations d’identification pour l’identité managée, qui permettent d’authentifier les fonctions Azure configurées avec MSI dans Azure Digital Twins. Pour plus d’informations surInteractiveBrowserCredential, consultez la documentation sur sa classe.
Voici quelques informations supplémentaires sur les fonctions et les données retournées.
- Tous les appels d’API de service sont exposés comme des fonctions membres dans la classe
DigitalTwinsClient. - Toutes les fonctions de service existent dans une version synchrone et une version asynchrone.
- Toutes les fonctions de service lèvent une exception pour tout état de retour de 400 (ou supérieur). Veillez à wrapper les appels dans une section
tryet à intercepter au moinsRequestFailedExceptions. Pour plus d’informations sur ce type d’exception, consultez sa documentation de référence. - La plupart des méthodes de service retournent
Response<T>(ouTask<Response<T>>pour les appels asynchrones), oùTcorrespond à la classe de l’objet de retour pour l’appel de service. La classe Response encapsule le retour de service et présente les valeurs de retour dans son champValue. - Les méthodes de service ayant des résultats paginés retournent des résultats
Pageable<T>ouAsyncPageable<T>. Pour plus d’informations sur la classePageable<T>, consultez sa documentation de référence. Pour plus d’informations surAsyncPageable<T>, consultez sa documentation de référence. - Vous pouvez effectuer une itération sur des résultats paginés à l’aide d’une boucle
await foreach. Pour plus d’informations sur ce processus, consultez Iterating with Async Enumerables in C# 8. - Les méthodes de service retournent des objets fortement typés dès que cela est possible. Toutefois, étant donné qu’Azure Digital Twins est basé sur des modèles personnalisés configurés par l’utilisateur au moment de l’exécution (via des modèles DTDL chargés dans le service), de nombreuses API de service acceptent et retournent des données de jumeau au format JSON.
Assistances de sérialisation dans le SDK .NET (C#)
Les assistances de sérialisation sont des fonctions d’assistance disponibles dans le SDK NET (C#) pour créer ou désérialiser rapidement des données de jumeaux pour accéder à des informations de base. Étant donné que les méthodes principales du kit de développement logiciel (SDK) retournent des données de jumeaux au format JSON par défaut, il peut être utile d’utiliser ces classes d’assistance pour décomposer les données de jumeaux.
Les classes d’assistance disponibles sont les suivantes :
BasicDigitalTwin: représente de façon générique les données de base d’un jumeau numériqueBasicDigitalTwinComponent: représente de façon générique un composant dans les propriétésContentsd’unBasicDigitalTwinBasicRelationship: représente de façon générique les données de base d’une relationDigitalTwinsJsonPropertyName: contient les constantes de chaîne à utiliser dans la sérialisation et la désérialisation JSON pour les types de jumeaux numériques personnalisés
Importation en bloc avec l’API Importer des travaux
L’API Importer des travaux est une API de plan de données qui vous permet d’importer un ensemble de modèles, de jumeaux et/ou de relations dans un seul appel d’API. Les opérations d’API d’importation de travaux sont également incluses avec les commandes CLI et les kits SDK de plan de données. L’utilisation de l’API Importer des travaux nécessite l’utilisation de Stockage Blob Azure.
Vérifiez les autorisations
Pour utiliser l’API Importer des travaux, vous devez activer les paramètres d’autorisation décrits dans cette section.
Tout d’abord, vous aurez besoin d’une identité managée affectée par le système pour votre instance Azure Digital Twins. Pour obtenir des instructions sur la configuration d’une identité managée par le système pour l’instance, consultez Activer/désactiver l’identité managée pour l’instance.
Vous devez disposer d’autorisations d’écriture dans votre instance Azure Digital Twins pour les catégories d’actions de données suivantes :
Microsoft.DigitalTwins/jobs/*- Tous les éléments de graphe que vous souhaitez inclure dans l’appel Travaux. Cela peut inclure
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*et/ouMicrosoft.DigitalTwins/digitaltwins/relationships/*.
Le rôle intégré qui fournit toutes ces autorisations est Le propriétaire des données Azure Digital Twins. Vous pouvez également utiliser un rôle personnalisé pour accorder un accès granulaire aux types de données dont vous avez besoin. Pour plus d’informations sur les rôles dans Azure Digital Twins, consultez Sécurité pour les solutions Azure Digital Twins.
Remarque
Si vous tentez un appel d’API Importer des travaux et que vous manquez des autorisations d’écriture sur l’un des types d’éléments de graphe que vous essayez d’importer, le travail ignore ce type et importe les autres. Par exemple, si vous avez un accès en écriture aux modèles et aux jumeaux, mais pas aux relations, une tentative d’importation en bloc des trois types d’éléments réussit uniquement à importer les modèles et les jumeaux. L’état du travail reflète un échec et le message indique les autorisations manquantes.
Vous devez également accorder les autorisations RBAC suivantes à l’identité managée affectée par le système de votre instance Azure Digital Twins afin qu’elle puisse accéder aux fichiers d’entrée et de sortie dans le conteneur Stockage Blob Azure :
- lecteur de données blob Stockage pour le conteneur d’objets blob d’entrée Stockage Azure
- Stockage Contributeur aux données blob pour le conteneur d’objets blob de sortie Stockage Azure
Enfin, générez un jeton du porteur qui peut être utilisé dans vos demandes à l’API Travaux. Pour obtenir des instructions, consultez Obtenir le jeton du porteur.
Mettre en forme les données
L’API accepte l’entrée d’informations de graphe à partir d’un fichier NDJSON , qui doit être chargée dans un conteneur de stockage d’objets blob Azure. Le fichier commence par une Header section, suivie des sections facultatives Models, Twinset Relationships. Vous n’avez pas besoin d’inclure les trois types de données de graphe dans le fichier, mais toutes les sections présentes doivent suivre cet ordre. Les jumeaux et les relations créés avec cette API peuvent éventuellement inclure l’initialisation de leurs propriétés.
Voici un exemple de fichier de données d’entrée pour l’API d’importation :
{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}
Conseil
Pour obtenir un exemple de projet qui convertit des modèles, des jumeaux et des relations en NDJSON pris en charge par l’API d’importation, consultez Azure Digital Twins Bulk Import NDJSON Generator. L’exemple de projet est écrit pour .NET et peut être téléchargé ou adapté pour vous aider à créer vos propres fichiers d’importation.
Une fois le fichier créé, chargez-le dans un objet blob de blocs dans Stockage Blob Azure à l’aide de votre méthode de chargement préférée (certaines options sont la commande AzCopy, Azure CLI ou le Portail Azure). Vous allez utiliser l’URL de stockage d’objets blob du fichier NDJSON dans le corps de l’appel de l’API Import Jobs.
Exécuter le travail d’importation
Vous pouvez maintenant passer à l’appel de l’API Importer des travaux. Pour obtenir des instructions détaillées sur l’importation d’un graphique complet dans un appel d’API, consultez Charger des modèles, des jumeaux et des relations en bloc avec l’API Importer des travaux. Vous pouvez également utiliser l’API Importer des travaux pour importer chaque type de ressource indépendamment. Pour plus d’informations sur l’utilisation de l’API Importer des travaux avec des types de ressources individuels, consultez les instructions de l’API Importer des travaux pour les modèles, les jumeaux et les relations.
Dans le corps de l’appel d’API, vous fournissez l’URL de stockage d’objets blob du fichier d’entrée NDJSON. Vous fournirez également une nouvelle URL de stockage d’objets blob pour indiquer où vous souhaitez stocker le journal de sortie une fois que le service l’a créé.
Important
Vérifiez que l’identité managée affectée par le système de votre instance Azure Digital Twins dispose des autorisations RBAC d’objet blob de stockage décrites dans la section Vérifier les autorisations.
Lorsque le travail d’importation s’exécute, un journal de sortie structuré est généré par le service et stocké en tant qu’objet blob d’ajout dans votre conteneur d’objets blob, à l’emplacement d’URL que vous avez spécifié pour l’objet blob de sortie dans la requête. Voici un exemple de journal de sortie pour une tâche réussie qui importe des modèles, des jumeaux et des relations :
{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}
Une fois la tâche terminée, vous pouvez voir le nombre total d’entités ingérées à l’aide de la métrique BulkOperationEntityCount.
Il est également possible d’annuler une tâche d’importation en cours d’exécution avec l’opération Annuler à partir de l’API Importer des travaux. Une fois que le travail a été annulé et qu’il n’est plus en cours d’exécution, vous pouvez le supprimer.
Limites et considérations
Gardez à l’esprit les considérations suivantes lors de l’utilisation de l’API Importer des travaux :
- Les travaux d’importation ne sont pas des opérations atomiques. Il n’existe aucune restauration en cas d’échec, d’achèvement partiel du travail ou d’utilisation de l’opération Annuler.
- Un seul travail en bloc est pris en charge à la fois dans une instance Azure Digital Twins. Vous pouvez afficher ces informations et d’autres limites numériques des API Travaux dans les limites d’Azure Digital Twins.
Suppression en bloc avec l’API Supprimer des travaux
L’API Delete Jobs est une API de plan de données qui vous permet de supprimer tous les modèles, jumeaux et relations dans une instance avec un seul appel d’API. Les opérations de l’API Supprimer les travaux sont également disponibles en tant que commandes CLI. Consultez la documentation de l’API pour afficher les détails de la demande de création d’un travail de suppression et case activée son état.
Pour vous assurer que tous les éléments sont supprimés, suivez ces recommandations lors de l’utilisation de l’API Supprimer des travaux :
- Pour obtenir des instructions sur la génération d’un jeton du porteur pour authentifier les demandes d’API, consultez Obtenir le jeton du porteur.
- Si vous avez récemment importé un grand nombre d’entités dans votre graphique, attendez un certain temps et vérifiez que tous les éléments sont synchronisés dans votre graphique avant de commencer le travail de suppression.
- Arrêtez toutes les opérations sur l’instance, en particulier les opérations de chargement, jusqu’à ce que le travail de suppression soit terminé.
Selon la taille du graphique en cours de suppression, un travail de suppression peut prendre entre quelques minutes et plusieurs heures.
La période d’expiration par défaut d’un travail de suppression est de 12 heures, qui peut être ajustée à n’importe quelle valeur comprise entre 15 minutes et 24 heures à l’aide d’un paramètre de requête sur l’API. Il s’agit de la durée pendant laquelle le travail de suppression s’exécutera avant qu’il expire, à quel moment le service tentera d’arrêter le travail s’il n’est pas encore terminé.
Limites et autres considérations
Gardez à l’esprit les considérations suivantes lors de l’utilisation de l’API Supprimer les travaux :
- Les travaux de suppression ne sont pas des opérations atomiques. Il n’y a pas de restauration en cas d’échec, d’achèvement partiel du travail ou de délai d’expiration du travail.
- Un seul travail en bloc est pris en charge à la fois dans une instance Azure Digital Twins. Vous pouvez afficher ces informations et d’autres limites numériques des API Travaux dans les limites d’Azure Digital Twins.
Superviser les métriques d’API
Les métriques d’API, comme celles concernant les requêtes, la latence et le taux d’échec, peuvent être affichées dans le portail Azure.
Pour plus d’informations sur l’affichage et la gestion des métriques Azure Digital Twins, consultez Surveiller votre instance. Pour obtenir la liste complète des mesures d’API disponibles pour Azure Digital Twins, consultez Mesures des requêtes d’API Azure Digital Twins.
Étapes suivantes
Découvrez comment adresser des demandes directes aux API Azure Digital Twins à l’aide de Postman :
Ou bien, dans la pratique, utilisez le Kit de développement logiciel (SDK) .NET en créant une application cliente à l’aide de ce tutoriel :