Digitala tvillingar och deras tvillingdiagram

Den här artikeln beskriver vad digitala tvillingar är i kontexten för Azure Digital Twins och hur relationer mellan dem kan bilda en tvillinggraf. I en Azure Digital Twins-lösning representeras entiteterna i din miljö av digitala tvillingar. En digital tvilling är en instans av en av dina anpassade definierade modeller. Den kan anslutas till andra digitala tvillingar via relationer för att bilda en tvillinggraf: det här tvillingdiagrammet är en representation av hela din miljö.

Dricks

"Azure Digital Twins" refererar till den här Azure-tjänsten som helhet. "Digital twin(s)" eller bara "twin(s)" refererar till enskilda tvillingnoder i din instans av tjänsten.

Digitala tvillingenheter

Innan du kan skapa en digital tvilling i din Azure Digital Twins-instans måste du ha en modell uppladdad till tjänsten. En modell beskriver bland annat den uppsättning egenskaper och relationer som en viss tvilling kan ha. De typer av information som definieras i en modell finns i Anpassade modeller.

När du har skapat och laddat upp en modell kan klientappen skapa en instans av typen . Den här instansen är en digital tvilling. När du till exempel har skapat en modell av Floor kan du skapa en eller flera digitala tvillingar som använder den här typen (till exempel en tvilling av golvtyp med namnet GroundFloor, en annan med namnet Floor2 och så vidare).

Kommentar

Digitala tvillingar i Azure Digital Twins skiljer sig från enhetstvillingar i IoT Hub. IoT Hub-enhetstvillingar fokuserar ofta på att beskriva aspekterna och funktionerna i själva en enhet, medan tvillingar i Azure Digital Twins är mer konceptuella representationer som kan lagra användardefinierade insikter om en enhet eller många relaterade enheter.

Enheter i IoT Hub kan anslutas till Azure Digital Twins som en del av en lösning från slutpunkt till slutpunkt som representerar din enhet mellan tjänster.

Relationer: ett diagram över digitala tvillingar

Tvillingar är anslutna till en tvillinggraf av sina relationer. De relationer som en tvilling kan ha definieras som en del av modellen.

Modellen Floor kan till exempel definiera en contains relation som riktar sig till tvillingar av typen Room. Med den här definitionen kan du med Azure Digital Twins skapa contains relationer från valfri Golvtvilling till valfri Rumstvilling (inklusive tvillingar som är av rumsundertyper).

Resultatet av den här processen är en uppsättning noder (de digitala tvillingarna) som är anslutna via kanter (deras relationer) i en graf.

Visualisering

Azure Digital Twins Explorer är ett visuellt verktyg för att utforska data i ditt Azure Digital Twins-diagram. Du kan använda utforskaren för att visa, fråga och redigera dina modeller, tvillingar och relationer.

Mer information om Azure Digital Twins Explorer-verktyget finns i Azure Digital Twins Explorer. Detaljerade anvisningar om hur du använder dess funktioner finns i Använda Azure Digital Twins Explorer.

Så här ser visualiseringen ut:

Skapa med API:erna

Det här avsnittet visar hur det ser ut att skapa digitala tvillingar och relationer från ett klientprogram. Den innehåller .NET SDK-exempel som använder DigitalTwins-API:er för att ge mer kontext om vad som händer i vart och ett av dessa begrepp.

Skapa digitala tvillingar

Nedan visas ett kodfragment med klientkod som använder DigitalTwins-API:erna för att instansiera en tvilling av typen Room med en twinId som definieras under instansieringen.

Du kan initiera egenskaperna för en tvilling när den skapas eller ange dem senare. Skapa en tvilling med initierade egenskaper genom att skapa ett JSON-dokument som tillhandahåller nödvändiga initieringsvärden.

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

Du kan också använda en hjälpklass med namnet BasicDigitalTwin för att lagra egenskapsfält i ett "tvillingobjekt" mer direkt, som ett alternativ till att använda en ordlista. Mer information om hjälpklassen och exempel på dess användning finns i Skapa en digital tvilling.

Kommentar

Även om tvillingegenskaper behandlas som valfria och därför inte behöver initieras, måste alla komponenter i tvillingen anges när tvillingen skapas. De kan vara tomma objekt, men själva komponenterna måste finnas.

Skapa relationer

Här är ett exempel på klientkod som använder DigitalTwins-API:erna för att skapa en relation från en digital tvilling ("källtvillingen" till en annan digital tvilling ("måltvillingen").

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

Skapa tvillingar och relationer i grupp med API:et Importera jobb

Du kan ladda upp många tvillingar och relationer i ett enda API-anrop med hjälp av API:et Importera jobb. Tvillingar och relationer som skapats med det här API:et kan också inkludera initiering av deras egenskaper. Detaljerade instruktioner och exempel som använder det här API:et finns i massimportinstruktioner för tvillingar och relationer.

Ta bort diagramelement

Om du vill ta bort specifika tvillingar och relationer använder du API:erna DigitalTwins Delete och DigitalTwins DeleteRelationship (även tillgängliga som CLI-kommandon och SDK-anrop).

Om du vill ta bort alla modeller, tvillingar och relationer i en instans samtidigt använder du API:et Ta bort jobb.

JSON-representationer av grafelement

Data och relationsdata för digitala tvillingar lagras båda i JSON-format, vilket innebär att resultatet blir en JSON-representation av digitala tvillingar och relationer som du har skapat när du kör frågor mot tvillingdiagrammet i Din Azure Digital Twins-instans.

JSON-format för digital tvilling

När det representeras som ett JSON-objekt visar en digital tvilling följande fält:

Fältnamn	beskrivning
$dtId	En användaranvändarsträng som representerar ID:t för den digitala tvillingen
$etag	Http-standardfält som tilldelats av webbservern
$metadata.$model	ID:t för modellgränssnittet som kännetecknar den här digitala tvillingen
$metadata.<property-name>	Annan metadatainformation om egenskaperna för den digitala tvillingen
$metadata.<property-name>.lastUpdateTime	Datum/tid då egenskapsuppdateringsmeddelandet bearbetades av Azure Digital Twins
$metadata.<property-name>.sourceTime	En valfri, skrivbar egenskap som representerar tidsstämpeln när egenskapsuppdateringen observerades i verkligheten. Den här egenskapen kan bara skrivas med 2022-05-31-versionen av Azure Digital Twins API:er/SDK:er och värdet måste uppfylla ISO 8601-datum- och tidsformatet. Mer information om hur du uppdaterar den här egenskapen finns i Uppdatera en egenskaps sourceTime.
<property-name>	Värdet för en egenskap i JSON (string, nummertyp eller objekt)
$relationships	URL:en för sökvägen till relationssamlingen. Det här fältet saknas om den digitala tvillingen inte har några utgående relationskanter.
<component-name>	Ett JSON-objekt som innehåller komponentens egenskapsvärden och metadata, ungefär som rotobjektets. Det här objektet finns även om komponenten inte har några egenskaper.
<component-name>.$metadata	Metadatainformationen för komponenten liknar rotnivån $metadata
<component-name>.<property-name>	Värdet för komponentens egenskap i JSON (string, nummertyp eller objekt)

Här är ett exempel på en digital tvilling formaterad som ett JSON-objekt. Den här tvillingen har två egenskaper, luftfuktighet och temperatur, och en komponent som kallas termostat.

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

Relations-JSON-format

När det representeras som ett JSON-objekt visar en relation från en digital tvilling följande fält:

Fältnamn	beskrivning
$relationshipId	En användaranvändarsträng som representerar ID:t för den här relationen. Den här strängen är unik i kontexten för den digitala källtvillingen, vilket också innebär att sourceId + relationshipId den är unik i kontexten för Azure Digital Twins-instansen.
$etag	Http-standardfält som tilldelats av webbservern
$sourceId	ID för den digitala källtvillingen
$targetId	ID:t för den digitala måltvillingen
$relationshipName	Namnet på relationen
<property-name>	[Valfritt] Värdet för en egenskap för den här relationen i JSON (string, nummertyp eller objekt)

Här är ett exempel på en relation formaterad som ett JSON-objekt:

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

Nästa steg

Se hur du hanterar grafelement med Azure Digital Twin-API:er:

• Hantera digitala tvillingar
• Hantera tvillingdiagrammet och relationerna

Eller lär dig mer om att fråga Azure Digital Twins-tvillingdiagrammet om du vill ha information:

• Frågespråk