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 le Swagger qui leur est associé, ou via un 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 utiliser les API de plan de contrôle en interagissant avec Azure Digital Twins via le portail Azure et l’interface de ligne de commande.

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 Import Jobs 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 Delete Jobs vous permet de gérer une action asynchrone de longue durée pour supprimer des modèles, des jumeaux et des 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 utiliser les API de plan de données en interagissant avec Azure Digital Twins via l’interface de ligne de commande.

Remarques concernant l’utilisation et l’authentification

Cette section contient des informations plus détaillées sur l’utilisation des API et des SDK.

Remarques concernant les API

Voici quelques informations générales concernant l’appel direct des API Azure Digital Twins.

• Vous pouvez utiliser un outil de test REST HTTP pour effectuer des appels directs aux API Azure Digital Twins. Pour plus d’informations sur ce processus, consultez Appeler les API Azure Digital Twins.
• 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 concernant l’authentification pour les requêtes d’API.

• L’une des manières de générer un jeton du porteur pour les requêtes d’API Azure Digital Twins consiste à utiliser la commande CLI az account get-access-token. Pour obtenir des instructions détaillées, consultez Ajouter un jeton du porteur.
• Les requêtes envoyé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 que celui où réside 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 le rôle Propriétaire des données Azure Digital Twins ou Lecteur des données Azure Digital Twins par le biais de la collaboration Microsoft Entra B2B. Pour savoir comment accéder à plusieurs locataires, consultez Écrire le code d’authentification de l’application.

Remarques concernant le Kit de développement logiciel (SDK)

Le kit 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 concernant l’authentification avec les kits SDK.

• Commencez par instancier la classe DigitalTwinsClient. Le constructeur exige des informations d’identification qui peuvent être obtenues par le biais de diverses méthodes d’authentification dans le package Azure.Identity. Pour plus d’informations sur Azure.Identity, consultez la documentation sur son espace de noms.
• Vous pourrez trouver InteractiveBrowserCredential utile 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 sur InteractiveBrowserCredential, 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 try et à intercepter au moins RequestFailedExceptions. 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> (ou Task<Response<T>> pour les appels asynchrones), où T correspond à 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 champ Value.
• Les méthodes de service ayant des résultats paginés retournent des résultats Pageable<T> ou AsyncPageable<T>. Pour plus d’informations sur la classe Pageable<T>, consultez sa documentation de référence. Pour plus d’informations sur AsyncPageable<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érique
• BasicDigitalTwinComponent : représente de façon générique un composant dans les propriétés Contents d’un BasicDigitalTwin
• BasicRelationship : représente de façon générique les données de base d’une relation
• DigitalTwinsJsonPropertyName : 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 Travaux d’importation

L’API Travaux d’importation 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 appel d’API unique. Les opérations de l’API Travaux d’importation sont également incluses avec les commandes CLI et les kits SDK de plan de données. L’utilisation de l’API Travaux d’importation nécessite l’utilisation de Stockage Blob Azure.

Vérifiez les autorisations

Pour utiliser l’API Travaux d’importation, 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 affecté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 graphique que vous souhaitez inclure dans l’appel Travaux. Cela peut inclure Microsoft.DigitalTwins/models/*, Microsoft.DigitalTwins/digitaltwins/* et/ou Microsoft.DigitalTwins/digitaltwins/relationships/*.

Le rôle intégré qui fournit toutes ces autorisations est Propriétaire des données Azure Digital Twins. Vous pouvez également utiliser un rôle personnalisé pour accorder un accès précis uniquement 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.

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 des données Blob du stockage pour le conteneur d’objets blob d’entrée Stockage Azure
• Contributeur aux données Blob du stockage pour le conteneur d’objets blob de sortie Stockage Azure

Enfin, générez un jeton du porteur qui peut être utilisé dans vos requêtes à l’API Travaux. Pour obtenir des instructions, consultez Ajouter un jeton du porteur.

Mettre en forme les données

L’API accepte l’entrée d’informations de graphique à partir d’un fichier NDJSON, qui doit être chargé dans un conteneur Stockage Blob Azure. Le fichier commence par une section Header, suivie des sections facultatives Models, Twins et Relationships. Vous n’avez pas besoin d’inclure les trois types de données de graphique 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}

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 (parmi les options, vous avez la commande AzCopy, Azure CLI ou le portail Azure). Vous utiliserez l’URL de stockage d’objets blob du fichier NDJSON dans le corps de l’appel de l’API Travaux d’importation.

Exécuter le travail d’importation

Vous pouvez maintenant passer à l’appel de l’API Travaux d’importation. Pour obtenir des instructions détaillées sur l’importation d’un graphique complet dans un appel d’API unique, consultez Charger des modèles, des jumeaux et des relations en bloc avec l’API Travaux d’importation. Vous pouvez également utiliser l’API Travaux d’importation pour importer chaque type de ressource indépendamment. Pour plus d’informations sur l’utilisation de l’API Travaux d’importation avec des types de ressources spécifiques, consultez les instructions relatives à l’API Travaux d’importation pour les modèles, les jumeaux et les relations.

Dans le corps de l’appel de l’API, vous fournirez 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’aura créé.

Lorsque le travail d’importation s’exécute, un journal de sortie structuré est généré par le service et stocké en tant que nouvel 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 un travail réussi important 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 le travail terminé, 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 un travail d’importation en cours d’exécution avec l’opération Annuler à partir de l’API Travaux d’importation. 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 Travaux d’importation :

• 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 à la fois est pris en charge dans une instance Azure Digital Twins. Vous pouvez consulter ces informations et d’autres limites numériques des API Travaux dans Limites d’Azure Digital Twins.

Suppression en bloc avec l’API Travaux de suppression

L’API Travaux de suppression 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 appel d’API unique. Les opérations de l’API Travaux de suppression sont également disponibles en tant que commandes CLI. Consultez la documentation de l’API pour afficher les détails des requêtes de création d’un travail de suppression et de vérification de son état.

Pour vous assurer que tous les éléments sont supprimés, suivez ces recommandations lors de l’utilisation de l’API Travaux de suppression :

• Pour obtenir des instructions sur la génération d’un jeton du porteur pour authentifier les demandes d’API, consultez Ajouter un 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, et elle 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 d’expirer ; à ce moment-là, 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 Travaux de suppression :

• 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 d’expiration de délai d’attente du travail.
• Un seul travail en bloc à la fois est pris en charge dans une instance Azure Digital Twins. Vous pouvez consulter ces informations et d’autres limites numériques des API Travaux dans 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 Superviser 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 effectuer des demandes directes aux API Azure Digital Twins :

• Appeler les API Azure Digital Twins

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 :

• Coder une application cliente