Digitale Zwillinge und ihr Zwillingsgraph

Artikel
01/03/2024

In diesem Artikel wird beschrieben, was digitale Zwillinge im Kontext von Azure Digital Twins sind und wie Beziehungen zwischen ihnen einen Zwillingsgraphen bilden können. In einer Azure Digital Twins-Lösung werden die Entitäten in Ihrer Umgebung durch digitale Zwillinge dargestellt. Ein digitaler Zwilling ist eine Instanz eines Ihrer benutzerdefinierten Modelle. Er kann mit anderen digitalen Zwillingen über Beziehungen verbunden werden, um einen Zwillingsgraphen zu erhalten. Dieser Zwillingsgraph ist die Darstellung Ihrer gesamten Umgebung.

Tipp

„Azure Digital Twins“ ist der Name dieses Azure-Diensts. „Digitale Zwillinge“ oder einfach „Zwillinge“ bezieht sich einzelne Zwillingsknoten auf Ihrer Instanz des Diensts.

Digital Twins

Bevor Sie auf Ihrer Azure Digital Twins-Instanz einen digitalen Zwilling erstellen können, müssen Sie ein Modell in den Dienst hochladen. Ein Modell beschreibt unter anderem den Satz von Eigenschaften und Beziehungen, die ein bestimmter Zwilling haben kann. Informationen zu den Informationsarten, die in einem Modell definiert sind, finden Sie unter Benutzerdefinierte Modelle.

Nachdem Sie ein Modell erstellt und hochgeladen haben, kann Ihre Client-App eine Instanz des entsprechenden Typs erstellen. Diese Instanz ist ein digitaler Zwilling. Nachdem Sie beispielsweise ein Modell vom Typ „Floor“ (Etage) erstellt haben, können Sie einen oder mehrere digitale Zwillinge erstellen, die diesen Typ nutzen (z. B. ein Zwilling vom Typ „Floor“ mit dem Namen „GroundFloor“, einen anderen mit dem Namen „Floor2“ usw.).

Hinweis

Digitale Zwillinge in Azure Digital Twins unterscheiden sich von Geräte twins im IoT Hub. Bei IoT Hub-Gerätezwillingen steht häufig die Beschreibung der Aspekte und Funktionen eines Geräts im Vordergrund. Bei Zwillingen in Azure Digital Twins handelt es sich dagegen um eher konzeptionelle Darstellungen zur Speicherung benutzerdefinierter Informationen zu einem Gerät oder zu zahlreichen verwandten Geräten.

Geräte in IoT Hub können im Rahmen einer End-to-End-Lösung, die Geräte dienstübergreifend darstellt, mit Azure Digital Twins verbunden werden.

Beziehungen: ein Graph für digitale Zwillinge

Zwillinge werden anhand ihrer Beziehungen zu einem Zwillingsgraphen vereint. Die Beziehungen, die ein Zwilling aufweisen kann, werden als Teil des Modells definiert.

Beispielsweise kann das Modell Floor eine contains Beziehung definieren, die auf Zwillinge vom Typ "Raum" ausgerichtet ist. Mit dieser Definition können Sie mit Azure Digital Twins Beziehungen von jedem Floor Twin zu jedem Room Twin erstellen contains (einschließlich Zwillinge, die raumuntertypen sind).

Das Ergebnis dieses Prozesses ist eine Gruppe mit Knoten (die digitalen Zwillinge), die über Edges (die Beziehungen) in einem Graphen verbunden sind.

Visualisierung

Der Azure Digital Twins-Explorer ist ein visuelles Tool zum Untersuchen der Daten in Ihrem Azure Digital Twins-Graphen. Mit dem Explorer können Sie Modelle, Zwillinge und Beziehungen anzeigen, abfragen und bearbeiten.

Weitere Informationen zum Azure Digital Twins-Explorer finden Sie unter Azure Digital Twins-Explorer. Ausführliche Schritte zur Verwendung der einzelnen Features finden Sie unter Verwenden von Azure Digital Twins-Explorer.

Die Visualisierung sieht wie folgt aus:

Erstellen mit den APIs

In diesem Abschnitt wird gezeigt, wie das Erstellen digitaler Zwillinge und Beziehungen über eine Clientanwendung aussieht. Es enthält .NET SDK-Beispiele , die die DigitalTwins-APIs verwenden, um mehr Kontext zu den Inhalten in den einzelnen Konzepten bereitzustellen.

Erstellen digitaler Zwillinge

Unten sehen Sie einen Ausschnitt des Clientcodes, in dem die DigitalTwins-APIs zum Instanziieren eines Zwillings vom Typ „Room“ (Zimmer) mit einer bei der Instanziierung definierten twinId verwendet wird.

Sie können die Eigenschaften eines Zwillings bei der Erstellung initialisieren oder später festlegen. Um einen Zwilling mit initialisierten Eigenschaften zu erstellen, erstellen Sie ein JSON-Dokument, das die erforderlichen Initialisierungswerte bereitstellt.

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

Sie können auch eine Hilfsklasse namens BasicDigitalTwin verwenden, um Eigenschaftenfelder als Alternative zur Verwendung eines Wörterbuchs direkt in einem „Zwillingsobjekt“ zu speichern. Weitere Informationen zur Hilfsklasse und Beispiele für deren Verwendung finden Sie unter Erstellen eines digitalen Zwillings.

Hinweis

Obwohl Zwillingseigenschaften optional sind und daher nicht initialisiert werden müssen, müssen alle Komponenten auf dem Zwilling beim Erstellen des Zwillings festgelegt werden. Es kann sich um leere Objekte handeln, aber die Komponenten selbst müssen vorhanden sein.

Erstellen von Beziehungen

Im Folgenden finden Sie Beispielclientcode, der die DigitalTwins-APIs verwendet, um eine Beziehung von einem digitalen Zwilling (dem „Quellzwilling“) zu einem anderen digitalen Zwilling (dem „Zielzwilling“) herzustellen.

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

Erstellen von Zwillingen und Beziehungen im Massenvorgang mit der Importaufträge-API

Sie können viele Zwillinge und Beziehungen in einem einzelnen API-Aufruf mithilfe der Importaufträge-API hochladen. Zwillinge und Beziehungen, die mit dieser API erstellt wurden, können optional die Initialisierung ihrer Eigenschaften umfassen. Ausführliche Anweisungen und Beispiele, die diese API verwenden, finden Sie unter Massenimportanweisungen für Zwillinge und Beziehungen.

Löschen von Diagrammelementen

Um bestimmte Zwillinge und Beziehungen zu löschen, verwenden Sie die Delete- und DigitalTwins DeleteRelationship-APIs (auch als CLI-Befehle und SDK-Aufrufe verfügbar).

Um alle Modelle, Zwillinge und Beziehungen in einer Instanz gleichzeitig zu löschen, verwenden Sie die Delete Jobs-API.

JSON-Darstellungen von Graphelementen

Sowohl die Daten des digitalen Zwillings als auch die Beziehungsdaten werden im JSON-Format gespeichert. Das heißt, wenn Sie den Zwillingsgraphen in Ihrer Azure Digital Twins-Instanz abfragen, ist das Ergebnis eine JSON-Darstellung der von Ihnen erstellten digitalen Zwillinge und Beziehungen.

JSON-Format von digitalen Zwillingen

Bei der Darstellung als JSON-Objekt zeigt ein digitaler Zwilling die folgenden Felder an:

Feldname	Beschreibung
`$dtId`	Eine vom Benutzer angegebene Zeichenfolge zur Darstellung der ID des digitalen Zwillings
`$etag`	Ein vom Webserver zugewiesenes Standard-HTTP-Feld
`$metadata.$model`	Die ID der Modellschnittstelle, die diesen digitalen Zwilling kennzeichnet
`$metadata.<property-name>`	Weitere Metadateninformationen zu Eigenschaften des digitalen Zwillings
`$metadata.<property-name>.lastUpdateTime`	Datum/Uhrzeit der Eigenschaftsupdatemeldung wurde durch Azure Digital Twins verarbeitet.
`$metadata.<property-name>.sourceTime`	Eine optionale, beschreibbare Eigenschaft, die den Zeitstempel darstellt, als das Update der Eigenschaft in der realen Welt beobachtet wurde. Diese Eigenschaft kann nur mit der Version 2022-05-31 der Azure Digital Twins-APIs/SDKs geschrieben werden und der Wert muss dem Datums- und Uhrzeitformat nach ISO 8601 entsprechen. Weitere Informationen zum Aktualisieren dieser Eigenschaft finden Sie unter Aktualisieren von sourceTime einer Eigenschaft.
`<property-name>`	Den Wert einer Eigenschaft im JSON-Format (`string`, Zahlentyp oder Objekt)
`$relationships`	Die URL des Pfads zur Sammlung mit den Beziehungen. Dieses Feld ist nicht vorhanden, wenn der digitale Zwilling keine ausgehenden Beziehungsedges aufweist.
`<component-name>`	Ein JSON-Objekt mit den Eigenschaftswerten und Metadaten der Komponente, die denen des Stammobjekts ähneln. Dieses Objekt ist auch vorhanden, wenn die Komponente keine Eigenschaften hat.
`<component-name>.$metadata`	Die Metadateninformationen für die Komponente, die dem Objekt `$metadata` auf der Stammebene ähneln
`<component-name>.<property-name>`	Den Wert der Komponenteneigenschaft im JSON-Format (`string`, Zahlentyp oder Objekt)

Hier ist ein Beispiel für einen digitalen Zwilling angegeben, der als JSON-Objekt formatiert ist. Dieser Zwilling verfügt über zwei Eigenschaften: „Humidity“ und „Temperature“ und eine Komponente namens „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": {}
    }

Beziehung im JSON-Format

Bei der Darstellung als JSON-Objekt zeigt die Beziehung eines digitalen Zwillings die folgenden Felder an:

Feldname	Beschreibung
`$relationshipId`	Eine vom Benutzer angegebene Zeichenfolge zur Darstellung der ID dieser Beziehung. Diese Zeichenfolge ist im Kontext des digitalen Quellzwillings eindeutig. Dies bedeutet, dass `sourceId` + `relationshipId` im Kontext der Azure Digital Twins-Instanz eindeutig ist.
`$etag`	Ein vom Webserver zugewiesenes Standard-HTTP-Feld
`$sourceId`	Die ID des digitalen Quellzwillings
`$targetId`	Die ID des digitalen Zielzwillings
`$relationshipName`	Der Name der Beziehung
`<property-name>`	[Optional] Den Wert einer Eigenschaft dieser Beziehung im JSON-Format (`string`, Zahlentyp oder Objekt)

Hier ist ein Beispiel für eine Beziehung angegeben, die als JSON-Objekt formatiert ist:

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

Nächste Schritte

Informieren Sie sich darüber, wie Sie Graphelemente mit Azure Digital Twin-APIs verwalten können:

Sie können sich auch damit vertraut machen, wie Sie Informationen für einen Azure Digital Twins-Zwillingsgraphen abfragen:

Abfragesprache