Digitale dubbels en hun tweelinggrafiek

Artikel
01/03/2024

In dit artikel wordt beschreven wat digitale dubbels zijn in de context van Azure Digital Twins en hoe relaties tussen deze dubbels een dubbelgrafiek kunnen vormen. In een Azure Digital Twins-oplossing worden de entiteiten in uw omgeving vertegenwoordigd door digitale dubbels. Een digitale dubbel is een exemplaar van een van uw aangepaste modellen. Het kan worden verbonden met andere digitale dubbels via relaties om een tweelinggrafiek te vormen: deze tweelinggrafiek is de weergave van uw hele omgeving.

Tip

'Azure Digital Twins' verwijst naar deze Azure-service als geheel. 'Digitale dubbel(en)' of alleen 'dubbel(en)' verwijst naar afzonderlijke dubbelknooppunten binnen uw exemplaar van de service.

Digitale tweelingen

Voordat u een digitale dubbel kunt maken in uw Azure Digital Twins-exemplaar, moet u een model uploaden naar de service. Een model beschrijft onder andere de set eigenschappen en relaties die een bepaalde dubbel kan hebben. Zie Aangepaste modellen voor de typen informatie die zijn gedefinieerd in een model.

Nadat u een model hebt gemaakt en geüpload, kan uw client-app een exemplaar van het type maken. Dit exemplaar is een digitale dubbel. Nadat u bijvoorbeeld een model van Floor hebt gemaakt, kunt u een of meer digitale dubbels maken die dit type gebruiken (zoals een floor-type dubbel genaamd GroundFloor, een andere met de naam Floor2, enzovoort).

Notitie

Digitale dubbels in Azure Digital Twins verschillen van apparaatdubbels in IoT Hub. IoT Hub-apparaatdubbels richten zich vaak op het beschrijven van de aspecten en mogelijkheden van een apparaat zelf, terwijl tweelingen in Azure Digital Twins meer conceptuele weergaven zijn waarmee door de gebruiker gedefinieerde inzichten over een apparaat of veel gerelateerde apparaten kunnen worden opgeslagen.

Apparaten in IoT Hub kunnen worden verbonden met Azure Digital Twins als onderdeel van een end-to-end-oplossing die uw apparaat vertegenwoordigt in alle services.

Relaties: een grafiek van digitale dubbels

Tweelingen zijn verbonden met een tweelinggrafiek door hun relaties. De relaties die een tweeling kan hebben, worden gedefinieerd als onderdeel van het model.

Het model Floor kan bijvoorbeeld een contains relatie definiëren die gericht is op tweelingen van het type Ruimte. Met deze definitie kunt u met Azure Digital Twins relaties maken contains van elke floordubbel naar elke kamerdubbel (inclusief tweelingen met roomsubtypen).

Het resultaat van dit proces is een set knooppunten (de digitale dubbels) die zijn verbonden via randen (hun relaties) in een grafiek.

Visualisatie

Azure Digital Twins Explorer is een visueel hulpmiddel voor het verkennen van de gegevens in uw Azure Digital Twins-grafiek. U kunt de verkenner gebruiken om uw modellen, tweelingen en relaties weer te geven, op te vragen en te bewerken.

Zie Azure Digital Twins Explorer voor meer informatie over het hulpprogramma Azure Digital Twins Explorer. Zie Azure Digital Twins Explorer gebruiken voor gedetailleerde stappen voor het gebruik van de functies.

De visualisatie ziet er als volgt uit:

Maken met de API's

In deze sectie ziet u hoe het eruitziet om digitale dubbels en relaties te maken vanuit een clienttoepassing. Het bevat .NET SDK-voorbeelden die gebruikmaken van de DigitalTwins-API's, om meer context te bieden over wat er in elk van deze concepten gebeurt.

Digitale tweelingen maken

Hieronder ziet u een codefragment van de clientcode die gebruikmaakt van de DigitalTwins-API's om een dubbel van het type Ruimte te instantiëren met een twinId ruimte die tijdens de instantiëring is gedefinieerd.

U kunt de eigenschappen van een dubbel initialiseren wanneer deze wordt gemaakt of later instellen. Als u een dubbel met geïnitialiseerde eigenschappen wilt maken, maakt u een JSON-document met de benodigde initialisatiewaarden.

// 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}");
    }
}

U kunt ook een helperklasse gebruiken die wordt aangeroepen BasicDigitalTwin om eigenschapsvelden in een dubbelobject rechtstreeks op te slaan, als alternatief voor het gebruik van een woordenlijst. Zie Een digitale dubbel maken voor meer informatie over de helperklasse en voorbeelden van het gebruik.

Notitie

Hoewel dubbeleigenschappen als optioneel worden behandeld en dus niet hoeven te worden geïnitialiseerd, moeten alle onderdelen op de tweeling worden ingesteld wanneer de dubbel wordt gemaakt. Ze kunnen lege objecten zijn, maar de onderdelen zelf moeten bestaan.

Relaties maken

Hier volgt een voorbeeld van clientcode die gebruikmaakt van de DigitalTwins-API's om een relatie te bouwen van één digitale dubbel (de 'brondubbel') naar een andere digitale dubbel (de 'doeldubbel').

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);
}

Dubbels en relaties bulksgewijs maken met de IMPORT Jobs-API

U kunt veel dubbels en relaties uploaden in één API-aanroep met behulp van de IMPORT Jobs-API. Tweelingen en relaties die met deze API zijn gemaakt, kunnen eventueel initialisatie van hun eigenschappen bevatten. Zie instructies voor bulksgewijs importeren voor tweelingen en relaties voor gedetailleerde instructies en voorbeelden die gebruikmaken van deze API.

Grafiekelementen verwijderen

Als u specifieke dubbels en relaties wilt verwijderen, gebruikt u de DigitalTwins Delete en DigitalTwins DeleteRelationship-API's (ook beschikbaar als CLI-opdrachten en SDK-aanroepen).

Als u alle modellen, tweelingen en relaties in een exemplaar tegelijk wilt verwijderen, gebruikt u de API Taken verwijderen.

JSON-weergaven van grafiekelementen

Gegevens van digitale dubbels en relaties worden beide opgeslagen in JSON-indeling. Dit betekent dat wanneer u een query uitvoert op de dubbelgrafiek in uw Azure Digital Twins-exemplaar, het resultaat een JSON-weergave is van digitale dubbels en relaties die u hebt gemaakt.

JSON-indeling voor digitale dubbels

Wanneer een digitale dubbel wordt weergegeven als een JSON-object, worden de volgende velden weergegeven:

Veldnaam	Beschrijving
`$dtId`	Een door de gebruiker opgegeven tekenreeks die de id van de digitale dubbel vertegenwoordigt
`$etag`	Standaard-HTTP-veld dat is toegewezen door de webserver
`$metadata.$model`	De id van de modelinterface die deze digitale dubbel karakteriseert
`$metadata.<property-name>`	Andere metagegevensinformatie over eigenschappen van de digitale dubbel
`$metadata.<property-name>.lastUpdateTime`	De datum/tijd waarop het bericht over het bijwerken van de eigenschap is verwerkt door Azure Digital Twins
`$metadata.<property-name>.sourceTime`	Een optionele, beschrijfbare eigenschap die de tijdstempel aangeeft toen de eigenschapsupdate werd waargenomen in de echte wereld. Deze eigenschap kan alleen worden geschreven met de versie 2022-05-31 van de Azure Digital Twins-API's/SDK's en de waarde moet voldoen aan de iso 8601-datum- en tijdnotatie. Zie De brontijd van een eigenschap bijwerken voor meer informatie over het bijwerken van deze eigenschap.
`<property-name>`	De waarde van een eigenschap in JSON (`string`, getaltype of object)
`$relationships`	De URL van het pad naar de verzameling relaties. Dit veld is afwezig als de digitale dubbel geen uitgaande relatieranden heeft.
`<component-name>`	Een JSON-object met de eigenschapswaarden en metagegevens van het onderdeel, vergelijkbaar met die van het hoofdobject. Dit object bestaat zelfs als het onderdeel geen eigenschappen heeft.
`<component-name>.$metadata`	De metagegevensinformatie voor het onderdeel, vergelijkbaar met het hoofdniveau `$metadata`
`<component-name>.<property-name>`	De waarde van de eigenschap van het onderdeel in JSON (`string`, getaltype of object)

Hier volgt een voorbeeld van een digitale dubbel die is opgemaakt als een JSON-object. Deze tweeling heeft twee eigenschappen, Vochtigheid en Temperatuur en een onderdeel genaamd Thermostaat.

{
    "$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": {}
    }

JSON-indeling voor relaties

Wanneer deze wordt weergegeven als een JSON-object, worden in een relatie van een digitale dubbel de volgende velden weergegeven:

Veldnaam	Beschrijving
`$relationshipId`	Een door de gebruiker opgegeven tekenreeks die de id van deze relatie vertegenwoordigt. Deze tekenreeks is uniek in de context van de digitale brondubbel. Dit betekent ook dat deze `sourceId` + `relationshipId` uniek is in de context van het Azure Digital Twins-exemplaar.
`$etag`	Standaard-HTTP-veld dat is toegewezen door de webserver
`$sourceId`	De id van de digitale brondubbel
`$targetId`	De id van de doel digitale dubbel
`$relationshipName`	De naam van de relatie
`<property-name>`	[Optioneel] De waarde van een eigenschap van deze relatie, in JSON (`string`, getaltype of object)

Hier volgt een voorbeeld van een relatie die is opgemaakt als een JSON-object:

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

Volgende stappen

Bekijk hoe u grafiekelementen beheert met Azure Digital Twin-API's:

Of lees meer over het uitvoeren van query's op de Azure Digital Twins-tweelinggrafiek voor informatie:

Querytaal