Partager via

Gérer les modèles Azure Digital Twins

  • Article

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 :

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 :

Screenshot of Azure Digital Twins Explorer showing a sample model graph.

Créer des modèles

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

Créer des modèles

Les modèles pour Azure Digital Twins sont écrits dans DTDL et enregistrés en tant que 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é, à charger 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 seront mis à jour à partir de capteurs de mouvement et de distributeurs de savon intelligents, et seront utilisés ensemble pour calculer une handwash percentage propriété. 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.

À la suite de cette méthode, vous pouvez définir des modèles pour les salles, les zones ou l’hôpital lui-même.

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

Utiliser les ontologies standard du secteur existantes

Une ontologie est un ensemble de modèles qui décrivent de manière complète un domaine donné, comme la fabrication, les structures de construction, les systèmes IoT, les villes intelligentes, les réseaux énergétiques, le contenu web, etc.

Si votre solution concerne un certain secteur qui utilise n’importe quelle sorte de norme de modélisation, envisagez de commencer par un ensemble pré-existant de modèles conçus pour votre secteur au lieu de concevoir vos modèles à partir de zéro. Microsoft a collaboré avec des experts du domaine pour créer des ontologies de modèle DTDL basées sur des normes du secteur, afin de réduire la réinvention et d’encourager la cohérence et la simplicité dans les solutions du secteur. 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’analyseur directement dans votre code C#. Vous pouvez également afficher l’exemple d’utilisation de l’analyseur dans le 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 sur le service. Il existe plusieurs façons de charger plusieurs modèles à la fois dans une seule transaction. Pour vous aider à choisir une stratégie, tenez compte de la taille de votre jeu de modèles lorsque vous passez au reste de cette section.

Charger de petits ensembles de modèles

Pour les jeux de modèles plus petits, vous pouvez charger plusieurs modèles à la fois à l’aide d’appels d’API individuels. Vous pouvez case activée la limite actuelle pour le nombre de modèles pouvant être chargés dans un seul appel d’API dans les limites d’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 à 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 jeux de modèles volumineux avec l’API Importer des travaux

Pour les jeux de modèles volumineux, 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 pour le 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 elles. Cette méthode nécessite l’utilisation de Stockage Blob Azure, ainsi que des 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) en tant que fichier NDJSON . La Models section vient immédiatement après Header la section, ce qui en fait la première section de données de graphe dans le fichier. Vous pouvez afficher un exemple de fichier d’importation et un exemple de projet pour créer ces fichiers dans l’introduction de l’API Importer des travaux.

Ensuite, le fichier doit être chargé dans un objet blob d’ajout dans Stockage Blob Azure. Pour obtenir des instructions sur la création d’un conteneur de stockage Azure, consultez Créer un conteneur. Ensuite, chargez le fichier à l’aide de votre méthode de chargement préférée (certaines options sont la commande AzCopy, Azure CLI ou le Portail Azure).

Une fois le fichier NDJSON chargé dans le conteneur, obtenez son URL dans le conteneur d’objets blob. Vous utiliserez 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 blob dans la Portail Azure :

Screenshot of the Azure portal showing the URL of a file in a storage container.

Ensuite, le fichier peut être utilisé dans un appel d’API Importer des travaux. Vous fournirez l’URL de stockage d’objets blob du fichier d’entrée, ainsi qu’une nouvelle URL de stockage d’objets blob pour indiquer où vous souhaitez 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. Par conséquent, 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 une fois qu’elles sont disponibles. 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 souhaitez supprimer tous les modèles, jumeaux et relations dans une instance à la fois, utilisez l’API Supprimer les 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 (comme dans, 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 DTDL 2 et 3 (raccourcies dans la documentation sur v2 et v3, respectivement). V3 est le choix recommandé en fonction 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 en tant que v2 ou v3 est le @context champ de l’interface. Pour convertir un modèle de v2 en v3, remplacez la dtmi:dtdl:context;2 valeur dtmi:dtdl:context;3de contexte par . Pour de nombreux modèles, il s’agit de la seule modification requise.
    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 avec 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é lors de la conversion du modèle en v3. Pour ce faire, commencez par remplacer le @context champ de l’interface d’une valeur unique 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 volumineuse, vous pouvez examiner les limites des différences entre DTDL v2 et v3.

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

Vous pouvez également envisager de nouvelles fonctionnalités de DTDL v3, telles que les propriétés de type tableau, la relaxation de version et les extensions de fonctionnalités supplémentaires, pour voir si l’une d’elles serait utile. Pour obtenir la liste complète des différences entre DTDL v2 et v3, consultez Modifications de la version 2 dans la description du langage DTDL v3.

Étapes suivantes

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