Verwalten digitaler Zwillinge

Artikel
01/03/2024

Entitäten in Ihrer Umgebung werden durch digital Zwillinge dargestellt. Die Verwaltung Ihrer digitalen Zwillinge kann das Erstellen, Ändern und Entfernen umfassen.

In diesem Artikel wird die Verwaltung digitaler Zwillinge beschrieben. Informationen zum Arbeiten mit Beziehungen und dem Zwillingsgraphen insgesamt finden Sie unter Verwalten des Zwillingsgraphen und der Beziehungen.

Tipp

Alle SDK-Funktionen sind in synchronen und asynchronen Versionen enthalten.

Voraussetzungen

Damit Sie in diesem Artikel mit Azure Digital Twins arbeiten können, benötigen Sie eine Azure Digital Twins-Instanz und die erforderlichen Berechtigungen, um sie zu verwenden. Wenn Sie über eine bereits eingerichtete Azure Digital Twins-Instanz verfügen, können Sie diese nutzen und zum nächsten Abschnitt springen. Befolgen Sie andernfalls die Anleitung unter Einrichten einer Instanz und der Authentifizierung. Die Anweisungen enthalten Informationen, mit denen Sie überprüfen können, ob jeder Schritt erfolgreich abgeschlossen wurde.

Notieren Sie sich nach dem Einrichten Ihrer Instanz den Hostnamen der Instanz. Sie finden den Hostnamen im Azure-Portal.

Entwicklerschnittstellen

In diesem Artikel wird erläutert, wie Sie unterschiedliche Verwaltungsvorgänge mithilfe des .NET (C#) SDK durchführen. Sie können dieselben Verwaltungsaufrufe auch mit den anderen Sprach-SDKs erstellen, wie unter Azure Digital Twins-APIs und SDKs beschrieben.

Andere Entwicklerschnittstellen, die zum Ausführen dieser Vorgänge verwendet werden können, 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 eines digitalen Zwillings

Wenn Sie einen Zwilling erstellen möchten, verwenden Sie die CreateOrReplaceDigitalTwinAsync()-Methode auf dem Serviceclient wie folgt:

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

Zum Erstellen eines digitalen Zwillings müssen Sie Folgendes angeben:

Ein ID-Wert, den Sie dem digitalen Zwilling zuweisen möchten (Sie definieren diese ID, wenn der Zwilling erstellt wird)
Das zu verwendende Modell
Alle gewünschten Initialisierungen von Zwillingsdaten, einschließlich...
- Eigenschaften (Initialisierung optional): Sie können bei Bedarf Anfangswerte für Eigenschaften des digitalen Zwillings festlegen. Eigenschaften werden als optional behandelt und können später festgelegt werden. Beachten Sie aber, dasssie erst als Teil eines Zwillings angezeigt werden, nachdem sie festgelegt wurden.
- Komponenten (Initialisierung erforderlich, wenn sie auf einem Zwilling vorhanden sind): Wenn Ihr Zwilling Komponenten enthält, müssen diese beim Erstellen des Zwillings initialisiert werden. Es kann sich um leere Objekte handeln, aber die Komponenten selbst müssen vorhanden sein.

Die Modell- und alle ursprünglichen Eigenschaftswerte werden über den initData-Parameter bereitgestellt. Dabei handelt es sich um eine JSON-Zeichenfolge, die die relevanten Daten enthält. Weitere Informationen zum Strukturieren dieses Objekts finden Sie im nächsten Abschnitt.

Tipp

Nachdem Sie einen Zwilling erstellt oder aktualisiert haben, kann es bis zu 10 Sekunden dauern, bis sich die Änderungen in Abfragen widerspiegeln. Bei der GetDigitalTwin-API (siehe weiter unten in diesem Artikel) tritt diese Verzögerung nicht auf. Wenn Sie eine sofortige Antwort benötigen, verwenden Sie daher den API-Befehl anstelle von Abfragen, um die neu erstellten Zwillinge anzuzeigen.

Initialisieren des Modells und der Eigenschaften

Sie können die Eigenschaften eines Zwillings zum Zeitpunkt der Erstellung des Zwillings initialisieren.

Die Zwillingserstellungs-API akzeptiert ein Objekt, das in eine gültige JSON-Beschreibung der Zwillingseigenschaften serialisiert wird. Unter Digitale Zwillinge und der Zwillingsgraph finden Sie eine Beschreibung des JSON-Formats für einen Zwilling.

Zunächst können Sie ein Datenobjekt erstellen, das den Zwilling und seine Eigenschaftsdaten darstellt. Sie können ein Parameterobjekt entweder manuell oder mithilfe einer bereitgestellten Hilfsklasse erstellen. Hier sehen Sie ein Beispiel für jeden.

Erstellen von Zwillingen mithilfe manuell erstellter Daten

Sie können die Eigenschaften eines Zwillings ohne benutzerdefinierte Hilfsklassen in Dictionary<string, object> darstellen, wobei string der Name der Eigenschaft ist und object ein Objekt, das die Eigenschaft und ihren Wert darstellt.

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

Erstellen von Zwillingen mithilfe der Hilfsklasse

Die Hilfsklasse BasicDigitalTwin ermöglicht es Ihnen, Eigenschaftsfelder in einem Zwillingsobjekt direkt zu speichern. Möglicherweise möchten Sie trotzdem die Liste der Eigenschaften mithilfe eines Dictionary<string, object>, das dann dem Zwillingsobjekt direkt CustomProperties hinzugefügt werden kann, erstellen.

string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
    Id = twinId,
    Metadata = { ModelId = "dtmi:example:Room;1" },
    // Initialize properties
    Contents =
    {
        { "Temperature", 25.0 },
        { "Humidity", 50.0 },
    },
};

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

Hinweis

BasicDigitalTwin-Objekte verfügen über ein Id-Feld. Sie können dieses Feld leer lassen. Wenn Sie einen ID-Wert hinzufügen, muss dieser jedoch dem an den CreateOrReplaceDigitalTwinAsync()-Aufruf übergebenen ID-Parameter entsprechen. Beispiel:

twin.Id = "myRoomId";

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

Sie können die Importaufträge-API verwenden, um viele Zwillinge gleichzeitig in einem einzigen API-Aufruf zu erstellen. Diese Methode erfordert die Verwendung von Azure Blob Storage und Schreibberechtigungen in Ihrer Azure Digital Twins-Instanz für Zwillinge und Massenaufträge.

Tipp

Die Importaufträge-API ermöglicht außerdem das Importieren von Modellen und Beziehungen im selben Aufruf, um alle Teile eines Diagramms gleichzeitig zu erstellen. Weitere Informationen zu diesem Prozess finden Sie unter Hochladen von Modellen, Zwillingen und Beziehungen in Massen mit der Importaufträge-API.

Um Zwillinge in Massen zu importieren, müssen Sie Ihre Zwillinge (und alle anderen Ressourcen, die im Massenimportauftrag enthalten sind) als NDJSON-Datei strukturieren. Der Twins Abschnitt kommt nach dem Models Abschnitt (und vor dem Relationships Abschnitt). Zwillinge, die in der Datei definiert sind, können auf Modelle verweisen, die entweder in dieser Datei definiert sind oder bereits in der Instanz vorhanden sind, und sie können optional die Initialisierung der Eigenschaften des Zwillings einschließen.

Sie können eine Beispielimportdatei und ein Beispielprojekt zum Erstellen dieser Dateien in der Einführung der Importaufträge-API anzeigen.

Als Nächstes muss die Datei in ein Anfüge-Blob in Azure Blob Storage hochgeladen werden. Anweisungen zum Erstellen eines Azure-Speichercontainers finden Sie unter Erstellen eines Containers. Laden Sie dann die Datei mit Ihrer bevorzugten Uploadmethode hoch (einige Optionen sind der AzCopy-Befehl, die Azure CLI oder die Azure-Portal).

Nachdem die NDJSON-Datei in den Container hochgeladen wurde, rufen Sie die URL im BLOB-Container ab. Sie verwenden diesen Wert später im Textkörper des API-Massenimportaufrufs.

Hier ist ein Screenshot, der den URL-Wert einer BLOB-Datei in der Azure-Portal zeigt:

Anschließend kann die Datei in einem Importaufträge-API-Aufruf verwendet werden. Sie stellen die BLOB-Speicher-URL der Eingabedatei und eine neue BLOB-Speicher-URL bereit, um anzugeben, wo das Ausgabeprotokoll gespeichert werden soll, nachdem der Dienst es erstellt hat.

Abrufen von Daten für einen digitalen Zwilling

Sie können auf die Details jedes digitalen Zwillings zugreifen, indem Sie die Methode GetDigitalTwin() wie folgt aufrufen:

Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;

Dieser Aufruf gibt Zwillingsdaten als einen stark typisierten Objekttyp (z. B. BasicDigitalTwin) zurück. BasicDigitalTwin ist eine Serialisierungshilfsklasse, die im SDK enthalten ist, die die kernigen Twin-Metadaten und -Eigenschaften in vordefinierter Form zurückgibt. Sie können jederzeit Zwillingsdaten deserialisieren, indem Sie die JSON-Bibliothek Ihrer Wahl wie System.Text.Json oder Newtonsoft.Json verwenden. Den grundlegenden Zugriff auf einen Zwilling können jedoch die Hilfsklassen komfortabler machen.

Hinweis

Von BasicDigitalTwin werden Attribute vom Typ System.Text.Json verwendet. Um BasicDigitalTwin mit Ihrer Instanz von DigitalTwinsClient verwenden zu können, müssen Sie entweder den Client mit dem Standardkonstruktor initialisieren oder den Serialisierer JsonObjectSerializer, wenn Sie die Serialisierungsoption anpassen möchten.

Die Hilfsklasse BasicDigitalTwin bietet Ihnen auch Zugriff auf Eigenschaften, die auf dem Zwilling definiert sind, über ein Dictionary<string, object>. Sie können Folgendes verwenden, um die Eigenschaften eines Zwillings aufzulisten:

BasicDigitalTwin twin;
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
    if (twin.Contents.TryGetValue(prop, out object value))
        Console.WriteLine($"Property '{prop}': {value}");
}

Beim Abrufen eines Zwillings mit der Methode GetDigitalTwin() werden nur Eigenschaften zurückgegeben, die mindestens einmal festgelegt wurden.

Tipp

Der displayName für einen Zwilling ist ein Teil seiner Modellmetadaten und wird daher nicht angezeigt, wenn Daten für die Zwillingsinstanz abgerufen werden. Um diesen Wert zu sehen, können Sie ihn aus dem Modell abrufen.

Informationen zum Abrufen mehrerer Zwillinge mithilfe eines einzelnen API-Aufrufs finden Sie in den Abfrage-API-Beispielen in "Query the twin graph".

Beachten Sie das folgende Modell (geschrieben in Digital Twins Definition Language (DTDL)), das einen Zwilling vom Typ Moon definiert:

{
    "@id": "dtmi:example:Moon;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
        {
            "@type": "Property",
            "name": "radius",
            "schema": "double",
            "writable": true
        },
        {
            "@type": "Property",
            "name": "mass",
            "schema": "double",
            "writable": true
        }
    ]
}

Das Ergebnis des Aufrufs object result = await client.GetDigitalTwinAsync("my-moon"); eines Mond-Zwillings könnte wie folgt aussehen:

{
  "$dtId": "myMoon-001",
  "$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
  "radius": 1737.1,
  "mass": 0.0734,
  "$metadata": {
    "$model": "dtmi:example:Moon;1",
    "radius": {
      "lastUpdateTime": "2022-12-06T20:00:32.8209188Z"
    },
    "mass": {
      "lastUpdateTime": "2022-12-04T12:04:43.3859361Z"
    }
  }
}

Die definierten Eigenschaften des digitalen Zwillings werden als Eigenschaften der obersten Ebene für den digitalen Zwilling zurückgegeben. Metadaten oder Systeminformationen, die nicht Teil der DTDL-Definition sind, werden mit einem $-Präfix zurückgegeben. Metadateneigenschaften umfassen die folgenden Werte:

$dtId: ID des digitalen Zwillings in dieser Azure Digital Twins-Instanz
$etag: ein vom Webserver zugewiesenes Standard-HTTP-Feld. Dieser Wert wird bei jeder Aktualisierung des Zwillings geändert. Er kann damit hilfreich sein, um zu ermitteln, ob die Daten des Zwillings seit einer früheren Überprüfung auf dem Server aktualisiert wurden. Sie können If-Match verwenden, um Aktualisierungen und Löschungen durchführen, die nur dann abgeschlossen werden, wenn der Etag mit dem bereitgestellten Etag übereinstimmt. Weitere Informationen zu diesen Vorgängen finden Sie in der Dokumentation zu DigitalTwins Update und DigitalTwins Delete.
$metadata: Eine Reihe von Metadateneigenschaften, die Folgendes enthalten können:
- $model, die DTMI des Modells des digitalen Zwillings.
- lastUpdateTime für Zwillingseigenschaften. Dies ist ein Zeitstempel, der das Datum und die Uhrzeit angibt, zu dem Azure Digital Twins die Eigenschaftsaktualisierungsnachricht verarbeitet hat.
- sourceTime für Zwillingseigenschaften. Dies ist eine optionale beschreibbare Eigenschaft, die den Zeitstempel darstellt, als die Eigenschaftsaktualisierung in der realen Welt beobachtet wurde.

Weitere Informationen zu den Feldern, die in einem digitalen Zwilling im Digital Twin JSON-Format enthalten sind, finden Sie hier. Weitere Informationen zu den Serialisierungshilfsklassen wie BasicDigitalTwin finden Sie unter Azure Digital Twins-APIs und SDKs.

Anzeigen aller digitalen Zwillinge

Verwenden Sie zum Anzeigen aller digitalen Zwillinge in Ihrer Instanz eine Abfrage. Sie können eine Abfrage mit den Abfrage-APIs oder den CLI-Befehlen ausführen.

Dies ist der Textkörper der grundlegenden Abfrage, die eine Liste aller digitalen Zwillinge in der Instanz zurückgibt:

SELECT * FROM DIGITALTWINS

Aktualisieren eines digitalen Zwillings

Um die Eigenschaften eines digitalen Zwillings zu aktualisieren, schreiben Sie die Informationen, die Sie ersetzen möchten, im JSON Patch-Format. Eine vollständige Liste der JSON Patch-Vorgänge, die verwendet werden können, einschließlich replace, add und remove, finden Sie im Abschnitt Vorgänge für JSON Patch.

Nachdem Sie das JSON Patch-Dokument mit Updateinformationen erstellt haben, übergeben Sie das Dokument an die UpdateDigitalTwin()-Methode:

await client.UpdateDigitalTwinAsync(twinId, updateTwinData);

Ein einzelner Patchaufruf kann beliebig viele Eigenschaften auf einem einzelnen Zwilling aktualisieren (sogar alle). Wenn Sie Eigenschaften über mehrere Zwillinge hinweg aktualisieren müssen, benötigen Sie einen separaten Aktualisierungsaufruf für jeden Zwilling.

Tipp

Nachdem Sie einen Zwilling erstellt oder aktualisiert haben, kann es bis zu 10 Sekunden dauern, bis sich die Änderungen in Abfragen widerspiegeln. Bei der GetDigitalTwin-API (siehe weiter oben in diesem Artikel) tritt diese Verzögerung nicht auf. Verwenden Sie daher den API-Befehl anstelle von Abfragen, um die neu aktualisierten Zwillinge anzuzeigen, wenn Sie eine sofortige Antwort benötigen.

Im Folgenden finden Sie ein Beispiel des JSON Patch-Codes. Dieses Dokument ersetzt die Eigenschaftswerte mass und radius des digitalen Zwillings, auf den es angewendet wird. Dieses Beispiel zeigt den JSON Patch-Vorgang replace, der den Wert einer vorhandenen Eigenschaft ersetzt.

[
    {
      "op": "replace",
      "path": "/mass",
      "value": 0.0799
    },
    {
      "op": "replace",
      "path": "/radius",
      "value": 0.800
    }
  ]

Wenn Sie einen Zwilling aus einem Codeprojekt mit dem .NET SDK aktualisieren, können Sie JSON-Patches mit JsonPatchDocument aus dem Azure .NET SDK erstellen. Im Folgenden finden Sie ein Beispiel für das Erstellen eines JSON Patch-Dokuments und das Verwenden von UpdateDigitalTwin() im Projektcode.

var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 25.0);
updateTwinData.AppendAdd("/myComponent/Property", "Hello");
// Un-set a property
updateTwinData.AppendRemove("/Humidity");

await client.UpdateDigitalTwinAsync("myTwin", updateTwinData).ConfigureAwait(false);

Tipp

Sie können Quellzeitstempel für Ihre digitalen Zwillinge beibehalten, indem Sie das Feld $metadata.<property-name>.sourceTime mit dem in diesem Abschnitt beschriebenen Prozess aktualisieren. Weitere Informationen zu diesem Feld und anderen Feldern, die für digitale Zwillinge beschreibbar sind, finden Sie unter JSON-Format für digitale Zwillinge.

Aktualisieren von Untereigenschaften in Komponenten digitaler Zwillinge

Erinnern Sie sich daran, dass ein Modell Komponenten enthalten kann, sodass es aus anderen Modellen besteht.

Zum Patchen von Eigenschaften in den Komponenten eines digitalen Zwillings können Sie die Pfadsyntax im JSON-Patch verwenden:

[
  {
    "op": "replace",
    "path": "/mycomponentname/mass",
    "value": 0.0799
  }
]

Aktualisieren von Untereigenschaften in Objekttypeigenschaften

Modelle können Eigenschaften eines Objekttyps enthalten. Diese Objekte verfügen möglicherweise über eigene Eigenschaften, und Sie möchten möglicherweise eine dieser Untereigenschaften aktualisieren, die zur Objekttypeigenschaft gehören. Dieser Prozess ähnelt dem Prozess zum Aktualisieren von Untereigenschaften in Komponenten, erfordert jedoch möglicherweise einige zusätzliche Schritte.

Stellen Sie sich ein Modell mit der Objekttypeigenschaft ObjectProperty vor. ObjectProperty verfügt über eine Zeichenfolgeneigenschaft namens StringSubProperty.

Wenn ein Zwilling mit diesem Modell erstellt wird, ist es nicht erforderlich, die ObjectProperty zu diesem Zeitpunkt zu instanziieren. Wenn die Objekteigenschaft während der Erstellung des Zwillings nicht instanziiert wird, wird kein Standardpfad für den Zugriff auf ObjectProperty und die zugehörige StringSubProperty für einen Patchvorgang erstellt. Sie müssen den Pfad ObjectProperty selbst hinzufügen, bevor Sie dessen Eigenschaften aktualisieren können.

Dies kann mit einem JSON-Patchvorgang vom Typ add wie folgt geschehen:

[
  {
    "op": "add", 
    "path": "/ObjectProperty", 
    "value": {"StringSubProperty":"<string-value>"}
  }
]

Hinweis

Wenn ObjectProperty über mehrere Eigenschaften verfügt, sollten Sie alle Eigenschaften in das value-Feld dieses Vorgangs einbeziehen, auch wenn Sie nur Eigenschaft eine aktualisieren:

... "value": {"StringSubProperty":"<string-value>", "Property2":"<property2-value>", ...}

Nachdem dies einmal erfolgt ist, ist ein Pfad zu StringSubProperty vorhanden, und sie kann von nun an direkt mit einem typischen replace-Vorgang aktualisiert werden:

[
  {
    "op": "replace",
    "path": "/ObjectProperty/StringSubProperty",
    "value": "<string-value>"
  }
]

Obwohl der erste Schritt in Fällen, in denen ObjectProperty beim Erstellen des Zwillings instanziiert wurde, nicht erforderlich ist, empfiehlt es sich, sie jedes Mal zu verwenden, wenn Sie eine Untereigenschaft zum ersten Mal aktualisieren, da Sie möglicherweise nicht immer mit Sicherheit wissen, ob die Objekteigenschaft anfänglich instanziiert wurde oder nicht.

Aktualisieren eines Modells eines digitalen Zwillings

Die UpdateDigitalTwin()-Funktion kann auch verwendet werden, um einen digitalen Zwilling zu einem anderen Modell zu migrieren.

Sehen Sie sich beispielsweise das folgende JSON Patch-Dokument an, das das $model-Metadatenfeld des digitalen Zwillings ersetzt:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Dieser Vorgang ist nur erfolgreich, wenn der digitale Zwilling, der vom Patch geändert wird, dem neuen Modell entspricht.

Betrachten Sie das folgenden Beispiel:

Stellen Sie sich einen digitalen Zwilling mit dem Modell foo_old vor. foo_old definiert eine erforderliche Eigenschaftsmasse.
Das neue Modell foo_new definiert eine Eigenschaftsmasse und fügt eine neue erforderliche Eigenschaftstemperatur hinzu.
Nach dem Patch muss der digitale Zwilling die beiden Eigenschaften „mass“ und „temperature“ aufweisen.

Der Patch für diese Situation muss sowohl das Modell als auch die Eigenschaft „temperature“ des Zwillings wie folgt aktualisieren:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo_new;1"
  },
  {
    "op": "add",
    "path": "/temperature",
    "value": 60
  }
]

Aktualisieren der sourceTime einer Eigenschaft

Sie können optional entscheiden, das sourceTime Feld für Zwillingseigenschaften zu verwenden, um Zeitstempel aufzuzeichnen, für die Eigenschaftsaktualisierungen in der realen Welt beobachtet werden. Azure Digital Twins unterstützt sourceTime nativ in den Metadaten für jede Zwillingseigenschaft. Der sourceTime-Wert muss dem Datums- und Uhrzeitformat ISO 8601 entsprechen. Weitere Informationen zu diesem Feld und anderen Feldern für digitale Zwillinge finden Sie unter JSON-Format für digitale Zwillinge.

Die niedrigste stabile Version der REST-API, die dieses Feld unterstützt, ist die Version 2022-05-31. Um mit diesem Feld mit den Azure Digital Twins-SDKs zu arbeiten, wird empfohlen, die neueste Version des SDK zu verwenden, um sicherzustellen, dass dieses Feld enthalten ist.

Im Folgenden sehen Sie ein Beispiel für ein JSON Patch-Dokument, das sowohl den Wert als auch das Feld sourceTime einer Temperature-Eigenschaft aktualisiert:

[
  {
    "op": "replace",
    "path": "/Temperature",
    "value": "22.3"
  },
  {
    "op": "replace",
    "path": "/$metadata/Temperature/sourceTime",
    "value": "2021-11-30T18:47:53.7648958Z"
  }
]

Um das Feld sourceTime für eine Eigenschaft zu aktualisieren, die Teil einer Komponente ist, schließen Sie die Komponente am Anfang des Pfads ein. Im obigen Beispiel müsste daher der Pfad von /$metadata/Temperature/sourceTime in myComponent/$metadata/Temperature/sourceTime geändert werden.

Hinweis

Wenn Sie sowohl sourceTime als auch den Wert für eine Eigenschaft aktualisieren und später nur den Wert der Eigenschaft aktualisieren, bleibt der sourceTime-Zeitstempel aus dem ersten Update erhalten.

Verarbeitung von in Konflikt stehenden Updateaufrufen

Azure Digital Twins stellt sicher, dass alle eingehenden Anforderungen nacheinander verarbeitet werden. Dies bedeutet, dass Sie selbst dann, wenn mehrere Funktionen versuchen, dieselbe Eigenschaft für einen Zwilling gleichzeitig zu aktualisieren, keinen expliziten Sperrcode schreiben müssen, um den Konflikt zu beheben.

Dieses Verhalten erfolgt für jeden Zwilling einzeln.

Stellen Sie sich beispielsweise ein Szenario vor, in dem die folgenden drei Aufrufe gleichzeitig eingehen:

Schreiben von Eigenschaft A auf Zwilling1
Schreiben von Eigenschaft B auf Zwilling1
Schreiben von Eigenschaft A auf Zwilling2

Die beiden Aufrufe, die Zwilling1 ändern, werden nacheinander ausgeführt, und für jede Änderung werden Änderungsnachrichten generiert. Der Aufruf zum Ändern von Twin2 kann gleichzeitig ohne Konflikte ausgeführt werden, sobald er eintrifft.

Löschen eines digitalen Zwillings

Sie können Zwillinge mithilfe der DeleteDigitalTwin()-Methode löschen. Sie können einen Zwilling jedoch nur löschen, wenn er keine weiteren Beziehungen aufweist. Daher löschen Sie zuerst die ein- und ausgehenden Beziehungen des Zwillings.

Hier ist ein Beispiel für den Code zum Löschen von Zwillingen und deren Beziehungen. Der DeleteDigitalTwin-SDK-Aufruf ist hervorgehoben, um zu verdeutlichen, inwiefern er Teil des breiteren Beispielkontexts ist.

private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
    await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
    await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
    try
    {
        await client.DeleteDigitalTwinAsync(twinId);
        Console.WriteLine("Twin deleted successfully");
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error:{ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);

        await foreach (BasicRelationship rel in rels)
        {
            await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
            Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);

        await foreach (IncomingRelationship incomingRel in incomingRels)
        {
            await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
            Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
    }
}

Löschen aller digitalen Zwillinge

Ein Beispiel für das gleichzeitige Löschen aller Zwillinge finden Sie in der Beispiel-App unter Erkunden von Azure Digital Twins mit einer Beispielclient-App. In der Datei CommandLoop.cs wird dies in einer CommandDeleteAllTwins()-Funktion durchgeführt.

Hinweis

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

Ausführbares Codebeispiel für digitale Zwillinge

Sie können das folgende ausführbare Codebeispiel verwenden, um einen Zwilling zu erstellen, seine Details zu aktualisieren und den Zwilling zu löschen.

Einrichten von Beispielprojektdateien

Der Codeausschnitt verwendet eine Beispielmodelldefinition: Room.json. Um die Modelldatei herunterzuladen, damit Sie sie in Ihrem Code verwenden können, verwenden Sie diesen Link, um direkt zur Datei in GitHub zu navigieren. Klicken Sie dann mit der rechten Maustaste auf eine beliebige Stelle auf dem Bildschirm, wählen Sie im Kontextmenü Ihres Browsers Speichern unter aus, und verwenden Sie das Fenster „Speichern unter“, um die Datei als Room.json zu speichern.

Erstellen Sie als Nächstes ein neues Konsolen-App-Projekt in Visual Studio oder einem Editor Ihrer Wahl.

Kopieren Sie dann den folgenden Code des ausführbaren Beispiels in Ihr Projekt:

using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Azure;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System.IO;

namespace DigitalTwins_Samples
{
    class TwinOperationsSample
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Hello World!");

            // Create the Azure Digital Twins client for API calls
            string adtInstanceUrl = "https://<your-instance-hostname>";
            var credentials = new DefaultAzureCredential();
            var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credentials);
            Console.WriteLine($"Service client created – ready to go");

            // Upload models
            Console.WriteLine($"Upload a model");
            string dtdl = File.ReadAllText("<path-to>/Room.json");
            var models = new List<string> { dtdl };
            // Upload the model to the service
            await client.CreateModelsAsync(models);

            // Create new digital twin
            // <CreateTwin_withHelper>
            string twinId = "myTwinID";
            var initData = new BasicDigitalTwin
            {
                Id = twinId,
                Metadata = { ModelId = "dtmi:example:Room;1" },
                // Initialize properties
                Contents =
                {
                    { "Temperature", 25.0 },
                    { "Humidity", 50.0 },
                },
            };

            // <CreateTwinCall>
            await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
            // </CreateTwinCall>
            // </CreateTwin_withHelper>
            Console.WriteLine("Twin created successfully");

            //Print twin
            Console.WriteLine("--- Printing twin details:");
            await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
            Console.WriteLine("--------");

            //Update twin data
            var updateTwinData = new JsonPatchDocument();
            updateTwinData.AppendAdd("/Temperature", 30.0);
            // <UpdateTwinCall>
            await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
            // </UpdateTwinCall>
            Console.WriteLine("Twin properties updated");
            Console.WriteLine();

            //Print twin again
            Console.WriteLine("--- Printing twin details (after update):");
            await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
            Console.WriteLine("--------");
            Console.WriteLine();

            //Delete twin
            await CustomMethod_DeleteTwinAsync(client, twinId);
        }

        private static async Task<BasicDigitalTwin> CustomMethod_FetchAndPrintTwinAsync(string twinId, DigitalTwinsClient client)
        {
            // <GetTwin>
            BasicDigitalTwin twin;
            // <GetTwinCall>
            Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
            twin = twinResponse.Value;
            // </GetTwinCall>
            Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
            foreach (string prop in twin.Contents.Keys)
            {
                if (twin.Contents.TryGetValue(prop, out object value))
                    Console.WriteLine($"Property '{prop}': {value}");
            }
            // </GetTwin>

            return twin;
        }

        // <DeleteTwin>
        private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
        {
            await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
            await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
            try
            {
                await client.DeleteDigitalTwinAsync(twinId);
                Console.WriteLine("Twin deleted successfully");
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error:{ex.Message}");
            }
        }

        private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
        {
            // Find the relationships for the twin

            try
            {
                // GetRelationshipsAsync will throw an error if a problem occurs
                AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);

                await foreach (BasicRelationship rel in rels)
                {
                    await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
                    Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
                }
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
            }
        }

        private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
        {
            // Find the relationships for the twin

            try
            {
                // GetRelationshipsAsync will throw an error if a problem occurs
                AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);

                await foreach (IncomingRelationship incomingRel in incomingRels)
                {
                    await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
                    Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
                }
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
            }
        }
        // </DeleteTwin>

    }
}

Hinweis

Es gibt derzeit ein bekanntes Problem, das die DefaultAzureCredential-Wrapperklasse betrifft und zu einem Fehler bei der Authentifizierung führen kann. Wenn dieses Problem auftritt, können Sie zum Beheben des Problems versuchen, DefaultAzureCredential mit dem folgenden optionalen Parameter zu instanziieren: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Weitere Informationen zu diesem Problem finden Sie unter Bekannte Probleme von Azure Digital Twins.

Projekt konfigurieren

Führen Sie als dann die folgenden Schritte aus, um den Projektcode zu konfigurieren:

Fügen Sie Ihrem Projekt die Datei Room.json hinzu, die Sie zuvor heruntergeladen haben, und ersetzen Sie den Platzhalter <path-to> im Code, um dem Programm den Pfad mitzuteilen.
Ersetzen Sie den Platzhalter <your-instance-hostname> durch den Hostnamen Ihrer Azure Digital Twins-Instanz.
Fügen Sie Ihrem Projekt zwei Abhängigkeiten hinzu, die für die Arbeit mit Azure Digital Twins erforderlich sind. Bei der ersten handelt es sich um das Paket für das Azure Digital Twins SDK für .NET, und die zweite stellt Tools zur Unterstützung der Authentifizierung bei Azure bereit.
```
dotnet add package Azure.DigitalTwins.Core
dotnet add package Azure.Identity
```

Sie müssen auch lokale Anmeldeinformationen einrichten, wenn Sie das Beispiel direkt ausführen möchten. Im nächsten Abschnitt werden diese Schritte erläutert.

Einrichten lokaler Azure-Anmeldeinformationen

Dieses Beispiel verwendet DefaultAzureCredential (Teil der Azure.Identity-Bibliothek) zur Authentifizierung von Benutzern mit der Azure Digital Twins-Instanz, wenn Sie diese auf Ihrem lokalen Computer ausführen. Weitere Informationen zu den verschiedenen Möglichkeiten, wie sich eine Client-App bei Azure Digital Twins authentifizieren kann, finden Sie unter Schreiben von App-Authentifizierungscode.

Mit DefaultAzureCredential sucht das Beispiel nach Anmeldeinformationen in Ihrer lokalen Umgebung, wie eine Azure-Anmeldung in einer lokalen DefaultAzureCredential oder in Visual Studio oder Visual Studio Code. Aus diesem Grund sollten Sie sich lokal über einen dieser Mechanismen bei Azure anmelden, um Anmeldeinformationen für das Beispiel einzurichten.

Wenn Sie Visual Studio oder Visual Studio Code zum Ausführen von Codebeispielen verwenden, stellen Sie sicher, dass Sie bei diesem Editor mit denselben Anmeldeinformationen für Azure angemeldet sind, die Sie für den Zugriff auf Ihre Instanz von Azure Digital Twins verwenden möchten. Wenn Sie ein lokales CLI-Fenster verwenden, führen Sie den Befehl az login aus, um sich bei Ihrem Azure-Konto anzumelden. Wenn Sie danach Ihr Codebeispiel ausführen, sollten Sie automatisch authentifiziert werden.

Ausführen des Beispiels

Nachdem das Setup abgeschlossen ist, können Sie das Beispielcodeprojekt ausführen.

Dies ist die Konsolenausgabe des obigen Programms:

Nächste Schritte

Erfahren Sie, wie Sie Beziehungen zwischen Ihren digitalen Zwillingen erstellen und verwalten können:

Verwalten des Zwillingsdiagramms und der Beziehungen

Verwalten digitaler Zwillinge

Voraussetzungen

Entwicklerschnittstellen

Visualisierung

Erstellen eines digitalen Zwillings

Initialisieren des Modells und der Eigenschaften

Erstellen von Zwillingen mithilfe manuell erstellter Daten

Erstellen von Zwillingen mithilfe der Hilfsklasse

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

Abrufen von Daten für einen digitalen Zwilling

Anzeigen aller digitalen Zwillinge

Aktualisieren eines digitalen Zwillings

Aktualisieren von Untereigenschaften in Komponenten digitaler Zwillinge

Aktualisieren von Untereigenschaften in Objekttypeigenschaften

Aktualisieren eines Modells eines digitalen Zwillings

Aktualisieren der sourceTime einer Eigenschaft

Verarbeitung von in Konflikt stehenden Updateaufrufen

Löschen eines digitalen Zwillings

Löschen aller digitalen Zwillinge

Ausführbares Codebeispiel für digitale Zwillinge

Einrichten von Beispielprojektdateien

Projekt konfigurieren

Einrichten lokaler Azure-Anmeldeinformationen

Ausführen des Beispiels

Nächste Schritte

Zusätzliche Ressourcen