Verwalten von Azure Digital Twins-Modellen

In diesem Artikel wird beschrieben, wie Sie die Modelle in Ihrer Azure Digital Twins-Instanz verwalten. Zu den Verwaltungsvorgängen gehören das Hochladen, Überprüfen, Abrufen und Löschen von Modellen.

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:

• Azure Digital Twins-Explorer
• REST-API-Aufrufe
• Azure CLI-Befehle

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 von Modellen

Sie können eigene Modelle von Grund auf neu erstellen oder vorhandene Ontologien verwenden, die für Ihre Branche verfügbar sind.

Autorenmodelle

Modelle für Azure Digital Twins werden in DTDL geschrieben und als JSON-Dateien gespeichert. Für Visual Studio Code gibt es auch eine DTDL-Erweiterung, die die Syntaxüberprüfung und andere Features zum Schreiben von DTDL-Dokumenten umfasst.

Angenommen, ein Krankenhaus möchte seine Räume digital überwachen. Jeder Raum enthält einen intelligenten Seifenspender, der das Händewaschen überwacht, sowie Sensoren, die den Durchgangsverkehr im Raum nachverfolgen.

Der erste Schritt zur Lösung besteht darin, Modelle zu erstellen, die verschiedene Aspekte des Krankenhauses darstellen. In diesem Szenario kann ein Patientenzimmer wie folgt beschrieben werden:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Hinweis

Dies ist ein Beispieltext für eine JSON-Datei, in der ein Modell definiert und gespeichert wird, das als Teil eines Clientprojekts hochgeladen werden soll. Der REST-API-Aufruf hingegen verwendet ein Array mit Modelldefinitionen wie die obige (die einer IEnumerable<string> im .NET SDK zugeordnet ist). Damit Sie dieses Modell direkt in der REST-API verwenden können, sollten Sie es in Klammern setzen.

Dieses Modell definiert einen Namen und eine eindeutige ID für das Patientenzimmer sowie Eigenschaften zur Darstellung der Anzahl der Besucher und zum Status des Händewaschens. Diese Zähler werden von Bewegungssensoren und intelligenten Seifenspendern aktualisiert und zusammen verwendet, um eine handwash percentage Eigenschaft zu berechnen. Das Modell definiert außerdem eine hasDevices-Beziehung, die verwendet wird, um einen digitalen Zwilling basierend auf dem Raummodell mit den tatsächlichen Geräten zu verbinden.

Hinweis

Es gibt einige DTDL-Features, die Azure Digital Twins derzeit nicht unterstützt, einschließlich des writable Attributs für Eigenschaften und Beziehungen sowie minMultiplicity und maxMultiplicity für Beziehungen. Weitere Informationen finden Sie unter Dienstspezifische DTDL-Notizen.

Nach dieser Methode können Sie Modelle für die Stationen, Zonen oder das Krankenhaus selbst definieren.

Wenn Sie ein umfassendes Modellset erstellen möchten, das Ihre Branche beschreibt Standard, überlegen Sie, ob es eine vorhandene Branchen-Ontologie gibt, die Sie verwenden können, um die Modellerstellung zu vereinfachen. Im nächsten Abschnitt werden branchenspezifische Ontologien ausführlicher beschrieben.

Verwenden vorhandener Branchenstandard-Ontologien

Eine Ontologie ist eine Reihe von Modellen, die eine bestimmte Do umfassend beschreiben Standard wie Fertigung, Gebäudestrukturen, IoT-Systeme, Smart Cities, Energienetze, Webinhalte und vieles mehr.

Wenn Ihre Lösung für eine bestimmte Branche geeignet ist, die irgendeine Art von Modellierungsstandard verwendet, sollten Sie mit einem bereits vorhandenen Satz von Modellen beginnen, die für Ihre Branche entwickelt wurden, anstatt Ihre Modelle von Grund auf neu zu entwerfen. Microsoft hat sich mit do Standard Experten zusammengetan, um DTDL-Modell-Ontologien basierend auf Branchenstandards zu erstellen, um die Neufindung zu minimieren und Konsistenz und Einfachheit in branchenübergreifenden Lösungen zu fördern. Weitere Informationen zu diesen Ontologien, einschließlich ihrer Verwendung und der verfügbaren Ontologien, finden Sie unter Was ist eine Ontologie?.

Überprüfen der Syntax

Nachdem Sie ein Modell erstellt haben, sollten Sie Ihre Modelle offline validieren, bevor Sie sie in Ihre Azure Digital Twins-Instanz hochladen.

Um Ihre Modelle zu überprüfen, wird eine clientseitige DTDL-Analysebibliothek für .NET auf NuGet: DTDLParser bereitgestellt. Sie können die Parserbibliothek direkt in Ihrem C#-Code verwenden. Sie können auch die Beispielverwendung des Parsers im DTDLParserResolveSample in GitHub anzeigen.

Hochladen von Modellen

Nachdem Sie Modelle erstellt haben, können Sie sie in die Azure Digital Twins-Instanz hochladen.

Wenn Sie zum Hochladen eines Modells bereit sind, können Sie den folgenden Codeausschnitt für das .NET SDK verwenden:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

Modelldateien werden beim Hochladen vom Dienst überprüft.

Normalerweise müssen Sie mehrere Modelle in den Dienst hochladen. Es gibt mehrere Möglichkeiten, viele Modelle gleichzeitig in einer einzelnen Transaktion hochzuladen. Um Ihnen bei der Auswahl einer Strategie zu helfen, sollten Sie die Größe Ihres Modellsatzes berücksichtigen, während Sie den Rest dieses Abschnitts fortsetzen.

Hochladen kleiner Modellsätze

Bei kleineren Modellsätzen können Sie mehrere Modelle gleichzeitig mithilfe einzelner API-Aufrufe hochladen. Sie können den aktuellen Grenzwert überprüfen, wie viele Modelle in einem einzelnen API-Aufruf in den Azure Digital Twins-Grenzwerten hochgeladen werden können.

Wenn Sie das SDK verwenden, können Sie mehrere Modelldateien mit der CreateModels-Methode wie folgt hochladen:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Wenn Sie die REST-APIs oder azure CLI verwenden, können Sie mehrere Modelle hochladen, indem Sie mehrere Modelldefinitionen in eine einzelne JSON-Datei einfügen, die zusammen hochgeladen werden soll. In diesem Fall sollten die Modelle wie im folgenden Beispiel in einem JSON-Array innerhalb der Datei platziert werden:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Hochladen großer Modellsätze mit der Importaufträge-API

Bei großen Modellsätzen können Sie die Importaufträge-API verwenden, um viele Modelle gleichzeitig in einem einzigen API-Aufruf hochzuladen. Die API kann gleichzeitig bis zum Azure Digital Twins-Grenzwert für die Anzahl von Modellen in einer Instanz akzeptieren und modelle bei Bedarf automatisch neu anordnen, um Abhängigkeiten zwischen ihnen aufzulösen. Diese Methode erfordert die Verwendung von Azure Blob Storage sowie Schreibberechtigungen in Ihrer Azure Digital Twins-Instanz für Modelle und Massenaufträge.

Tipp

Die Importaufträge-API ermöglicht es auch, Zwillinge und Beziehungen im selben Aufruf zu importieren, 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.

Zum Massenimport von Modellen müssen Sie Ihre Modelle (und alle anderen Ressourcen, die im Massenimportauftrag enthalten sind) als NDJSON-Datei strukturieren. Der Models Abschnitt kommt unmittelbar nach Header dem Abschnitt und macht ihn zum ersten Diagrammdatenabschnitt in der Datei. 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 geben die BLOB-Speicher-URL der Eingabedatei sowie eine neue BLOB-Speicher-URL an, um anzugeben, wo das Ausgabeprotokoll gespeichert werden soll, wenn es vom Dienst erstellt wird.

Abrufen von Modellen

Sie können Modelle auflisten und abrufen, die auf Ihrer Azure Digital Twins-Instanz gespeichert sind.

Ihre Optionen umfassen:

• Ein einzelnes Modell abrufen
• Alle Modelle abrufen
• Abrufen von Metadaten und Abhängigkeiten für Modelle

Hier sehen Sie ein paar Beispielaufrufe:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

Die SDK-Aufrufe zum Abrufen von Modellen geben alle DigitalTwinsModelData-Objekte zurück. DigitalTwinsModelData enthält Metadaten zum Modell, das in der Azure Digital Twins-Instanz gespeichert ist, z. B. Name, DTMI und Erstellungsdatum des Modells. Das Objekt DigitalTwinsModelData kann auch das Modell selbst enthalten. Das heißt: Je nach Parametern können Sie die Abrufaufrufe verwenden, um entweder nur Metadaten (was z. B. nützlich ist, wenn Sie eine Liste verfügbarer Tools für die Benutzeroberfläche anzeigen möchten) oder das gesamte Modell abzurufen.

Der Aufruf RetrieveModelWithDependencies gibt nicht nur das angeforderte Modell zurück, sondern auch alle Modelle, von denen das angeforderte Modell abhängig ist.

Modelle werden nicht unbedingt genau in dem Dokumentformat zurückgegeben, in dem sie hochgeladen wurden. Azure Digital Twins gewährleistet nur, dass das Rückgabeformat semantisch gleichwertig ist.

Aktualisieren von Modellen

In diesem Abschnitt werden Überlegungen und Strategien zum Aktualisieren von Modellen beschrieben.

Vor dem Aktualisieren: Berücksichtigung des Kontexts der gesamten Lösung

Bevor Sie Modelle aktualisieren, sollten Sie in ganzheitlicher Weise über die gesamte Lösung und die Auswirkungen der Modelländerungen nachdenken, die Sie vornehmen werden. Modelle in einer Azure Digital Twins-Lösung sind häufig miteinander verbunden. Daher ist es wichtig, sich kaskadierende Änderungen bewusst zu machen, bei denen die Aktualisierung eines Modells das Aktualisieren mehrerer anderer erfordert. Das Aktualisieren von Modellen wirkt sich auf die Zwillinge aus, die die Modelle verwenden, und kann sich auch auf den Eingangs- und Verarbeitungscode, Clientanwendungen und automatisierte Berichte auswirken.

Im Folgenden finden Sie einige Empfehlungen, mit deren Hilfe Sie Modellübergänge reibungslos verwalten können:

• Statt sich Modelle als getrennte Entitäten vorzustellen, sollten Sie erwägen, bei Bedarf den gesamten Modellsatz weiterzuentwickeln, um bei Bedarf Modelle und ihre Beziehungen gemeinsam auf dem aktuellen Stand zu halten.
• Behandeln Sie Modelle wie Quellcode, und verwalten Sie sie in der Quellcodeverwaltung. Behandeln Sie Modelle und Modelländerungen mit derselben Strenge und Aufmerksamkeit wie anderen Code in der Lösung.

Wenn Sie bereit sind, mit dem Aktualisieren der Modelle fortzufahren, lesen Sie den restlichen Teil dieses Abschnitts, in dem die Strategien beschrieben werden, die Sie zum Implementieren der Aktualisierungen verwenden können.

Strategien zum Aktualisieren von Modellen

Sobald ein Modell in die Azure Digital Twins-Instanz hochgeladen wurde, ist die Modellschnittstelle unveränderlich. Dies bedeutet, dass keine herkömmliche „Bearbeitung“ von Modellen möglich ist. Azure Digital Twins lässt auch kein erneutes Hochladen desselben Modells zu, wenn in der Instanz bereits ein übereinstimmendes Modell vorhanden ist.

Stattdessen müssen Sie das ursprüngliche Modell ersetzen, wenn Sie Änderungen an einem Modell vornehmen möchten, z. B. displayName oder description aktualisieren oder Eigenschaften hinzufügen und entfernen.

Beim Ersetzen eines Modells stehen zwei Strategien zur Auswahl:

• Strategie 1: Hochladen einer neuen Modellversion: Laden Sie das Modell mit einer neuen Versionsnummer hoch, und aktualisieren Sie die Zwillinge, um dieses neue Modell zu verwenden. Sowohl die neue als auch die alte Version des Modells sind in der Instanz vorhanden, bis Sie eine Version löschen.
  • Verwenden Sie diese Strategie, wenn Sie nur einige der Zwillinge aktualisieren möchten, die das Modell verwenden, oder wenn Sie sicherstellen möchten, dass Zwillinge ihren Modellen entsprechen und während des Modellübergangs beschreibbar sind.
• Strategie 2: Löschen des alten Modells und erneutes Hochladen: Löschen Sie das ursprüngliche Modell, und laden Sie das neue Modell mit demselben Namen und derselben ID (DTMI-Wert) hoch. Dadurch wird das alte Modell vollständig durch das neue ersetzt.
  • Verwenden Sie diese Strategie, wenn Sie alle Zwillinge aktualisieren möchten, die dieses Modell gleichzeitig verwenden, sowie den ganzen Code, der auf die Modelle reagiert. Wenn die Modellaktualisierung eine Breaking Change enthält, stimmen Zwillinge während des Übergangs vom alten zum neuen Modell eine kurze Zeit lang nicht mit ihren Modellen überein. Dies bedeutet, dass sie erst wieder aktualisiert werden können, wenn das neue Modell hochgeladen wurde und die Zwillinge dem Modell entsprechen.

Hinweis

Von Breaking Changes an Modellen außerhalb der Entwicklung wird abgeraten.

In den nächsten Abschnitten werden die einzelnen Strategieoption detaillierter erläutert.

Strategie 1: Hochladen einer neuen Modellversion

Diese Option umfasst das Erstellen einer neuen Version des Modells und das Hochladen in die Instanz.

Dieser Vorgang überschreibt keine früheren Versionen des Modells, sodass mehrere Versionen des Modells in Ihrer Instanz koexistieren, bis Sie sie entfernen. Da die neue und die alte Modellversion nebeneinander vorhanden sind, können Zwillinge entweder die neue Version des Modells oder die ältere Version verwenden. Dies bedeutet, dass das Hochladen einer neuen Version eines Modells nicht automatisch Auswirkungen auf vorhandene Zwillinge hat. Die vorhandenen Zwillinge bleiben als Instanzen der alten Modellversion erhalten, und Sie können diese Zwillinge auf die neue Modellversion aktualisieren, indem Sie sie patchen.

Zur Verwendung dieser Strategie führen Sie die folgenden Schritte aus:

1. Erstellen und Hochladen einer neuen Modellversion

Um eine neue Version eines bestehenden Modells zu erstellen, beginnen Sie mit der DTDL des ursprünglichen Modells. Sie können die Felder, die Sie ändern möchten, aktualisieren, hinzufügen oder entfernen.

Markieren Sie dieses Modell dann als neuere Version des Modells, indem Sie das id-Feld des Modells aktualisieren. Der letzte Abschnitt der Modell-ID, nach dem ;, stellt die Modellnummer dar. Damit Sie anzeigen können, dass es sich jetzt um eine aktualisierte Version dieses Modells handelt, erhöhen Sie die Zahl am Ende des id-Werts auf eine beliebige Zahl, die größer als die aktuelle Versionsnummer ist.

Wenn Ihre frühere Modell-ID z. B. so aussah:

"@id": "dtmi:com:contoso:PatientRoom;1",

Version 2 dieses Modells könnte wie folgt aussehen:

"@id": "dtmi:com:contoso:PatientRoom;2",

Dann können Sie die neue Version des Modells in die Instanz hochladen.

Diese Version des Modells wird dann in Ihrer Instanz für digitale Zwillinge zur Verfügung stehen. Frühere Versionen des Modells werden nicht überschrieben, sodass jetzt in Ihrer Instanz mehrere Versionen des Modells gleichzeitig vorhanden sind.

2. Aktualisieren von Graphelementen nach Bedarf

Aktualisieren Sie als Nächstes die Zwillinge und Beziehungen in der Instanz, um die neue Modellversion anstelle der alten zu verwenden.

Zum Aktualisieren der Zwillinge und Aktualisieren der Beziehungen können Sie die folgenden Anweisungen verwenden. Der Patchvorgang zum Aktualisieren des Modells eines Zwillings sieht in etwa wie folgt aus:

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

Wichtig

Verwenden Sie beim Aktualisieren von Zwillingen denselben Patch, um sowohl die Modell-ID (auf die neue Modellversion) und alle Felder zu aktualisieren, die im Zwilling geändert werden müssen, damit sie mit dem neuen Modell übereinstimmen.

Möglicherweise müssen Sie auch Beziehungen und andere Modelle in der Instanz aktualisieren, die auf dieses Modell verweisen, damit sie auf die neue Modellversion verweisen. Zu diesem Zweck müssen Sie einen weiteren Modellaktualisierungsvorgang durchführen. Kehren Sie also zum Anfang dieses Abschnitts zurück, und wiederholen Sie den Vorgang für alle weiteren Modelle, die aktualisiert werden müssen.

3. (Optional) Außerbetriebnahme oder Löschung der alten Modellversion

Wenn Sie die alte Modellversion nicht mehr verwenden, können Sie das ältere Modell außer Betrieb nehmen. Mithilfe dieser Aktion kann das Modell in der Instanz bestehen bleiben, aber nicht zum Erstellen neuer digitaler Zwillinge verwendet werden.

Sie können das alte Modell auch vollständig löschen, wenn Sie es in der Instanz gar nicht mehr benötigen.

Die oben verlinkten Abschnitte enthalten Beispielcode und Überlegungen zum Außerbetriebnehmen und Löschen von Modellen.

Strategie 2: Löschen des alten Modells und erneutes Hochladen

Anstatt die Version eines Modells schrittweise zu erhöhen, können Sie ein Modell vollständig löschen und ein bearbeitetes Modell erneut in die Instanz hochladen.

In Azure Digital Twins ist kein Hinweis mehr darauf vorhanden, dass das alte Modell jemals hochgeladen wurde. Somit gleicht diese Aktion dem Hochladen eines völlig neuen Modells. Zwillinge, die das Modell verwenden, werden automatisch auf die neue Definition umgestellt, sobald es verfügbar ist. Je nachdem, wie sich die neue Definition von der alten unterscheidet, können diese Zwillinge Eigenschaften und Beziehungen aufweisen, die mit der gelöschten Definition übereinstimmen und für die neue Definition nicht gültig sind. Daher müssen Sie sie möglicherweise patchen, um sicherzustellen, dass sie gültig bleiben.

Zur Verwendung dieser Strategie führen Sie die folgenden Schritte aus:

1. Löschen des alten Modells

Da Azure Digital Twins zwei Modelle mit derselben ID nicht zulässt, löschen Sie zunächst das ursprüngliche Modell aus der Instanz.

Hinweis

Wenn Sie über andere Modelle verfügen, die von diesem Modell abhängen (durch Vererbung oder Komponenten), müssen Sie diese Verweise entfernen, bevor Sie das Modell löschen können. Sie können diese abhängigen Modelle zuerst aktualisieren, um die Verweise vorübergehend zu entfernen, oder die abhängigen Modelle löschen und in einem späteren Schritt erneut hochladen.

Gehen Sie folgendermaßen vor, um das ursprüngliche Modell zu löschen. Durch diese Aktion bleiben die Zwillinge, die dieses Modell verwendet haben, vorübergehend „verwaist“, da sie jetzt ein Modell verwenden, das nicht mehr vorhanden ist. Dieser Zustand wird im nächsten Schritt repariert, wenn Sie das aktualisierte Modell erneut hochladen.

2. Erstellen und Hochladen des neuen Modells

Beginnen Sie mit der DTDL des ursprünglichen Modells. Sie können die Felder, die Sie ändern möchten, aktualisieren, hinzufügen oder entfernen.

Laden Sie dann das Modell in die Instanz hoch, als wäre es ein neues Modell, das zum ersten Mal hochgeladen wird.

3. Aktualisieren von Graphelementen nach Bedarf

Nachdem das neue Modell nun statt des alten Modells hochgeladen wurde, beginnen die Zwillinge im Graph automatisch mit der Verwendung der neuen Modelldefinition, sobald die Zwischenspeicherung in der Instanz abläuft und zurückgesetzt wird. Dieser Vorgang kann je nach Graphgröße 10 bis 15 Minuten oder länger dauern. Danach sollte auf neue und geänderte Eigenschaften im Modell zugegriffen werden können; auf entfernte Eigenschaften kann nicht mehr zugegriffen werden.

Hinweis

Wenn Sie zuvor andere abhängige Modelle entfernt haben, um das ursprüngliche Modell zu löschen, laden Sie diese jetzt erneut hoch, nachdem der Cache zurückgesetzt wurde. Wenn Sie die abhängigen Modelle aktualisiert haben, um vorübergehend Verweise auf das ursprüngliche Modell zu entfernen, können Sie sie erneut aktualisieren, um den Verweis wiederherzustellen.

Aktualisieren Sie als Nächstes die Zwillinge und Beziehungen in der Instanz, damit ihre Eigenschaften mit den vom neuen Modell definierten Eigenschaften übereinstimmen. Bevor dieser Schritt abgeschlossen ist, können die Zwillinge, die nicht mit ihrem Modell übereinstimmen, weiterhin gelesen, aber nicht beschrieben werden. Weitere Informationen zum Zustand von Zwillingen ohne gültiges Modell finden Sie unter Zwillinge ohne Modelle.

Es gibt zwei Möglichkeiten, Zwillinge und Beziehungen für das neue Modell zu aktualisieren, damit sie wieder beschreibbar sind:

• Patchen Sie die Zwillinge und Beziehungen nach Bedarf, damit sie dem neuen Modell entsprechen. Zum Aktualisieren der Zwillinge und Aktualisieren der Beziehungen können Sie die folgenden Anweisungen verwenden.
  • Wenn Sie Eigenschaften hinzugefügt haben: Das Aktualisieren von Zwillingen und Beziehungen auf die neuen Werte ist nicht erforderlich, da Zwillinge, bei denen die neuen Werte fehlen, weiterhin gültige Zwillinge sind. Sie können sie jedoch patchen, wenn Sie Werte für die neuen Eigenschaften hinzufügen möchten.
  • Wenn Sie Eigenschaften entfernt haben: Sie müssen Zwillinge patchen, um die Eigenschaften zu entfernen, die jetzt mit dem neuen Modell ungültig sind.
  • Wenn Sie Eigenschaften aktualisiert haben: Sie müssen Zwillinge patchen, um die Werte von geänderten Eigenschaften zu aktualisieren, damit sie mit dem neuen Modell gültig sind.
• Löschen Sie Zwillinge und Beziehungen, von denen das Modell verwendet wird, und erstellen Sie sie neu. Sie können die folgenden Anweisungen dazu verwenden, Zwillinge zu löschen und Zwillinge erneut zu erstellen und Beziehungen zu löschen und Beziehungen erneut zu erstellen,
  • Die Durchführung dieses Vorgangs empfiehlt sich, wenn Sie viele Änderungen am Modell vornehmen und es schwierig sein wird, die vorhandenen Zwillinge so zu aktualisieren, dass sie mit ihm übereinstimmen. Die erneute Erstellung kann jedoch kompliziert sein, wenn Sie über viele Zwillinge verfügen, die durch viele Beziehungen miteinander verbunden sind.

Entfernen von Modellen

Sie haben zwei Möglichkeiten, um Modelle aus dem Dienst zu entfernen:

• Außerbetriebnahme: Sobald ein Modell außer Betrieb genommen wurde, können Sie es nicht mehr zum Erstellen neuer digitaler Zwillinge verwenden. Vorhandene digitale Zwillinge, die dieses Modell bereits verwenden, sind nicht betroffen. Deshalb können Sie sie weiterhin aktualisieren, indem Sie z. B. Eigenschaften ändern und Beziehungen hinzufügen oder löschen.
• Löschen: Durch diesen Vorgang wird das Modell vollständig aus der Lösung entfernt. Alle Zwillinge, die dieses Modell verwenden, sind keinem gültigen Modell mehr zugeordnet, weshalb sie so behandelt werden, als würden sie über gar kein Modell verfügen. Sie können diese Zwillinge zwar weiterhin lesen, aber Sie können erst wieder Updates an ihnen vornehmen, wenn sie einem anderen Modell zugewiesen werden.

Bei diesen Vorgängen handelt es sich um separate Features, die einander nicht beeinträchtigen. Sie können aber zusammen dazu verwendet werden, ein Modell schrittweise zu entfernen.

Hinweis

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

Außerbetriebsetzung

Sie können die DecommissionModel-Methode aus dem SDK verwenden, um ein Modell außer Betrieb zu setzen:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Sie können ein Modell auch außer Betrieb setzen, indem Sie den REST-API-Aufruf DigitalTwinModels Update verwenden. Die decommissioned-Eigenschaft ist die einzige Eigenschaft, die durch diesen API-Aufruf ersetzt werden kann. Das JSON-Patch-Dokument sieht in etwa wie folgt aus:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

Der Status „Außerbetriebsetzung“ eines Modells ist in den ModelData-Datensätzen enthalten, die von den APIs zum Abrufen von Modellen zurückgegeben werden.

Löschen

Sie können entweder alle Modelle auf einmal aus der Instanz löschen oder einzeln bestimmte Modelle zum Löschen auswählen.

Ein Beispiel für das gleichzeitige Löschen aller Modelle finden Sie im GitHub-Repository End-to-End-Beispiele für Azure Digital Twins. Die Datei CommandLoop.cs enthält eine CommandDeleteAllModels-Funktion mit Code zum Löschen aller Modelle in der Instanz.

Orientieren Sie sich zum Löschen eines einzelnen Modells an den Anweisungen und Überlegungen aus dem übrigen Teil dieses Abschnitts.

Vor dem Löschen: Löschanforderungen

Generell können Modelle jederzeit gelöscht werden.

Allerdings stellen Modelle, von denen andere Modelle abhängig sind (durch eine extends-Beziehung oder weil es sich um eine Komponente handelt), eine Ausnahme dar. Wenn beispielsweise ein ConferenceRoom-Modell ein Room-Modell erweitert und über ein ACUnit-Modell als Komponente verfügt, können Sie die Modelle Room und ACUnit erst löschen, wenn die jeweiligen Verweise für das Modell ConferenceRoom entfernt werden.

Hierzu können Sie das abhängige Modell aktualisieren, um die Abhängigkeiten zu entfernen, oder das abhängige Modell vollständig löschen.

Beim Löschen: Löschvorgang

Selbst wenn ein Modell die Anforderungen zum sofortigen Löschen erfüllt, sollten Sie zunächst einige Maßnahmen ergreifen, um unbeabsichtigte Folgen für die übrigen Zwillinge zu vermeiden. Im Folgenden wird erläutert, wie Sie den Prozess verwalten können:

1. Setzen Sie zunächst das Modell außer Betrieb.
2. Warten Sie einige Minuten, um sicherzustellen, dass der Dienst alle in letzter Minute gesendeten Erstellungsanforderungen verarbeitet hat, die vor der Außerbetriebnahme gesendet wurden.
3. Fragen Sie die Zwillinge des Modells ab, um alle Zwillinge zu finden, die das außer Betrieb genommene Modell verwenden.
4. Löschen Sie die Zwillinge, wenn Sie sie nicht mehr benötigen, oder patchen Sie sie bei Bedarf an ein neues Modell. Sie können die Zwillinge auch unbeachtet lassen. Dann werden sie zu Zwillingen ohne Modell, sobald das Modell gelöscht wird. Weitere Informationen zu den Auswirkungen dieses Zustands finden Sie im nächsten Abschnitt.
5. Warten Sie einige Minuten, um sicherzustellen, dass die Änderungen übernommen wurden.
6. Löschen Sie das Modell.

Um ein Modell zu löschen, können Sie den SDK-Aufruf DeleteModel verwenden:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Sie können ein Modell auch mit dem Rest-API-Aufruf DigitalTwinModels Delete löschen.

Nach dem Löschen: Zwillinge ohne Modelle

Nach dem Löschen eines Modells werden sämtliche digitale Zwillinge, die das Modell verwendet haben, als Zwillinge ohne Modell betrachtet. Es gibt zwar keine Abfrage, die Sie verwenden können, um eine Liste aller Zwillinge in diesem Zustand zu erhalten, aber Sie können die Zwillinge des jeweiligen gelöschten Modells abfragen, um herauszufinden, welche Zwillinge betroffen sind.

Im Folgenden finden Sie eine Übersicht darüber, wozu Zwillinge ohne Modell (nicht) verwendet werden können.

Möglich:

• Den Zwilling abfragen
• Lesen von Eigenschaften
• Ausgehende Beziehungen lesen
• Hinzufügen und Löschen eingehender Beziehungen (wie in, andere Zwillinge können weiterhin Beziehungen zu diesem Zwilling bilden)
  • Das target in der Beziehungsdefinition kann weiterhin den DTMI des gelöschten Modells widerspiegeln. Auch eine Beziehung ohne festgelegtes Ziel kann hier funktionieren.
• Beziehungen löschen
• Den Zwilling löschen

Nicht möglich:

• Ausgehende Beziehungen bearbeiten (z. B. Beziehungen dieses Zwillings zu anderen Zwillingen)
• Eigenschaften bearbeiten

Nach dem Löschen: Erneutes Hochladen eines Modells

Wenn Sie ein Modell löschen, können Sie später ein neues Modell mit derselben ID hochladen. Dann passiert Folgendes:

• Aus Sicht des Lösungsspeichers entspricht dieser Vorgang dem Hochladen eines komplett neuen Modells. Er erinnert sich nicht daran, dass das alte Modell hochgeladen wurde.
• Wenn der Graph übrig gebliebene Zwillinge enthält, die auf das gelöschte Modell verweisen, werden diese nicht mehr als verwaist angesehen. Die Modell-ID ist dann einschließlich einer neuen Definition wieder gültig. Wenn sich die neue Definition für das Modell jedoch von der gelöschten Modelldefinition unterscheidet, weisen diese Zwillinge möglicherweise Eigenschaften und Beziehungen auf, die der gelöschten Definition entsprechen und mit der neuen nicht gültig sind.

In Azure Digital Twins wird dieser Zustand nicht verhindert. Deshalb sollten Sie darauf achten, Zwillinge ordnungsgemäß zu patchen, damit sie durch den Wechsel der Modelldefinition nicht ihre Gültigkeit verlieren.

Konvertieren von v2-Modellen in v3

Azure Digital Twins unterstützt die DTDL-Versionen 2 und 3 (gekürzt in der Dokumentation auf v2 bzw. v3). V3 ist die empfohlene Wahl basierend auf den erweiterten Funktionen. In diesem Abschnitt wird erläutert, wie Sie ein vorhandenes DTDL v2-Modell auf DTDL v3 aktualisieren.

1. Aktualisieren Sie den Kontext. Das Standard-Feature, das ein Modell als v2 oder v3 identifiziert, ist das @context Feld auf der Schnittstelle. Um ein Modell von v2 in v3 zu konvertieren, ändern Sie den dtmi:dtdl:context;2 Kontextwert in dtmi:dtdl:context;3. Bei vielen Modellen ist dies die einzige erforderliche Änderung.
   1. Wert in v2: "@context": "dtmi:dtdl:context;2"
   2. Wert in v3: "@context": "dtmi:dtdl:context;3".
2. Aktualisieren Sie bei Bedarf semantische Typen. In DTDL v2 werden semantische Typen nativ unterstützt. In DTDL v3 sind sie in der QuantitativeTypes-Featureerweiterung enthalten. Wenn Ihr v2-Modell semantische Typen verwendet hat, müssen Sie die Featureerweiterung hinzufügen, wenn Sie das Modell in v3 konvertieren. Ändern Sie dazu zuerst das @context Feld auf der Schnittstelle von einem einzelnen Wert in ein Array von Werten, und fügen Sie dann den Wert dtmi:dtdl:extension:quantitativeTypes;1hinzu.
   1. Wert in v2: "@context": "dtmi:dtdl:context;2"
   2. Wert in v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. Berücksichtigen Sie bei Bedarf Größenbeschränkungen. V2 und v3 weisen unterschiedliche Größenbeschränkungen auf. Wenn Ihre Schnittstelle also sehr groß ist, sollten Sie die Grenzwerte für die Unterschiede zwischen DTDL v2 und v3 überprüfen.

Nach diesen Änderungen wurde ein früheres DTDL v2-Modell in ein DTDL v3-Modell konvertiert.

Möglicherweise sollten Sie auch neue Funktionen von DTDL v3 in Betracht ziehen, z. B. Arraytypeigenschaften, Versionsentspannung und zusätzliche Featureerweiterungen, um festzustellen, ob eine davon vorteilhafte Ergänzungen sein würde. Eine vollständige Liste der Unterschiede zwischen DTDL v2 und v3 finden Sie unter Änderungen von Version 2 in der DTDL v3-Sprachbeschreibung.

Nächste Schritte

Weitere Informationen zum Erstellen und Verwalten von digitalen Zwillingen basierend auf Ihren Modellen finden Sie unter

• Verwalten digitaler Zwillinge