Verwenden der Azure Digital Twins-Verwaltungs-APIs

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.

Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.

Die Azure Digital Twins-Verwaltungs-APIs bieten leistungsstarke Funktionen für Ihre IoT-Apps. In diesem Artikel wird die Navigation durch die API-Struktur erläutert.

API-Zusammenfassung

Die folgende Liste enthält die Komponenten der Digital Twins-APIs.

• /spaces: Diese APIs interagieren mit den physischen Speicherorten in Ihrem Setup. Sie helfen Ihnen, die digitalen Mappings Ihrer physischen Speicherorte in Form eines räumlichen Graphs zu erstellen, zu löschen und zu verwalten.

• /geräte: Diese APIs interagieren mit den Geräten in Ihrem Setup. Diese Geräte können einen oder mehrere Sensoren verwalten. Ein Gerät kann beispielsweise Ihr Telefon sein, ein Raspberry Pi-Sensorhalter oder ein Lora-Gateway usw.

• /sensoren: Diese APIs helfen Ihnen bei der Kommunikation mit den Sensoren, die Ihren Geräten und Ihren physischen Standorten zugeordnet sind. Die Sensoren erfassen und senden Umgebungswerte, mit denen Sie Ihre räumliche Umgebung manipulieren können.

• /resources: Diese APIs helfen Ihnen bei der Einrichtung von Ressourcen, z. B. einem IoT-Hub, für Ihre Digital Twins-Instanz.

• /types: Diese APIs ermöglichen es Ihnen, erweiterte Typen mit Ihren Digital Twins-Objekten zuzuordnen, um bestimmte Merkmale zu diesen Objekten hinzuzufügen. Diese Typen ermöglichen eine einfache Filterung und Gruppierung von Objekten in der Benutzeroberfläche und den benutzerdefinierten Funktionen, die Ihre Telemetriedaten verarbeiten. Beispiele für erweiterte Typen sind DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType, SpaceResourceType usw.

• /ontologies: Diese APIs helfen Ihnen, Ontologien zu verwalten, die Sammlungen erweiterter Typen sind. Ontologien stellen Namen für Objekttypen entsprechend dem physischen Raum, den sie repräsentieren, bereit. Die Ontologie BACnet bietet beispielsweise spezifische Namen für sensor types, datatypes, datasubtypes und dataunittypes. Ontologien werden vom Dienst verwaltet und erstellt. Benutzer können Ontologien laden und entladen. Wenn eine Ontologie geladen wird, sind alle zugehörigen Typnamen aktiviert und können in Ihrem räumlichen Graphen bereitgestellt werden.

• /propertyKeys: Sie können diese APIs verwenden, um benutzerdefinierte Eigenschaften für Ihre Räume, Geräte, Benutzer und Sensoren zu erstellen. Diese Eigenschaften werden als Schlüssel/Wert-Paare erstellt. Sie können den Datentyp für diese Eigenschaften durch Festlegen von PrimitiveDataType definieren. Sie können beispielsweise eine Eigenschaft namens BasicTemperatureDeltaProcessingRefreshTime vom Typ uint für Ihre Sensoren definieren und dann für jeden Ihrer Sensoren einen Wert für diese Eigenschaft vergeben. Sie können auch Einschränkungen für diese Werte während der Erstellung der Eigenschaft hinzufügen, wie z.B. Min- und Max-Bereiche, sowie zulässige Werte wie ValidationData.

• /matchers: Mit diesen APIs können Sie die Bedingungen angeben, die Sie aus Ihren eingehenden Gerätedaten auswerten möchten. Weitere Informationen finden Sie in diesem Artikel.

• /userDefinedFunctions: Diese APIs ermöglichen es Ihnen, eine benutzerdefinierte Funktion zu erstellen, zu löschen oder zu aktualisieren, die ausgeführt wird, wenn die von den Übereinstimmungern definierten Bedingungen ausgeführt werden, um Daten zu verarbeiten, die von Ihrem Setup stammen. Weitere Informationen zu diesen benutzerdefinierten Funktionen, auch benutzerdefinierte Funktionen genannt, finden Sie in diesem Artikel.

• /endpunkte: Mit diesen APIs können Sie Endpunkte erstellen, damit Ihre Digital Twins-Lösung mit anderen Azure-Diensten für Datenspeicher und Analysen kommunizieren kann. Weitere Informationen finden Sie in diesem Artikel.

• /keyStores: Mit diesen APIs können Sie Sicherheitsschlüsselspeicher für Ihre Räume verwalten. Diese Speicher können eine Sammlung von Sicherheitsschlüsseln enthalten und ermöglichen es Ihnen, die neuesten gültigen Schlüssel einfach abzurufen.

• /users: Mit diesen APIs können Sie Benutzern Ihre Leerzeichen zuordnen, um diese Personen nach Bedarf zu suchen.

• /system: Mit diesen APIs können Sie systemweite Einstellungen verwalten, z. B. die Standardtypen von Leerzeichen und Sensoren.

• /roleAssignments: Diese APIs ermöglichen es Ihnen, Rollen entitäten wie Benutzer-ID, benutzerdefinierte Funktions-ID usw. zuzuordnen. Jede Rollenzuweisung enthält die ID der Entität, die zugeordnet werden soll, den Entitätstyp, die ID der Rolle, die zugeordnet werden soll, die Mandanten-ID und einen Pfad, der die obere Grenze der Ressource definiert, auf die die Entität mit dieser Zuordnung zugreifen kann. Weitere Informationen finden Sie in diesem Artikel.

API-Navigation

Die Digital Twins-APIs unterstützen die Filterung und Navigation durch Ihren räumlichen Graph mit den folgenden Parametern:

• spaceId: Die API filtert die Ergebnisse nach der angegebenen Leer-ID. Zusätzlich ist das boolesche Flag useParentSpace auf die APIs /spaces anwendbar, was bedeutet, dass sich die angegebene Space-ID auf den übergeordneten Space anstelle des aktuellen Space bezieht.

• minLevel und maxLevel: Stammräume gelten als auf Ebene 1. Spaces mit einem übergeordneten Space auf Ebene n sind auf Ebene n+1. Wenn diese Werte festgelegt sind, können Sie die Ergebnisse auf bestimmten Ebenen filtern. Nach dem Festlegen sind dies Inklusivwerte. Geräte, Sensoren und andere Objekte werden als auf der gleichen Ebene wie ihr nächstgelegener Space betrachtet. Um alle Objekte auf einer bestimmten Ebene zu erhalten, setzen Sie sowohl minLevel als auch maxLevel auf den gleichen Wert.

• minRelative und maxRelative: Wenn diese Filter angegeben werden, ist die entsprechende Ebene relativ zur Ebene der angegebenen Leerzeichen-ID:

  • Die relative Ebene 0 ist gleich der gleichen Ebene wie die angegebene Space-ID.
  • Die relative Ebene 1 repräsentiert Spaces auf der gleichen Ebene wie der untergeordnete Space der angegebenen Space-ID. Die relative Ebene n repräsentiert Spaces, die um n Ebenen niedriger sind als der angegebene Space.
  • Die relative Ebene -1 repräsentiert Spaces auf der gleichen Ebene wie der übergeordnete Space des angegebenen Space.

• traverse: Ermöglicht es Ihnen, eine beliebige Richtung aus einer bestimmten Leer-ID zu durchlaufen, wie durch die folgenden Werte angegeben.

  • Keine: Dieser Standardwert filtert auf die angegebene Leerzeichen-ID.
  • Nach unten: Diese Filtert nach der angegebenen Leerzeichen-ID und seinen Nachfolgern.
  • Up: Diese Filtert nach der angegebenen Leer-ID und seinen Vorgängern.
  • Span: Dieser Filtert einen horizontalen Teil des räumlichen Diagramms auf derselben Ebene wie die angegebene Leer-ID. Dies muss entweder minRelative oder maxRelative sein, oder auf „True“ gesetzt werden.

Beispiele

Die folgende Liste zeigt einige Beispiele für die Navigation durch die /devices-APIs. Beachten Sie, dass sich der Platzhalter YOUR_MANAGEMENT_API_URL auf die URI der Digital Twins-APIs im Format https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/ bezieht, wobei YOUR_INSTANCE_NAME der Name Ihrer Azure Digital Twins-Instanz ist und YOUR_LOCATION die Region ist, in der Ihre Instanz gehostet wird.

• YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 gibt alle Geräte zurück, die an Stamm-Spaces angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 gibt alle Geräte zurück, die an Spaces der Ebenen 2, 3 oder 4 angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId gibt alle Geräte zurück, die direkt an mySpaceId angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down gibt alle Geräte zurück, die an mySpaceId oder einen seiner Nachfolger angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true gibt alle Geräte zurück, die an Nachfolger von mySpaceId angefügt sind, mit Ausnahme von mySpaceId.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true gibt alle Geräte zurück, die an unmittelbare untergeordnete IDs von mySpaceId angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true gibt alle Geräte zurück, die an einen der Vorgänger von mySpaceId angefügt sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 gibt alle Geräte zurück, die an Nachfolger von mySpaceId angefügt sind, die auf einer Ebene kleiner oder gleich 5 sind.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true gibt alle Geräte zurück, die an Spaces angefügt sind, die sich auf der gleichen Ebene wie mySpaceId befinden.

OData-Unterstützung

Die meisten APIs, die Sammlungen zurückgeben, wie z.B. ein GET-Aufruf auf /spaces, unterstützen die folgende Teilmenge der generischen OData-Systemabfrageoptionen:

• $filter
• $orderby
• $top
• $skip – Wenn Sie beabsichtigen, die gesamte Sammlung anzuzeigen, sollten Sie sie als Gesamtmenge in einem einzigen Aufruf anfordern und dann in Ihrer Anwendung ein Paging durchführen.

Hinweis

Einige OData-Optionen (beispielsweise die Abfrageoptionen $count, $expand und $search) werden aktuell nicht unterstützt.

Beispiele

Die folgende Liste enthält mehrere Abfragen mit gültiger OData-Syntax:

• YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
• YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
• YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
• YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
• YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
• YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

Nächste Schritte

Einige häufige API-Abfragemuster finden Sie in Abfragen von Azure Digital Twins-APIs für gängige Aufgaben.

Weitere Informationen zu API-Endpunkten finden Sie unter Verwenden von Digital Twins Swagger.

Informationen zur OData-Syntax sowie zu verfügbaren Vergleichsoperatoren finden Sie unter OData-Vergleichsoperatoren in Azure Cognitive Search.