Azure Digital Twins-APIs und -SDKs
Dieser Artikel bietet eine Übersicht über die verfügbaren Azure Digital Twins APIs und die Methoden zur Interaktion mit ihnen. Sie können die REST-APIs entweder direkt mit den zugehörigen Swagger-Dateien (über ein Tool wie Postman) oder über ein SDK verwenden.
Azure Digital Twins ist sowohl mit Steuerungsebenen-APIs als auch mit Datenebenen-APIs und SDKs zur Verwaltung Ihrer Instanz und ihrer Elemente ausgestattet.
- Die Steuerungsebenen-APIs sind Azure Resource Manager (ARM)-APIs, die Vorgänge zur Ressourcenverwaltung wie das Erstellen und Löschen von Instanzen abdecken.
- Bei den Datenebenen-APIs handelt es sich um Azure Digital Twins-APIs, die für Vorgänge zur Datenverwaltung wie die Verwaltung von Modellen, Zwillingen und des Graphen verwendet werden.
- Die SDKs nutzen die bestehenden APIs, um die Entwicklung von benutzerdefinierten Anwendungen unter Verwendung von Azure Digital Twins zu erleichtern.
APIs auf Steuerungsebene
Bei den Steuerungsebenen-APIs handelt es sich um ARM-APIs, die verwendet werden, um Ihre Azure Digital Twins-Instanz als Ganzes zu verwalten, sodass sie Vorgänge wie das Erstellen oder Löschen Ihrer gesamten Instanz abdecken. Sie werden diese APIs auch zum Erstellen und Löschen von Endpunkten verwenden.
Um die APIs direkt aufzurufen, verweisen Sie auf den neuesten Swagger-Ordner im Swagger-Repository der Steuerungsebene. Dieser Ordner enthält auch einen Ordner mit Beispielen, die die Verwendung veranschaulichen.
Hier sind die sdKs, die derzeit für die Azure Digital Twins-Steuerebenen-APIs verfügbar sind.
Sie können auch die Steuerebenen-APIs ausüben, indem Sie mit Azure Digital Twins über die Azure-Portal und CLI interagieren.
APIs auf Datenebene:
Bei den Datenebenen-APIs handelt es sich um die Azure Digital Twins-APIs, die verwendet werden, um die Elemente innerhalb Ihrer Azure Digital Twins-Instanz zu verwalten. Dazu gehören Vorgänge wie das Erstellen von Routen, das Hochladen von Modellen, das Erstellen von Beziehungen und das Verwalten von Zwillingen. Sie können ganz allgemein in die folgenden Kategorien unterteilt werden:
DigitalTwinModels: Die Kategorie „DigitalTwinModels“ enthält APIs zum Verwalten der Modelle in einer Azure Digital Twins-Instanz. Zu den Verwaltungsaktivitäten gehören das Hochladen, Überprüfen, Abrufen und Löschen von Modellen, die in DTDL erstellt wurden.DigitalTwins: Die Kategorie „DigitalTwins“ enthält die APIs, mit denen Entwickler digitale Zwillinge und ihre Beziehungen in einer Azure Digital Twins-Instanz erstellen, ändern und löschen können.Query: Die Kategorie „Query“ ermöglicht es Entwicklern, Gruppen von digitalen Zwillingen im Zwillingsgraphen beziehungsübergreifend zu finden.Event Routes: Die Kategorie „Event Routes“ enthält APIs zur Weiterleitung von Daten, durch das System und zu Downstreamdiensten.Import Jobs– Mit der API für Importaufträge können Sie eine lange ausgeführte, asynchrone Aktion zum Importieren von Modellen, Zwillingen und Beziehungen in Massen verwalten.Delete Jobs– Mit der Löschaufträge-API können Sie eine lange ausgeführte, asynchrone Aktion verwalten, um alle Modelle, Zwillinge und Beziehungen in einer Instanz zu löschen.
Um die APIs direkt aufzurufen, verweisen Sie auf den neuesten Swagger-Ordner im Swagger-Repository der Datenebene. Dieser Ordner enthält auch einen Ordner mit Beispielen, die die Verwendung veranschaulichen. Sie können auch die Referenzdokumentation zur Datenebenen-API anzeigen.
Hier sind die sdKs, die derzeit für die Azure Digital Twins-Datenebenen-APIs verfügbar sind.
Sie können die Datenebenen-APIs auch üben, indem Sie mit Azure Digital Twins über die CLI interagieren.
Verwendungs- und Authentifizierungsnotizen
Dieser Abschnitt enthält ausführlichere Informationen zur Verwendung der APIs und SDKs.
API-Hinweise
Hier finden Sie einige allgemeine Informationen zum direkten Aufrufen der Azure Digital Twins-APIs.
- Sie können ein HTTP REST-Testtool wie Postman verwenden, um direkte Aufrufe an die APIs von Azure Digital Twins durchzuführen. Weitere Informationen zu diesem Prozess finden Sie unter Aufrufen von Azure Digital Twins-APIs mit Postman.
- CORS (Cross-Origin Resource Sharing) wird in Azure Digital Twins derzeit nicht unterstützt. Weitere Informationen zu den Auswirkungen und zu Lösungsstrategien finden Sie unter Cross-Origin Resource Sharing (CORS) für Azure Digital Twins.
Hier finden Sie weitere Informationen zur Authentifizierung für API-Anforderungen.
- Eine Möglichkeit zum Generieren eines Bearertokens für Azure Digital Twins-API-Anforderungen ist der Befehl az account get-access-token CLI. Ausführliche Anweisungen finden Sie unter "Bearertoken abrufen".
- Anforderungen an die Azure Digital Twins-APIs erfordern einen Benutzer oder Dienstprinzipal, der Teil desselben Microsoft Entra ID-Mandanten ist, in dem die Azure Digital Twins-Instanz vorhanden ist. Um böswillige Überprüfungen von Azure Digital Twins-Endpunkten zu verhindern, wird für Anforderungen mit Zugriffstoken von außerhalb des ursprünglichen Mandanten die Fehlermeldung „404 Sub-Domain nicht gefunden“ zurückgegeben. Dieser Fehler wird zurückgegeben, auch wenn dem Benutzer oder Dienstprinzipal eine Azure Digital Twins Data Owner- oder Azure Digital Twins Data Reader-Rolle über die Microsoft Entra B2B-Zusammenarbeit erteilt wurde. Informationen zum Konfigurieren des mandantenübergreifenden Zugriffs finden Sie unter Schreiben von App-Authentifizierungscode.
SDK-Hinweise
Das zugrunde liegende SDK für Azure Digital Twins ist Azure.Core. In der Dokumentation zu Azure-Namespaces finden Sie Verweise auf die SDK-Infrastruktur und -Typen.
Hier finden Sie einige weitere Informationen zur Authentifizierung mit den SDKs.
- Instanziieren Sie zunächst die
DigitalTwinsClientKlasse. Der Konstruktor erfordert Anmeldeinformationen, die mit verschiedenen Authentifizierungsmethoden im PaketAzure.Identityabgerufen werden können. Weitere Informationen zuAzure.Identityfinden Sie in der Dokumentation zu Namespaces. - Möglicherweise finden Sie
InteractiveBrowserCredentialzu Beginn nützlich, aber es gibt noch verschiedene andere Optionen, einschließlich Anmeldeinformationen für die verwaltete Identität, die Sie wahrscheinlich zur Authentifizierung von mit MSI eingerichteten Azure-Funktionen für Azure Digital Twins verwenden werden. Weitere Informationen überInteractiveBrowserCredentialfinden Sie in dessen Klassendokumentation.
Hier sind einige weitere Informationen zu Funktionen und zurückgegebenen Daten.
- Alle Aufrufe von Dienst-APIs werden als Memberfunktionen für die
DigitalTwinsClient-Klasse verfügbar gemacht. - Alle Dienstfunktionen sind in synchroner und asynchroner Version vorhanden.
- Alle Dienstfunktionen lösen eine Ausnahme für einen beliebigen Rückgabestatus von 400 oder höher aus. Stellen Sie sicher, dass Sie Aufrufe in einem
try-Abschnitt umschließen und mindestensRequestFailedExceptionserfassen. Weitere Informationen zu dieser Art von Ausnahme finden Sie in der zugehörigen Referenzdokumentation. - Die meisten Dienstmethoden geben
Response<T>(oderTask<Response<T>>für die asynchronen Aufrufe) zurück, wobeiTdie Klasse des Rückgabeobjekts für den Dienstaufruf darstellt. Die Klasse Antwort (response) kapselt die Dienstrückgabe und präsentiert Rückgabewerte in ihremValue-Feld. - Dienstmethoden mit ausgelagerten Ergebnissen geben
Pageable<T>oderAsyncPageable<T>als Ergebnis zurück. Weitere Informationen zurPageable<T>-Klasse finden Sie in der zugehörigen Referenzdokumentation. Weitere Informationen zuAsyncPageable<T>finden Sie in der zugehörigen Referenzdokumentation. - Mithilfe einer
await foreach-Schleife können Sie ausgelagerte Ergebnisse durchlaufen. Weitere Informationen zu diesem Prozess finden Sie unter Durchlaufen von asynchronen Enumerationen in C# 8. - Dienstmethoden geben, wo immer möglich, stark typisierte Objekte zurück. Da Azure Digital Twins jedoch auf Modellen basiert, die vom Benutzer zur Laufzeit individuell konfiguriert werden (über DTDL-Modelle, die in den Dienst hochgeladen werden), verwenden viele Dienst-APIs das JSON-Format, um Zwillingsdaten zu übernehmen und zurückzugeben.
Serialisierungshilfsprogramme im .NET SDK (C#)
Serialisierungshilfsprogramme sind im .NET SDK (C#) verfügbare Hilfsfunktionen zum schnellen Erstellen oder Deserialisieren von Zwillingsdaten für den Zugriff auf grundlegende Informationen. Da die Kernmethoden des SDK Zwillingsdaten standardmäßig als JSON zurückgeben, kann es hilfreich sein, die Zwillingsdaten mithilfe dieser Hilfsklassen weiter zu unterteilen.
Die folgenden Hilfsklassen sind verfügbar:
BasicDigitalTwin: Stellt generisch die Kerndaten eines digitalen Zwillings dar.BasicDigitalTwinComponent: Stellt generisch eine Komponente in den Eigenschaften vom TypContentseines grundlegenden digitalen Zwillings (BasicDigitalTwin) dar.BasicRelationship: Stellt generisch die Kerndaten einer Beziehung dar.DigitalTwinsJsonPropertyName: Enthält die Zeichenfolgenkonstanten für die Verwendung bei der JSON-Serialisierung und -Deserialisierung für benutzerdefinierte Arten von digitalen Zwillingen.
Massenimport mit der Importaufträge-API
Die Importaufträge-API ist eine Datenebenen-API , mit der Sie eine Reihe von Modellen, Zwillingen und/oder Beziehungen in einem einzelnen API-Aufruf importieren können. Importaufträge-API-Vorgänge sind auch in den CLI-Befehlen und Datenebenen-SDKs enthalten. Für die Verwendung der API für Importaufträge ist die Verwendung von Azure Blob Storage erforderlich.
Berechtigungen überprüfen
Um die Importaufträge-API zu verwenden, müssen Sie die in diesem Abschnitt beschriebenen Berechtigungseinstellungen aktivieren.
Zunächst benötigen Sie eine vom System zugewiesene verwaltete Identität für Ihre Azure Digital Twins-Instanz. Anweisungen zum Einrichten einer vom System verwalteten Identität für die Instanz finden Sie unter Aktivieren/Deaktivieren der verwalteten Identität für die Instanz.
Sie müssen über Schreibberechtigungen in Ihrer Azure Digital Twins-Instanz für die folgenden Datenaktionskategorien verfügen:
Microsoft.DigitalTwins/jobs/*- Alle Diagrammelemente, die Sie in den Auftragsaufruf aufnehmen möchten. Dies kann u. U. sein
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*und/oderMicrosoft.DigitalTwins/digitaltwins/relationships/*.
Die integrierte Rolle, die all diese Berechtigungen bereitstellt, ist Azure Digital Twins Data Owner. Sie können auch eine benutzerdefinierte Rolle verwenden, um nur den benötigten Datentypen präzisen Zugriff zu gewähren. Weitere Informationen zu Rollen in Azure Digital Twins finden Sie unter Security for Azure Digital Twins solutions.
Hinweis
Wenn Sie versuchen, einen IMPORT Jobs API-Aufruf aufzurufen und Keine Schreibberechtigungen für einen der Diagrammelementtypen fehlen, die Sie importieren möchten, überspringt der Auftrag diesen Typ und importiert die anderen. Wenn Sie z. B. Schreibzugriff auf Modelle und Zwillinge haben, aber keine Beziehungen, ist der Versuch, alle drei Elementtypen zu importieren, nur erfolgreich beim Importieren der Modelle und Zwillinge. Der Auftragsstatus spiegelt einen Fehler wider, und die Meldung gibt an, welche Berechtigungen fehlen.
Außerdem müssen Sie der vom System zugewiesenen verwalteten Identität Ihrer Azure Digital Twins-Instanz die folgenden RBAC-Berechtigungen erteilen, damit sie im Azure Blob Storage-Container auf Eingabe- und Ausgabedateien zugreifen kann:
- Storage Blob Data Reader für den Azure Storage-Eingabe-BLOB-Container
- Mitwirkender von Speicher-BLOB-Daten für den Azure Storage-Ausgabe-BLOB-Container
Generieren Sie schließlich ein Bearertoken, das in Ihren Anforderungen an die Auftrags-API verwendet werden kann. Anweisungen finden Sie unter "Bearertoken abrufen".
Formatieren von Daten
Die API akzeptiert Graph-Informationseingaben aus einer NDJSON-Datei , die in einen Azure Blob Storage-Container hochgeladen werden muss. Die Datei beginnt mit einem Header Abschnitt, gefolgt von den optionalen Abschnitten Models, Twinsund Relationships. Sie müssen nicht alle drei Arten von Diagrammdaten in die Datei einschließen, aber alle vorhandenen Abschnitte müssen dieser Reihenfolge entsprechen. Zwillinge und Beziehungen, die mit dieser API erstellt wurden, können optional die Initialisierung ihrer Eigenschaften umfassen.
Hier ist eine Beispieleingabedatendatei für die Import-API:
{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}
Tipp
Ein Beispielprojekt, das Modelle, Zwillinge und Beziehungen in den von der Import-API unterstützten NDJSON konvertiert, finden Sie unter Azure Digital Twins Bulk Import NDJSON Generator. Das Beispielprojekt ist für .NET geschrieben und kann heruntergeladen oder angepasst werden, um Ihnen beim Erstellen eigener Importdateien zu helfen.
Nachdem die Datei erstellt wurde, laden Sie sie mithilfe Ihrer bevorzugten Uploadmethode in ein Block-Blob in Azure Blob Storage hoch (einige Optionen sind der AzCopy-Befehl, die Azure CLI oder die Azure-Portal). Sie verwenden die BLOB-Speicher-URL der NDJSON-Datei im Textkörper des API-Aufrufs für Importaufträge.
Ausführen des Importauftrags
Jetzt können Sie mit dem Aufrufen der Importaufträge-API fortfahren. Ausführliche Anweisungen zum Importieren eines vollständigen Diagramms in einem API-Aufruf finden Sie unter Hochladen von Modellen, Zwillingen und Beziehungen in Massen mit der Importaufträge-API. Sie können auch die Importaufträge-API verwenden, um jeden Ressourcentyp unabhängig voneinander zu importieren. Weitere Informationen zur Verwendung der Importaufträge-API mit einzelnen Ressourcentypen finden Sie in den Anweisungen zur Importaufträge-API für Modelle, Zwillinge und Beziehungen.
Im Textkörper des API-Aufrufs geben Sie die BLOB-Speicher-URL der NDJSON-Eingabedatei an. Außerdem stellen Sie eine neue BLOB-Speicher-URL bereit, um anzugeben, wo das Ausgabeprotokoll gespeichert werden soll, nachdem der Dienst es erstellt hat.
Wichtig
Stellen Sie sicher, dass die vom System zugewiesene verwaltete Identität Ihrer Azure Digital Twins-Instanz über die Im Abschnitt "Berechtigungen überprüfen" beschriebenen Speicher-BLOB-RBAC-Berechtigungen verfügt.
Während der Ausführung des Importauftrags wird ein strukturiertes Ausgabeprotokoll vom Dienst generiert und als neues Anfüge-Blob in Ihrem BLOB-Container gespeichert, an dem URL-Speicherort, den Sie für den Ausgabe-BLOB in der Anforderung angegeben haben. Hier ist ein Beispielausgabeprotokoll für einen erfolgreichen Auftragsimport von Modellen, Zwillingen und Beziehungen:
{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}
Wenn der Auftrag abgeschlossen ist, können Sie die Gesamtanzahl der aufgenommenen Entitäten mithilfe der Metrik "BulkOperationEntityCount" anzeigen.
Es ist auch möglich, einen ausgeführten Importauftrag mit dem Vorgang "Abbrechen" aus der Importaufträge-API abzubrechen. Nachdem der Auftrag abgebrochen wurde und nicht mehr ausgeführt wird, können Sie ihn löschen.
Grenzwerte und Überlegungen
Beachten Sie beim Arbeiten mit der Importaufträge-API die folgenden Überlegungen:
- Importaufträge sind keine Atomoperationen. Es gibt kein Rollback im Falle eines Fehlers, eines teilweisen Auftragsabschlusses oder der Verwendung des Cancel-Vorgangs.
- Innerhalb einer Azure Digital Twins-Instanz wird jeweils nur ein Massenauftrag unterstützt. Sie können diese Informationen und andere numerische Grenzwerte der Auftrags-APIs in Azure Digital Twins-Grenzwerte anzeigen.
Massenlöschung mit der API zum Löschen von Aufträgen
Die Delete Jobs-API ist eine Datenebenen-API , mit der Sie alle Modelle, Zwillinge und Beziehungen in einer Instanz mit einem einzelnen API-Aufruf löschen können. Löschaufträge-API-Vorgänge sind auch als CLI-Befehle verfügbar. Besuchen Sie die API-Dokumentation, um die Anforderungsdetails zum Erstellen eines Löschauftrags und zum Überprüfen des Status anzuzeigen.
Um sicherzustellen, dass alle Elemente gelöscht werden, befolgen Sie diese Empfehlungen, während Sie die Löschaufträge-API verwenden:
- Anweisungen zum Generieren eines Bearertokens zum Authentifizieren von API-Anforderungen finden Sie unter "Bearertoken abrufen".
- Wenn Sie kürzlich eine große Anzahl von Entitäten in Ihr Diagramm importiert haben, warten Sie einige Zeit, und stellen Sie sicher, dass alle Elemente in Ihrem Diagramm synchronisiert werden, bevor Sie den Löschauftrag beginnen.
- Beenden Sie alle Vorgänge für die Instanz, insbesondere Uploadvorgänge, bis der Löschauftrag abgeschlossen ist.
Abhängig von der Größe des gelöschten Diagramms kann ein Löschauftrag von ein paar Minuten bis zu mehreren Stunden dauern.
Der Standardtimeoutzeitraum für einen Löschauftrag beträgt 12 Stunden, die mithilfe eines Abfrageparameters in der API auf einen beliebigen Wert zwischen 15 Minuten und 24 Stunden angepasst werden können. Dies ist die Zeitspanne, in der der Löschauftrag ausgeführt wird, bevor es zu einem Timeout führt. An diesem Punkt versucht der Dienst, den Auftrag zu beenden, wenn er noch nicht abgeschlossen wurde.
Grenzwerte und andere Überlegungen
Beachten Sie beim Arbeiten mit der Löschaufträge-API die folgenden Überlegungen:
- Löschaufträge sind keine Atomoperationen. Es gibt keinen Rollback im Falle eines Fehlers, eines teilweisen Auftragsabschlusses oder eines Timeouts des Auftrags.
- Innerhalb einer Azure Digital Twins-Instanz wird jeweils nur ein Massenauftrag unterstützt. Sie können diese Informationen und andere numerische Grenzwerte der Auftrags-APIs in Azure Digital Twins-Grenzwerte anzeigen.
Überwachen von API-Metriken
API-Metriken wie Anforderungen, Wartezeit und Ausfallrate können im Azure-Portal angezeigt werden.
Informationen zum Anzeigen und Verwalten von Azure Digital Twins-Metriken finden Sie unter Überwachen Ihrer Instanz. Eine vollständige Liste der für Azure Digital Twins verfügbaren API-Metriken finden Sie unter Azure Digital Twins-API-Anforderungsmetriken.
Nächste Schritte
Lesen Sie, wie Sie mithilfe von Postman direkte Anforderungen an die Azure Digital Twins-APIs senden:
Verwenden Sie alternativ das .NET SDK, indem Sie eine Client-App mithilfe dieses Tutorials erstellen: