Jumeaux numériques et graphe de jumeaux

Cet article décrit les jumeaux numériques dans le contexte d’Azure Digital Twins, ainsi que la manière dont les relations qu’ils entretiennent peuvent former un graphe de jumeaux. Dans une solution Azure Digital Twins, les entités de votre environnement sont représentées par des jumeaux numériques. Un jumeau numérique est une instance de l’un de vos modèles personnalisés. Il peut être connecté à d’autres jumeaux numériques par le biais de relations pour former un graphique de jumeaux : ce graphique jumeau représente l’ensemble de votre environnement.

Conseil

« Azure Digital Twins » fait référence à ce service Azure dans son ensemble. « Jumeaux numériques » ou tout simplement « jumeau(s) » fait référence à des nœuds individuels au sein de votre instance du service.

Jumeaux numériques

Avant de pouvoir créer un jumeau numérique dans votre instance Azure Digital Twins, vous devez disposer d’un modèle chargé sur le service. Un modèle décrit l’ensemble de propriétés et de relations qu’un jumeau particulier peut avoir, entre autres. Pour obtenir les types d’informations définis dans un modèle, consultez Modèles personnalisés.

Après avoir créé et chargé un modèle, votre application cliente peut créer une instance de ce type. Cette instance est un jumeau numérique. Par exemple, après la création d’un modèle Étage, vous pouvez créer un ou plusieurs jumeaux numériques qui utilisent ce type (par exemple, un jumeau de type Étage appelé Rez-de-chaussée, un autre appelé Étage2, etc.).

Remarque

Les jumeaux numériques dans Azure Digital Twins sont différents des jumeaux d’appareil dans IoT Hub. Les jumeaux d’appareil IoT Hub sont souvent utilisés pour la description des aspects et des fonctionnalités d’un appareil lui-même, tandis que les jumeaux dans Azure Digital Twins sont des représentations plus conceptuelles qui peuvent stocker des insights définies par l’utilisateur sur un appareil ou sur de nombreux appareils associés.

Les appareils dans IoT Hub peuvent être connectés à Azure Digital Twins dans le cadre d’une solution de bout en bout qui représente vos appareils dans les services.

Relation : un graphique de jumeaux numériques

Les jumeaux sont connectés dans un graphique de jumeaux par leurs relations. Les relations qu’un jumeau peut avoir sont définies dans le cadre de son modèle.

Par exemple, le modèle Floor peut définir une contains relation qui cible des jumeaux de type Room. Avec cette définition, Azure Digital Twins vous permet de créer contains des relations entre n’importe quel jumeau Floor et n’importe quel jumeau room (y compris les jumeaux qui sont des sous-types room).

Le résultat de ce processus est un ensemble de nœuds (les jumeaux numériques) connectés par leurs périphéries (leurs relations) dans un graphique.

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éation avec des API

Cette section montre à quoi ressemble la création de jumeaux numériques et de relations à partir d’une application cliente. Il contient des exemples de SDK .NET qui utilisent les API DigitalTwins pour fournir un contexte plus contextuel sur ce qui se passe à l’intérieur de chacun de ces concepts.

Créer des jumeaux numériques

Vous trouverez ci-dessous un extrait de code client qui utilise les API DigitalTwins pour instancier un jumeau de type Salle avec un twinId qui est défini durant l’instanciation.

Vous pouvez initialiser les propriétés d’un jumeau lors de sa création, ou les définir ultérieurement. Pour créer un jumeau avec des propriétés initialisées, créez un document JSON qui fournit les valeurs d’initialisation nécessaires.

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

Vous pouvez également utiliser une classe d’assistance appelée BasicDigitalTwin pour stocker les champs de propriété dans un objet « jumeau » de manière plus directe, comme alternative à l’utilisation d’un dictionnaire. Pour plus d’informations sur la classe d’assistance et des exemples de son utilisation, consultez Créer un jumeau numérique.

Remarque

Bien que les propriétés de jumeau soient traitées comme facultatives et ne doivent pas obligatoirement être initialisées, tous les composants du jumeau doivent être définis lors de sa création. Il peut s’agir d’objets vides, mais les composants proprement dits doivent exister.

Créer des relations

Voici un exemple de code client qui utilise les API DigitalTwins pour créer une relation d’un jumeau numérique (le jumeau « source ») à un autre jumeau numérique (le jumeau « cible »).

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

Créer des jumeaux et des relations en bloc avec l’API Importer des travaux

Vous pouvez charger de nombreux jumeaux et relations dans un seul appel d’API à l’aide de l’API Importer des travaux. Les jumeaux et les relations créés avec cette API peuvent éventuellement inclure l’initialisation de leurs propriétés. Pour obtenir des instructions détaillées et des exemples qui utilisent cette API, consultez les instructions d’importation en bloc pour les jumeaux et les relations.

Supprimer des éléments de graphe

Pour supprimer des jumeaux et des relations spécifiques, utilisez les API DigitalTwins Delete et DigitalTwins DeleteRelationship (également disponibles en tant que commandes CLI et appels sdk).

Pour supprimer tous les modèles, jumeaux et relations dans une instance à la fois, utilisez l’API Supprimer les travaux.

Représentations JSON des éléments de graphique

Les données de relation et les données des jumeaux numériques sont toutes stockées au format JSON. Cela signifie que lorsque vous interrogez le graphique de jumeau dans votre instance Azure Digital Twins, le résultat est une représentation JSON des jumeaux numériques et des relations que vous avez créées.

Format JSON de jumeaux numériques

Lorsqu’il est représenté sous la forme d’un objet JSON, un jumeau numérique affiche les champs suivants :

Nom du champ	Description
$dtId	Chaîne fournie par l’utilisateur représentant l’ID du jumeau numérique
$etag	Champ HTTP standard attribué par le serveur web
$metadata.$model	L’ID de l’interface de modèle qui caractérise ce jumeau numérique
$metadata.<property-name>	Autres informations de métadonnées sur les propriétés du jumeau numérique
$metadata.<property-name>.lastUpdateTime	Date et heure auxquelles le message de mise à jour de la propriété a été traité par Azure Digital Twins.
$metadata.<property-name>.sourceTime	Propriété facultative accessible en écriture qui représente la date et l’heure auxquelles la mise à jour de la propriété a été observée. Cette propriété peut uniquement être écrite à l’aide de la version 2022-05-31 des API/SDK Azure Digital Twins et sa valeur doit respecter le format ISO 8601 de date et d’heure. Pour plus d’informations sur la mise à jour de cette propriété, consultez Mettre à jour le sourceTime d’une propriété.
<property-name>	Valeur d’une propriété au format JSON (string, type de nombre ou objet)
$relationships	URL du chemin de la collection des relations. Ce champ est absent si le jumeau numérique n’a pas de périphéries de relations sortantes.
<component-name>	Objet JSON contenant les valeurs de propriété et les métadonnées du composant, similaires à celles de l’objet racine. Cet objet existe même si le composant n’a pas de propriétés.
<component-name>.$metadata	Informations de métadonnées pour le composant, similaires aux $metadata au niveau de la racine
<component-name>.<property-name>	Valeur de la propriété du composant au format JSON (string, type de nombre ou objet)

Voici un exemple de jumeau numérique au format objet JSON. Ce jumeau a deux propriétés, Humidité et Température, et un composant appelé Thermostat.

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

Format JSON de la relation

Lorsqu’elle est représentée sous la forme d’un objet JSON, une relation d’un jumeau numérique affiche les champs suivants :

Nom du champ	Description
$relationshipId	Chaîne fournie par l’utilisateur représentant l’ID de cette relation. Cette chaîne est unique dans le contexte du jumeau numérique source, ce qui signifie également que sourceId + relationshipId est unique dans le contexte de l’instance Azure Digital Twins.
$etag	Champ HTTP standard attribué par le serveur web
$sourceId	ID du jumeau numérique source
$targetId	ID du jumeau numérique cible
$relationshipName	Nom de la relation.
<property-name>	[Facultatif] Valeur d’une propriété de cette relation, au format JSON (string, type de nombre ou objet)

Voici un exemple de relation au format objet JSON :

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

Étapes suivantes

Voir comment gérer des éléments graphiques avec les API Azure Digital Twins :

• Gérer les jumeaux numériques
• Gérer le graphe et les relations de jumeau

Ou découvrez comment interroger le graphe de jumeaux Azure Digital Twins pour obtenir des informations :

• Langage de requête