Partage via


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.

Langage du SDK Lien du package Documentation de référence Code source
.NET (C#) Azure.ResourceManager.DigitalTwins on NuGet Référence pour le Kit de développement logiciel (SDK) Azure DigitalTwins pour .NET Bibliothèque de client de gestion Microsoft Azure Digital Twins pour .NET sur GitHub
Java azure-resourcemanager-digitaltwins on Maven Référence pour la gestion des ressources - Digital Twins Bibliothèque de client AzureDigitalTwins Azure Resource Manager pour Java sur GitHub
JavaScript Bibliothèque de client AzureDigitalTwinsManagement pour JavaScript sur npm Bibliothèque de client AzureDigitalTwinsManagement pour JavaScript sur GitHub
Python azure-mgmt-digitaltwins on PyPI Kit de développement logiciel (SDK) Microsoft Azure pour Python sur GitHub
Go azure-sdk-for-go/services/digitaltwins/mgmt Kit de développement logiciel (SDK) Azure pour Go sur GitHub

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 :

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.

Langage du SDK Lien du package Documentation de référence Code source
.NET (C#) Azure.DigitalTwins.Core sur NuGet Référence pour la bibliothèque de client Azure IoT Digital Twins pour .NET Bibliothèque de client Azure IoT Digital Twins pour .NET sur GitHub
Java com.azure:azure-digitaltwins-core sur Maven Référence pour le Kit de développement logiciel (SDK) Azure Digital Twins pour Java Bibliothèque de client Azure IoT Digital Twins pour Java sur GitHub
JavaScript Bibliothèque de client Core Azure Digital Twins pour JavaScript sur npm Reference for @azure/digital-twins-core Bibliothèque de client Core Azure Digital Twins pour JavaScript sur GitHub
Python Bibliothèque de client Core Azure Digital Twins pour Python sur PyPI Référence pour azure-digitaltwins-core Bibliothèque de client Core Azure Digital Twins pour Python sur GitHub

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.

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.

Remarque

Si vous tentez un appel d’API Travaux d’importation et qu’il vous manque des autorisations d’écriture sur l’un des types d’éléments de graphique 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 :

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}

Conseil

Pour obtenir un exemple de projet qui convertit des modèles, des jumeaux et des relations au format NDJSON pris en charge par l’API d’importation, consultez Générateur de NDJSON d’importation en bloc Azure Digital Twins. 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 (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éé.

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’objets 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 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 :

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 :