Verwalten digitaler Zwillinge

Artikel
01/03/2024

Entitäten in Ihrer Umgebung werden durch digital Zwillinge dargestellt. Die Verwaltung digitaler Zwillinge kann das Erstellen, Ändern und Löschen 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
Jede gewünschte Initialisierung 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 ist jeweils ein Beispiel.

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. Sie sollten dennoch die Liste der Eigenschaften mit Dictionary<string, object> erstellen, was dann dem Zwillingsobjekt direkt als CustomProperties hinzugefügt werden kann.

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. Zum Beispiel:

twin.Id = "myRoomId";

Erstellen von Zwillingen per Massenvorgang mit der API zum Importieren von Aufträgen

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

Tipp

Die API zum Importieren von Aufträgen ermöglicht es auch, Modelle und Beziehungen im selben Aufruf zu importieren, um alle Graph-Teile gleichzeitig zu erstellen. Weitere Informationen zu diesem Prozess finden Sie unter Hochladen von Modellen, Zwillingen und Beziehungen in Massen mit der API zum Importieren von Aufträgen.

Zum Massenimport von Zwillingen müssen Sie Ihre Zwillinge (und alle anderen Ressourcen im Massenimportauftrag) als NDJSON-Datei strukturieren. Der Abschnitt Twins kommt nach dem Abschnitt Models (und vor dem Abschnitt Relationships). In der Datei definierte Zwillinge können auf Modelle verweisen, die entweder in dieser Datei definiert 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 in die API zum Importieren von Aufträgen anzeigen.

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

Nachdem die NDJSON-Datei in den Container hochgeladen wurde, rufen Sie die URL innerhalb des Blob-Containers ab. Sie verwenden diesen Wert später im Textkörper des API-Aufrufs für den Massenimport.

Hier ist ein Screenshot mit dem URL-Wert einer Blob-Datei im Azure-Portal:

Anschließend kann die Datei in einem Aufruf der API zum Importieren von Aufträgen verwendet werden. Sie geben die Blobspeicher-URL der Eingabedatei sowie eine neue Blobspeicher-URL an, um festzulegen, wo das Ausgabeprotokoll gespeichert werden soll, nachdem es vom Dienst erstellt wurde.

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 und die die zentralen Zwillingsmetadaten und -eigenschaften in einem vorab geparsten Format 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 Beispielen zur Abfrage-API unter Abfragen des Zwillingsgraphen.

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 von object result = await client.GetDigitalTwinAsync("my-moon"); für einen Zwilling vom Typ „Moon“ kann 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: DTMI des Modells für den digitalen Zwilling
- lastUpdateTime für Zwillingseigenschaften. Dies ist ein Zeitstempel, der das Datum und die Uhrzeit angibt, an dem bzw. zu dem Azure Digital Twins die Eigenschaftsupdatemeldung verarbeitet hat.
- sourceTime für Zwillingseigenschaften. Dies ist eine optionale, beschreibbare Eigenschaft, die den Zeitstempel darstellt, als das Update der Eigenschaft in der realen Welt beobachtet wurde.

Weitere Informationen zu den in einem digitalen Zwilling enthaltenen Feldern finden Sie unter JSON-Format von digitalen Zwillingen. 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.

Im Folgenden finden Sie den Text 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 für mehrere Zwillinge aktualisieren müssen, benötigen Sie für jeden Zwilling einen separaten Updateaufruf.

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

Denken Sie 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 mit einem Objekttyp enthalten. Diese Objekte verfügen möglicherweise über eigene Eigenschaften, und Sie möchten möglicherweise eine dieser Untereigenschaften aktualisieren, die zur Objekttypeigenschaft gehört. 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 zu ObjectProperty selbst hinzufügen, bevor Sie die 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 notwendig ist, wird empfohlen, ihn jedes Mal auszuführen, wenn Sie eine Untereigenschaft zum ersten Mal aktualisieren, da Sie nicht immer mit Sicherheit wissen, ob die Objekteigenschaft ursprü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 vom Patch geänderte digitale Zwilling 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 mass-Eigenschaft.
Das neue Modell „foo_new“ definiert die Eigenschaften „mass“ und fügt die neue erforderliche Eigenschaft temperature 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

Optional können Sie das Feld sourceTime für Zwillingseigenschaften verwenden, um Zeitstempel für den Zeitpunkt aufzuzeichnen, zu dem 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 Zwilling2 kann ohne Konflikt zeitgleich ausgeführt werden, sobald er eingeht.

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 folgt ein Beispiel für den Code zum Löschen von Zwillingen und ihren 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 API zum Löschen von Aufträgen.

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 erforderlich sind, um Azure Digital Twins verwenden zu können. 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 Sie das Setup abgeschlossen haben, können Sie nun das Beispielcodeprojekt ausführen.

Hier 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 Zwillingsgraphen und der Beziehungen

Teilen über

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 per Massenvorgang mit der API zum Importieren von Aufträgen

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

Feedback

Zusätzliche Ressourcen