Gérer les modèles Azure Digital Twins

Cet article explique comment gérer les modèles dans votre instance Azure Digital Twins. Les opérations de gestion incluent le chargement, la validation, la récupération et la suppression des modèles.

Prérequis

Pour utiliser Azure Digital Twins dans cet article, vous avez besoin d’une instance Azure Digital Twins et des autorisations requises pour l’utiliser. Si vous disposez déjà d’une instance Azure Digital Twins configurée, vous pouvez utiliser cette instance et passer à la section suivante. Dans le cas contraire, suivez les instructions indiquées dans Configurer une instance et l’authentification. Les instructions contiennent des informations qui vous aideront à vérifier que vous avez correctement effectué chaque étape.

Une fois l’instance configurée, notez son nom d’hôte. Vous trouverez le nom d’hôte dans le portail Azure.

Interfaces développeur

Cet article montre comment effectuer différentes opérations de gestion à l’aide du kit SDK .NET (C#). Vous pouvez également créer les mêmes appels de gestion à l’aide des autres kits de langage SDK décrits dans les API Azure Digital Twins et kits SDK.

Les autres interfaces développeur qui peuvent être utilisées pour effectuer ces opérations sont les suivantes :

• Azure Digital Twins Explorer
• Appels de l’API REST
• Commandes Azure CLI

Remarque

Actuellement, Azure Digital Twins Explorer prend intégralement en charge les modèles DTDL v2, et prend en charge des fonctionnalités limitées pour les modèles DTDL v3.

Les modèles DTDL v3 peuvent être consultés dans le panneau Modèles, et les jumeaux créés avec des modèles DTDL v3 peuvent être consultés et modifiés (y compris ceux avec des propriétés de tableau). Toutefois, les modèles DTDL v3 ne s’afficheront pas dans le panneau Model Graph, et ne peuvent pas être importés à l’aide d’Azure Digital Twins Explorer. Pour importer des modèles DTDL v3 dans votre instance, utilisez une autre interface de développement comme les API et les kits SDK ou Azure CLI.

Visualisation

Azure Digital Twins Explorer est un outil visuel permettant d’explorer les données dans votre graphique Azure Digital Twins. Vous pouvez utiliser l’explorateur pour afficher, interroger et modifier vos modèles, vos jumeaux et vos relations.

Pour en savoir plus sur l’outil Azure Digital Twins Explorer, consultez Azure Digital Twins Explorer. Pour obtenir des instructions détaillées sur l’utilisation de ses fonctionnalités, consultez Utilisation d’Azure Digital Twins Explorer.

Voici à quoi ressemble la visualisation :

Créer des modèles

Vous pouvez créer vos propres modèles à partir de zéro ou utiliser les ontologies existantes disponibles pour votre secteur d’activité.

Créer des modèles

Les modèles pour Azure Digital Twins sont écrits en DTDL et enregistrés sous forme de fichiers JSON. Il existe également une extension DTDL disponible pour Visual Studio Code. Cette extension fournit une fonctionnalité de validation de la syntaxe et d’autres fonctionnalités facilitant l’écriture de documents DTDL.

Prenons l’exemple d’un hôpital souhaitant disposer d’une représentation numérique des pièces de son bâtiment. Chaque pièce contient un distributeur de savon intelligent permettant de contrôler le lavage des mains, et des capteurs pour suivre le trafic.

La première étape de la solution consiste à créer des modèles pour représenter chaque aspect de l’hôpital. Dans ce scénario, la chambre d’un patient peut être décrite comme suit :

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Remarque

Il s’agit d’un exemple de corps pour un fichier JSON dans lequel un modèle est défini et enregistré, et doit être chargé dans le cadre d’un projet client. En revanche, l’appel d’API REST prend un tableau de définitions de modèle comme celle ci-dessus (qui est mappée à un IEnumerable<string> dans le kit de développement logiciel .NET). Par conséquent, pour utiliser ce modèle dans l’API REST directement, entourez-le avec des crochets.

Ce modèle définit un nom et un ID unique pour chaque chambre de patient, ainsi que des propriétés représentant le nombre de visiteurs et l’état de lavage des mains. Ces compteurs sont mis à jour à partir des capteurs de mouvement et des distributeurs de savon intelligents. Ils sont utilisés ensemble pour calculer une propriété handwash percentage. Le modèle définit également une relation hasDevices, qui sera utilisée pour connecter tout jumeau numérique basé sur ce modèle Room aux périphériques réels.

Remarque

Azure Digital Twins ne prend pas en charge certaines fonctionnalités DTDL, notamment l’attribut writable au niveau des propriétés et des relations, ainsi que minMultiplicity et maxMultiplicity pour les relations. Pour plus d’informations, consultez les Notes DTDL spécifiques du service.

En suivant cette méthode, vous pouvez définir des modèles pour l’hôpital entier, des services ou des zones.

Si votre objectif est de créer un ensemble de modèles complet qui décrit votre domaine sectoriel, déterminez s’il existe une ontologie sectorielle existante que vous pouvez utiliser pour faciliter la création de modèles. La section suivante décrit plus en détail les ontologies sectorielles.

Utiliser les ontologies existantes basées sur les standard sectoriels

Une ontologie est un ensemble de modèles qui décrit de manière exhaustive un domaine donné, comme la fabrication, la construction de structures, les systèmes IoT, les villes intelligentes, les réseaux d’énergie, le contenu web, etc.

Si votre solution cible un certain secteur d’activité qui utilise une sorte de standard de modélisation, commencez avec un ensemble préexistant de modèles conçus pour votre secteur au lieu de concevoir vos modèles à partir de zéro. Microsoft, en partenariat avec des experts de domaine, a créé des ontologies de modèle DTDL basées sur les standard du secteur afin de limiter la réinvention, et d’encourager la cohérence et la simplicité des solutions sectorielles. Pour en savoir plus sur ces ontologies, y compris leur utilisation et les ontologies disponibles dès maintenant, dans Qu’est-ce qu’une ontologie ?.

Valider la syntaxe

Après la création d’un modèle, il est recommandé de valider les modèles hors connexion avant de les charger sur une instance Azure Digital Twins.

Pour vous aider à valider vos modèles, une bibliothèque d'analyse DTDL côté client .NET est fournie sur NuGet : DTDLParser. Vous pouvez utiliser la bibliothèque d’analyse directement dans votre code C#. Vous pouvez également consulter un exemple d’utilisation de l’analyseur dans DTDLParserResolveSample dans GitHub.

Charger des modèles

Une fois les modèles créés, vous pouvez les charger vers l’instance Azure Digital Twins.

Lorsque vous êtes prêt à charger un modèle, vous pouvez utiliser l’extrait de code suivant pour le kit de développement logiciel (SDK) .NET: :

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

Lors du chargement, les fichiers de modèle sont validés par le service.

Vous devez généralement charger plusieurs modèles dans le service. Il y a plusieurs façons de charger un grand nombre de modèles à la fois dans une seule transaction. Pour vous aider à choisir une stratégie, tenez compte de la taille de votre ensemble de modèles quand vous passez au reste de cette section.

Charger de petits ensembles de modèles

Pour les ensembles de modèles plus petits, vous pouvez charger plusieurs modèles à la fois en utilisant des appels d’API individuels. Vous pouvez vérifier la limite actuelle du nombre de modèles que vous pouvez charger dans un seul appel d’API dans Limites Azure Digital Twins.

Si vous utilisez le kit de développement logiciel (SDK), vous pouvez charger plusieurs fichiers de modèle avec la méthode CreateModels comme suit :

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Si vous utilisez les API REST ou Azure CLI, vous pouvez charger plusieurs modèles en plaçant plusieurs définitions de modèle dans un seul fichier JSON pour les charger ensemble. Dans ce cas, les modèles doivent être placés dans un tableau JSON dans le fichier, comme dans l’exemple suivant :

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Charger des grands ensembles de modèles avec l’API Importer des travaux

Pour les grands ensembles de modèles, vous pouvez utiliser l’API Importer des travaux pour charger plusieurs modèles à la fois dans un seul appel d’API. L’API peut accepter simultanément jusqu’à la limite Azure Digital Twins du nombre de modèles dans une instance, et elle réorganise automatiquement les modèles si nécessaire pour résoudre les dépendances entre eux. Cette méthode nécessite l’utilisation du Stockage Blob Azure, ainsi que d’autorisations d’écriture dans votre instance Azure Digital Twins pour les modèles et les travaux en bloc.

Conseil

L’API Importer des travaux permet également d’importer des jumeaux et des relations dans le même appel pour créer toutes les parties d’un graphique à la fois. Pour plus d’informations sur ce processus, consultez Charger des modèles, des jumeaux et des relations en bloc avec l’API Importer des travaux.

Pour importer des modèles en bloc, vous devez structurer vos modèles (et toutes les autres ressources incluses dans le travail d’importation en bloc) dans un fichier NDJSON. La section Models vient immédiatement après la section Header, ce qui en fait la première section de données de graphe du fichier. Vous pouvez consulter un exemple de fichier d’importation et un exemple de projet pour la création de ces fichiers dans Présentation de l’API Importer des travaux.

Ensuite, le fichier doit être chargé dans un blob d’ajout dans le Stockage Blob Azure. Pour savoir comment créer un conteneur de Stockage Azure, consultez Créer un conteneur. Ensuite, chargez le fichier en utilisant votre méthode de chargement préférée (parmi les options vous avez la commande AzCopy, Azure CLI ou le portail Azure).

Une fois le fichier NDJSON chargé dans le conteneur, obtenez son URL dans le conteneur de blobs. Vous utilisez cette valeur plus loin dans le corps de l’appel d’API d’importation en bloc.

Voici une capture d’écran montrant la valeur d’URL d’un fichier de blob dans le portail Azure :

Ensuite, le fichier peut être utilisé dans un appel de l’API Importer des travaux. Vous fournissez l’URL de stockage blob du fichier d’entrée, ainsi qu’une nouvelle URL de stockage blob pour indiquer où stocker le journal de sortie lors de sa création par le service.

Récupérer des modèles

Vous pouvez répertorier et récupérer des modèles stockés sur votre instance Azure Digital Twins.

Vos options sont les suivantes :

• Récupérer un seul modèle
• Récupérer tous les modèles
• Récupérer les métadonnées et les dépendances pour les modèles

Voici quelques exemples d’appels :

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

Tous les appels de SDK pour récupérer les modèles retournent des objets DigitalTwinsModelData. DigitalTwinsModelData contient les métadonnées relatives au modèle stocké dans l’instance Azure Digital Twins, par exemple le nom, le DTMI et la date de création du modèle. L’objet DigitalTwinsModelData comprend également le modèle lui-même. Par conséquent, en fonction des paramètres, vous pouvez utiliser les appels de récupération pour récupérer uniquement les métadonnées (utile lorsque vous souhaitez afficher une liste d’interfaces utilisateur des outils disponibles, par exemple) ou le modèle entier.

L’appel RetrieveModelWithDependencies retourne non seulement le modèle demandé, mais également tous les modèles dont il dépend.

Les modèles ne sont pas nécessairement retournés exactement sous la même forme que dans le document où ils ont été chargés. Azure Digital Twins garantit uniquement que la forme de retour est sémantiquement équivalente.

Mettre à jour les modèles

Cette section décrit les points à prendre en considération pour mettre à jour des modèles ainsi que les différentes stratégies de mise à jour.

Avant la mise à jour : ayez une réflexion qui prend en compte le contexte de votre solution entière

Avant de procéder à des mises à jour de vos modèles, nous vous recommandons d’avoir une réflexion globale au sujet de votre solution et de l’impact des modifications que vous souhaitez apporter aux modèles. Dans une solution Azure Digital Twins, les modèles sont souvent interconnectés. Il est donc important de garder à l’esprit l’éventualité de modifications en cascade : quand vous mettez à jour un modèle, vous devrez peut-être également mettre à jour plusieurs autres modèles. Non seulement la mise à jour des modèles a un impact sur les jumeaux qui utilisent les modèles modifiés, mais elle peut aussi impacter le code d’entrée et de traitement, les applications clientes et les rapports automatisés.

Voici quelques recommandations utiles pour gérer vos transitions de modèles sans problème :

• Au lieu de considérer les modèles comme des entités distinctes, songez à développer votre ensemble de modèles quand cela est approprié pour que les modèles et leurs relations soient toujours à jour les uns par rapport aux autres.
• Traitez les modèles comme du code source et gérez-les dans le contrôle de code source. Travaillez sur vos modèles et leurs modifications avec la même rigueur et attention que pour tout autre code de votre solution.

Lorsque vous êtes prêt à poursuivre ce processus de mise à jour de vos modèles, référez-vous au reste de cette section, qui décrit les stratégies de mise à jour que vous pouvez implémenter.

Stratégies de mise à jour des modèles

Une fois qu’un modèle est chargé sur votre instance Azure Digital Twins, l’interface du modèle est immuable, c’est-à-dire qu’elle ne peut pas être modifiée selon le processus de « modification » habituel des modèles. Azure Digital Twins n’autorise pas non plus le rechargement du même modèle strictement identique si un modèle correspondant existe déjà dans l’instance.

Pour apporter des modifications à un modèle (par exemple, mettre à jour displayName ou description, ou ajouter et supprimer des propriétés), vous ne pouvez le faire qu’en remplaçant le modèle d’origine.

Deux stratégies sont possibles pour remplacer un modèle :

• Stratégie 1 : Charger une nouvelle version du modèle. Cette stratégie consiste à charger le modèle, en changeant le numéro de version, puis à mettre à jour les jumeaux pour qu’ils utilisent ce nouveau modèle. Les deux versions du modèle, l’ancienne et la nouvelle, coexistent dans votre instance jusqu’à ce que vous en supprimiez une.
  • Utilisez cette stratégie quand vous souhaitez uniquement mettre à jour certains des jumeaux qui utilisent le modèle, ou quand vous voulez vous assurer que les jumeaux restent toujours conformes à leurs modèles et accessibles en écriture durant la transition du modèle.
• Stratégie 2 : Supprimer l’ancien modèle et recharger le nouveau. Cette stratégie consiste à supprimer le modèle d’origine et à charger à la place le nouveau modèle, en utilisant les mêmes nom et ID (valeur DTMI). L’ancien modèle est alors entièrement remplacé par le nouveau.
  • Utilisez cette stratégie quand vous souhaitez mettre à jour simultanément tous les jumeaux qui utilisent ce modèle, en plus de tout le code réagissant aux modèles. Si la mise à jour d’un modèle comporte un changement cassant, les jumeaux ne seront pas conformes à leurs modèles pendant une brève période, le temps de la transition des jumeaux de l’ancien modèle vers le nouveau. La conséquence est que les jumeaux ne pourront pas être mis à jour tant que le nouveau modèle n’aura pas été chargé et que les jumeaux ne seront pas conformes à ce modèle.

Remarque

Il est déconseillé de faire des changements cassants dans vos modèles en dehors de la phase de développement.

Lisez les sections suivantes pour découvrir chaque option de stratégie plus en détail.

Stratégie 1 : Charger une nouvelle version du modèle

Cette option consiste à créer une autre version du modèle et à charger cette nouvelle version dans votre instance.

Cette opération ne remplace pas les versions antérieures du modèle et plusieurs versions du modèle coexistent dans votre instance jusqu’à ce que vous les supprimiez. Étant donné que la nouvelle version et l’ancienne version du modèle coexistent, les jumeaux peuvent utiliser l’une ou l’autre de ces versions. Autrement dit, le chargement d’une nouvelle version d’un modèle n’impacte pas automatiquement les jumeaux existants. Les jumeaux existants sont conservés comme instances de l’ancienne version du modèle. Vous pouvez mettre à jour ces jumeaux vers la nouvelle version du modèle en leur appliquant un correctif.

Pour utiliser cette stratégie, effectuez les étapes expliquées ci-dessous.

1. Créer et charger une nouvelle version du modèle

Pour créer une nouvelle version d’un modèle existant, commencez par le DTDL du modèle d’origine. Mettez à jour, ajoutez ou supprimez les champs que vous souhaitez modifier.

Ensuite, marquez ce modèle comme version plus récente en mettant à jour son champ id. La dernière section de l’ID de modèle, après le point-virgule (;), représente le numéro de modèle. Pour indiquer que ce modèle est une version plus récente, incrémentez le nombre à la fin de la valeur id en choisissant un nombre supérieur au numéro de la version actuelle.

Par exemple, si votre ID de modèle précédent ressemble à ceci :

"@id": "dtmi:com:contoso:PatientRoom;1",

La version 2 de ce modèle peut se présenter comme suit :

"@id": "dtmi:com:contoso:PatientRoom;2",

Ensuite, chargez la nouvelle version du modèle dans votre instance.

Cette version du modèle devient alors disponible dans votre instance pour les jumeaux numériques. Elle ne remplace pas les versions antérieures du modèle. Ainsi, plusieurs versions du modèle coexistent maintenant dans votre instance.

2. Mettre à jour les éléments graphiques en fonction des besoins

Ensuite, mettez à jour les jumeaux et leurs relations dans votre instance afin qu’ils utilisent la nouvelle version du modèle à la place de l’ancienne.

Aidez-vous des instructions ci-après pour mettre à jour les jumeaux et mettre à jour les relations. L’opération de correction pour mettre à jour le modèle d’un jumeau ressemble à ceci :

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Important

Quand vous mettez à jour des jumeaux, utilisez le même correctif pour mettre à jour à la fois l’ID du modèle (avec la nouvelle version du modèle) et chaque champ devant être modifié sur les jumeaux pour les rendre conformes au nouveau modèle.

Vous pouvez aussi avoir besoin de mettre à jour les relations et d’autres modèles dans votre instance qui référencent ce modèle, afin qu’ils référencent bien la nouvelle version du modèle. Pour cela, vous devez effectuer une autre opération de mise à jour du modèle. Revenez au début de cette section et répétez le processus pour chacun des autres modèles nécessitant une mise à jour.

3. (Facultatif) Désaffecter ou supprimer l’ancienne version du modèle

Si vous n’avez plus besoin de l’ancienne version du modèle, vous pouvez la désaffecter. Avec cette action, le modèle est conservé dans l’instance, mais il ne peut pas être utilisé pour créer d’autres jumeaux numériques.

Vous pouvez aussi supprimer complètement l’ancien modèle si vous ne souhaitez pas le conserver dans l’instance.

Les deux liens ci-dessus renvoient vers les sections contenant un exemple de code et des informations relatives à la désaffectation et à la suppression de modèles.

Stratégie 2 : Supprimer l’ancien modèle et recharger le nouveau

Au lieu d’incrémenter la version d’un modèle, vous pouvez supprimer complètement un modèle et recharger un modèle modifié dans l’instance.

Comme Azure Digital Twins ne se souvient pas que l’ancien modèle a déjà été chargé, cette action revient à charger un modèle entièrement nouveau. Les jumeaux qui utilisent le modèle basculent automatiquement vers la nouvelle définition dès qu’elle est disponible. En fonction des différences qu’il y a entre la nouvelle définition et l’ancienne, ces jumeaux peuvent avoir des propriétés et des relations qui font référence à la définition supprimée et qui ne sont pas valides avec la nouvelle définition. Dans ce cas, vous devez les corriger afin qu’ils restent valides.

Pour utiliser cette stratégie, effectuez les étapes expliquées ci-dessous.

1. Supprimer l’ancien modèle

Étant donné qu’Azure Digital Twins n’autorise pas l’existence de modèles ayant le même ID, commencez par supprimer le modèle d’origine de votre instance.

Remarque

Si vous avez d’autres modèles qui dépendent de ce modèle (par héritage ou certains composants), vous devez supprimer ces références avant de supprimer le modèle. Vous pouvez mettre à jour ces modèles dépendants pour supprimer temporairement les références dans un premier temps, ou supprimer les modèles dépendants et les recharger lors d’une étape ultérieure.

Aidez-vous des instructions suivantes pour supprimer votre modèle d’origine. Cette action laisse les jumeaux qui utilisaient ce modèle temporairement « orphelins », car ils utilisent désormais un modèle qui n’existe plus. Cet état sera corrigé à l’étape suivante lors du rechargement du modèle mis à jour.

2. Créer et charger le nouveau modèle

Commencez par le DTDL du modèle d’origine. Mettez à jour, ajoutez ou supprimez les champs que vous souhaitez modifier.

Ensuite, chargez le modèle dans l’instance, comme s’il s’agissait d’un tout nouveau modèle chargé pour la première fois.

3. Mettre à jour les éléments du graphe si nécessaire

Maintenant que votre nouveau modèle a été chargé à la place de l’ancien, les jumeaux dans votre graphe commenceront automatiquement à utiliser la nouvelle définition de modèle après l’expiration et la réinitialisation de la mise en cache dans l’instance. Ce processus peut prendre de dix à quinze minutes ou plus en fonction de la taille de votre graphe. Après cela, les propriétés nouvelles et modifiées de votre modèle seront accessibles, au contraire des propriétés supprimées.

Remarque

Si vous avez supprimé d’autres modèles dépendants précédemment afin de supprimer le modèle d’origine, rechargez-les maintenant après la réinitialisation du cache. Si vous avez mis à jour les modèles dépendants pour supprimer temporairement les références au modèle d’origine, vous pouvez les mettre de nouveau à jour avec la référence.

Ensuite, mettez à jour les jumeaux et les relations dans votre instance afin que leurs propriétés correspondent aux propriétés définies par le nouveau modèle. À ce stade, les jumeaux qui ne correspondent pas à leur modèle peuvent toujours être lus, mais ils ne sont pas accessibles en écriture. Pour plus d’informations sur l’état des jumeaux sans modèle valide, consultez Jumeaux sans modèles.

Il existe deux façons de mettre à jour les jumeaux et les relations du nouveau modèle afin de les rendre de nouveau accessibles en écriture :

• Corrigez les jumeaux et les relations de manière à ce qu’ils soient conformes au nouveau modèle. Aidez-vous des instructions ci-après pour mettre à jour les jumeaux et mettre à jour les relations.
  • Si vous avez ajouté des propriétés, il n’est pas nécessaire de mettre à jour les jumeaux et les relations avec les nouvelles valeurs, car les jumeaux qui n’ont pas les nouvelles valeurs restent valides. Vous pouvez toutefois les corriger si vous souhaitez ajouter des valeurs pour les nouvelles propriétés.
  • Si vous avez supprimé des propriétés, il est nécessaire de corriger les jumeaux pour supprimer les propriétés qui ne sont maintenant plus valides avec le nouveau modèle.
  • Si vous avez mis à jour des propriétés, il est nécessaire de corriger les jumeaux pour mettre à jour les valeurs des propriétés modifiées afin qu’elles soient valides avec le nouveau modèle.
• Supprimez les jumeaux et les relations qui utilisent le modèle, puis recréez-les. Aidez-vous des instructions suivantes pour supprimer les jumeaux et recréer les jumeaux, et supprimer les relations et recréer les relations.
  • Vous souhaiterez peut-être effectuer cette opération si vous modifiez largement le modèle et qu’il sera difficile de mettre à jour les jumeaux existants de manière correcte. Toutefois, recréer entièrement les jumeaux et les relations peut s’avérer compliqué si vous avez beaucoup de jumeaux qui sont interconnectés par de nombreuses relations.

Supprimer des modèles

Les modèles peuvent être supprimés du service de l’une des deux manières suivantes :

• Désaffectation : une fois qu’un modèle est désaffecté, vous ne pouvez plus l’utiliser pour créer de nouveaux jumeaux numériques. Les représentations numériques existantes utilisant déjà ce modèle ne sont pas affectées. vous pouvez donc toujours les mettre à jour avec des éléments tels que les modifications de propriétés et l’ajout ou la suppression de relations.
• Suppression : cette opération supprime complètement le modèle de la solution. Les représentations qui utilisaient ce modèle ne sont plus associées à un modèle valide. Elles sont donc traitées comme si elles n’en avaient pas. Vous pouvez toujours lire ces jumeaux, mais pas les mettre à jour tant qu’ils ne sont pas réaffectés à un autre modèle.

Ces deux opérations sont des fonctionnalités distinctes qui n’ont pas d’impact l’une sur l’autre, mais elles peuvent être utilisées ensemble pour supprimer un modèle progressivement.

Remarque

Si vous voulez supprimer tous les modèles, jumeaux et relations d’une instance à la fois, utilisez l’API Supprimer des travaux.

Désaffectation

Pour désaffecter un modèle, vous pouvez utiliser la méthode DecommissionModel fournie dans le SDK :

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Vous pouvez également effectuer cette opération par un appel de l’API REST DigitalTwinModels Update. La propriété decommissioned est la seule propriété qui peut être remplacée par cet appel d’API. Le document JSON Patch ressemble à ceci :

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

L’état de désaffectation d’un modèle est inclus dans les enregistrements ModelData retournés par les API de récupération de modèle.

Suppression

Vous pouvez supprimer tous les modèles de votre instance d’une seule traite, ou vous pouvez le faire sur une base individuelle.

Pour obtenir un exemple de suppression de tous les modèles en même temps, consultez le dépôt Exemples Azure Digital Twins de bout en bout dans GitHub. Le fichier CommandLoop.cs contient une fonction CommandDeleteAllModels dont le code supprime la totalité des modèles dans l’instance.

Pour supprimer les modèles de façon individuelle, aidez-vous des instructions et des informations fournies dans la suite de cette section.

Avant la suppression : Conditions requises pour la suppression

En règle générale, les modèles peuvent être supprimés à tout moment.

L’exception concerne les modèles dont dépendent d’autres modèles, qu’il s’agisse d’une relation extends ou en tant que composant. Par exemple, si un modèle ConferenceRoom étend un modèle Room, et qu’il possède un modèle ACUnit en tant que composant, vous ne pouvez pas supprimer Room ou ACUnit avant que ConferenceRoom ne supprime leurs références respectives.

Pour ce faire, vous pouvez mettre à jour le modèle dépendant pour supprimer les dépendances, ou supprimer complètement le modèle dépendant.

Durant la suppression : Processus de suppression

Même si un modèle répond aux exigences pour une suppression immédiate, vous voudrez peut-être suivre quelques étapes préliminaires pour éviter des conséquences inattendues pour la représentation numérique. Voici quelques étapes qui peuvent vous aider à gérer le processus :

1. Tout d’abord, désaffectez le modèle
2. Attendez quelques minutes, pour vous assurer que le service a bien traité toutes les demandes de création de représentations de dernière minute envoyées avant la désaffectation
3. Interrogez les représentations par modèle pour voir toutes les représentations utilisant le modèle désormais désactivé
4. Supprimez les représentations si vous n’en avez plus besoin ou bien liez-les à un nouveau modèle si nécessaire. Vous pouvez également choisir de conserver les jumeaux seuls, auquel cas ils deviennent des jumeaux sans modèle une fois le modèle supprimé. Consultez la section suivante pour connaître les implications de cet état.
5. Patientez quelques minutes pour vous assurer que les modifications ont été répercutées
6. Supprimer le modèle

Pour supprimer un modèle, vous pouvez utiliser l’appel de SDK DeleteModel :

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Vous pouvez aussi supprimer un modèle à l’aide de l’appel d'API REST DigitalTwinModels Delete.

Après la suppression : Représentations sans modèle

Une fois qu’un modèle est supprimé, les représentations numériques qui l’utilisaient sont désormais considérées comme sans modèle. Il n’existe aucune requête vous permettant de lister tous les jumeaux dans cet état, mais vous pouvez toujours interroger les jumeaux par le modèle supprimé pour connaître les jumeaux concernés.

Voici une vue d’ensemble de ce que vous pouvez et ne pouvez pas faire avec des jumeaux sans modèle.

Choses que vous pouvez faire :

• Interroger la représentation
• Lire les propriétés
• Lire les relations sortantes
• Ajouter et supprimer des relations entrantes (d’autres jumeaux peuvent toujours former des relations à ce jumeau)
  • La target dans la définition de la relation peut toujours refléter le DTMI du modèle supprimé. Une relation sans cible définie peut également fonctionner ici.
• Supprimer les relations
• Supprimer la représentation

Choses que vous ne pouvez pas faire :

• Modifier les relations sortantes (autrement dit les relations de ce jumeau vers d’autres jumeaux)
• Modifier les propriétés

Après la suppression : recharger un modèle

Une fois qu’un modèle a été supprimé, vous pouvez décider de charger un nouveau modèle ayant un ID identique à celui que vous avez supprimé. Voici ce qui se passe dans ce cas.

• Du point de vue du magasin de solutions, cette opération revient à charger un modèle entièrement nouveau. Le service ne se rappelle pas du chargement de l’ancien modèle.
• S’il reste des jumeaux dans le graphe qui référencent le modèle supprimé, ces jumeaux ne sont plus orphelins, car l’ID de ce modèle est de nouveau valide avec la nouvelle définition. Cependant, si la nouvelle définition du modèle est différente de la définition du modèle supprimée, il est possible que ces jumeaux possèdent des propriétés et des relations qui correspondent à la définition supprimée et qui ne sont pas valides avec la nouvelle définition.

Azure Digital Twins n’empêche pas cet état ; aussi, veillez à corriger les jumeaux de sorte qu’ils restent valides après le changement de la définition du modèle.

Convertir des modèles v2 en v3

Azure Digital Twins prend en charge les versions 2 et 3 de DTDL (abrégées respectivement en v2 et v3 dans la documentation). V3 est le choix recommandé en raison de ses fonctionnalités étendues. Cette section explique comment mettre à jour un modèle DTDL v2 existant vers DTDL v3.

1. Mettez à jour le contexte. La fonctionnalité principale qui identifie un modèle comme v2 ou v3 est le champ @context dans l’interface. Pour convertir un modèle de v2 en v3, remplacez la valeur de contexte dtmi:dtdl:context;2 par dtmi:dtdl:context;3. Pour de nombreux modèles, il s’agit du seul changement nécessaire.
   1. Valeur dans v2 : "@context": "dtmi:dtdl:context;2"
   2. Valeur dans v3 : "@context": "dtmi:dtdl:context;3".
2. Si nécessaire, mettez à jour les types sémantiques. Dans DTDL v2, les types sémantiques sont pris en charge en mode natif. Dans DTDL v3, ils sont inclus dans l’extension de fonctionnalité QuantitativeTypes. Par conséquent, si votre modèle v2 a utilisé des types sémantiques, vous devez ajouter l’extension de fonctionnalité pendant la conversion du modèle en v3. Pour ce faire, commencez par remplacer le champ monovaleur @context dans l’interface par un tableau de valeurs, puis ajoutez la valeur dtmi:dtdl:extension:quantitativeTypes;1.
   1. Valeur dans v2 : "@context": "dtmi:dtdl:context;2"
   2. Valeur dans v3 : "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. Si nécessaire, tenez compte des limites de taille. V2 et v3 ont des limites de taille différentes. Par conséquent, si votre interface est très grande, vous pouvez passer en revue les limites décrites dans les différences entre DTDL v2 et v3.

Après ces changements, un ancien modèle DTDL v2 a été converti en modèle DTDL v3.

Vous pouvez également passer en revue les nouvelles fonctionnalités de DTDL v3, comme les propriétés de type de tableau, la relaxation de version et les extensions de fonctionnalité supplémentaires, pour voir si elles représentent un ajout bénéfique. Pour obtenir la liste complète des différences entre DTDL v2 et v3, consultez Changements par rapport à la Version 2 dans la description du langage DTDL v3.

Remarque

Actuellement, Azure Digital Twins Explorer prend intégralement en charge les modèles DTDL v2, et prend en charge des fonctionnalités limitées pour les modèles DTDL v3.

Les modèles DTDL v3 peuvent être consultés dans le panneau Modèles, et les jumeaux créés avec des modèles DTDL v3 peuvent être consultés et modifiés (y compris ceux avec des propriétés de tableau). Toutefois, les modèles DTDL v3 ne s’afficheront pas dans le panneau Model Graph, et ne peuvent pas être importés à l’aide d’Azure Digital Twins Explorer. Pour importer des modèles DTDL v3 dans votre instance, utilisez une autre interface de développement comme les API et les kits SDK ou Azure CLI.

Étapes suivantes

Découvrez comment créer et gérer des représentations numériques basées sur vos modèles :

• Gérer les jumeaux numériques