Verwenden der REST-API zum Erstellen und Verwalten von IoT Central-Anwendungen
Sie können die REST-API für die Steuerungsebene zum Erstellen und Verwalten von IoT Central-Anwendungen verwenden. Sie können auch die REST-API verwenden, um:
- Ihrer Anwendung eine verwaltete Identität hinzuzufügen.
- Dashboards in Ihrer Anwendung zu verwalten
Um diese API verwenden zu können, benötigen Sie ein Bearertoken für die Ressource management.azure.com. Dieses Bearertoken können Sie über die Azure CLI abrufen:
az account get-access-token --resource https://management.azure.com
Informationen zum Verwalten der IoT Central-Anwendung mithilfe der IoT Central-Benutzeroberfläche finden Sie unter Erstellen einer IoT Central-Anwendung.
Auflisten Ihrer Anwendungen
So rufen Sie eine Liste der IoT Central-Anwendungen in einem Abonnement ab:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
So rufen Sie eine Liste der IoT Central-Anwendungen in einer Ressourcengruppe ab:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Die Details für eine einzelne Anwendung können Sie folgendermaßen abrufen:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Erstellen einer IoT Central-Anwendung
So erstellen Sie eine IoT Central-Anwendung mit einer systemseitig zugewiesenen verwalteten Identität:
PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Die folgenden Nutzdaten zeigen die Konfiguration für die neue Anwendung, einschließlich der verwalteten Identität:
{
"location": "eastus",
"sku": {
"name": "ST2"
},
"properties": {
"displayName": "Contoso IoT Central App",
"subdomain": "my-iot-central-app",
"template": "iotc-pnp-preview@1.0.0"
},
"identity": {
"type": "SystemAssigned"
}
}
Ändern einer IoT Central-Anwendung
Sie können bereits vorhandene IoT Central-Anwendungen ändern. Im folgenden Beispiel wird gezeigt, wie Sie den Anzeigenamen ändern und die systemseitig zugewiesene verwaltete Identität aktivieren:
PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Verwenden Sie die folgenden Nutzdaten, um den Anzeigenamen zu ändern und die systemseitig zugewiesene verwaltete Identität zu aktivieren:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Hinweis
Verwaltete Identitäten können nur IoT Central-Anwendungen hinzugefügt werden, die in einer Region erstellt wurden. Alle neuen Anwendungen werden in einer Region erstellt.
Löschen einer IoT Central-Anwendung
Verwenden Sie den folgenden Befehl, um eine IoT Central-Anwendung zu löschen:
DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Dashboards
Sie können Dashboards erstellen, die einer bestimmten Organisation zugeordnet werden. Ein Organisationsdashboard ist nur für Benutzer sichtbar, die auf die Organisation zugreifen können, der das Dashboard zugeordnet wurde. Nur Benutzer in einer Rolle mit Organisationsdashboardberechtigungen können Organisationsdashboards erstellen, bearbeiten und löschen.
Alle Benutzer können persönliche Dashboards erstellen, die nur ihnen angezeigt werden. Benutzer können zwischen Organisationsdashboards und persönlichen Dashboards wechseln.
Hinweis
Das Erstellen persönlicher Dashboards mithilfe der API wird derzeit nicht unterstützt.
Informationen zum Verwalten von Dashboards mithilfe der IoT Central-Benutzeroberfläche finden Sie unter Verwalten von Dashboards.
REST-API für Dashboards
Mit der IoT Central-REST-API können Sie folgende Aktionen ausführen:
- Hinzufügen eines Dashboards zu Ihrer Anwendung
- Aktualisieren eines Dashboards in Ihrer Anwendung
- Abrufen einer Liste des Dashboards in der Anwendung
- Abrufen eines Dashboards nach ID
- Löschen eines Dashboards in Ihrer Anwendung
Ein Dashboard hinzufügen
Mit der folgenden Anforderung können Sie ein Dashboard erstellen:
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId: Ein eindeutiger DTMI-Bezeichner für das Dashboard
Der Anforderungstext enthält einige erforderliche Felder:
@displayName: Anzeigename des Dashboards@favorite: Ist das Dashboard in der Favoritenliste?group: Gerätegruppen-IDTile: Konfiguration, die das Kachelobjekt angibt, einschließlich Layout, Anzeigename und Konfiguration.
Die Kachel umfasst einige Pflichtfelder:
| Name | Beschreibung |
|---|---|
displayName |
Anzeigename der Kachel |
height |
Höhe der Kachel |
width |
Breite der Kachel |
x |
Horizontale Position der Kachel |
y |
Vertikale Position der Kachel |
Für die Dimensionen und die Position einer Kachel werden ganzzahlige Einheiten verwendet. Die kleinstmögliche Kachel hat eine Höhe und Breite von 1.
Sie können ein Kachelobjekt so konfigurieren, dass mehrere Datentypen angezeigt werden. Dieser Artikel enthält Beispiele für Kacheln, die Liniendiagramme, Markdown und den letzten bekannten Wert anzeigen. Weitere Informationen zu den verschiedenen Kacheltypen, die Sie einem Dashboard hinzufügen können, finden Sie unter Kacheltypen.
Kachel „Liniendiagramm“
Zeigt mindestens einen aggregierten Telemetriewert für mindestens ein Gerät über einen bestimmten Zeitraum hinweg an. Sie können beispielsweise ein Liniendiagramm anzeigen, das die durchschnittliche Temperatur und den durchschnittlichen Druck eines oder mehrere Geräte in der letzten Stunde anzeigt.
Die Kachel des Liniendiagramms weist die folgende Konfiguration auf:
| Name | Beschreibung |
|---|---|
capabilities |
Gibt den Aggregatwert der anzuzeigenden Telemetriedaten an. |
devices |
Die Liste der anzuzeigenden Geräte. |
format |
Die Formatkonfiguration des Diagramms, z. B. die zu verwendenden Achsen. |
group |
Die ID der anzuzeigenden Gerätegruppe. |
queryRange |
Der anzuzeigende Zeitbereich und die anzuzeigende Auflösung. |
type |
lineChart |
Markdown-Kachel
Kacheln, auf die geklickt werden kann und in denen Überschriften und Beschreibungstext in Markdown angezeigt werden. Die URL kann ein relativer Link zu einer anderen Seite der Anwendung sein, oder ein absoluter Link zu einer externen Website. Die Markdown-Kachel weist die folgende Konfiguration auf:
| Name | Beschreibung |
|---|---|
description |
Die Markdownzeichenfolge, die innerhalb der Kachel gerendert werden soll. |
href |
Der Link, der beim Auswählen der Kachel aufgerufen werden soll. |
image |
Ein base64-codiertes Bild, das angezeigt werden soll. |
type |
markdown |
Kachel mit letztem bekannten Wert
Zeigt den aktuellen Telemetriewerte für mindestens ein Gerät an. Auf dieser Kachel können Sie beispielsweise die aktuellen Messungen von Temperatur, Druck und Feuchtigkeit für ein oder mehrere Gerät anzeigen.
Die Kachel „Letzter bekannter Wert“ (Last Known Value, LKV) weist die folgende Konfiguration auf:
| Name | Beschreibung |
|---|---|
capabilities |
Gibt die anzuzeigenden Telemetriedaten an. |
devices |
Die Liste der anzuzeigenden Geräte. |
format |
Die Formatkonfiguration der LKV-Kachel, z. B. die Textgröße des Zeilenumbruchs. |
group |
Die ID der anzuzeigenden Gerätegruppe. |
showTrend |
Zeigen Sie die Differenz zwischen dem letzten bekannten Wert und dem vorherigen Wert an. |
type |
lkv |
Das folgende Beispiel zeigt einen Anforderungstext, der ein neues Dashboard mit den Kacheln „Liniendiagramm“, „Markdown“ und „Letzter bekannter Wert“ hinzufügt. Die LKV- und Liniendiagrammkacheln sind 2x2-Kacheln. Die Markdown-Kachel ist eine 1x1-Kachel. Die Kacheln sind in der oberen Zeile des Dashboards angeordnet:
{
"displayName": "My Dashboard ",
"tiles": [
{
"displayName": "LKV Temperature",
"configuration": {
"type": "lkv",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"format": {
"abbreviateValue": false,
"wordWrap": false,
"textSize": 14
}
},
"x": 0,
"y": 0,
"width": 2,
"height": 2
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Average temperature",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 3,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Abrufen eines Dashboards
Verwenden Sie die folgende Anforderung, um die Details eines Dashboards mithilfe einer Dashboard-ID abzurufen.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Aktualisieren eines Dashboards
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Das folgende Beispiel zeigt einen Anforderungstext, der den Anzeigenamen eines Dashboards aktualisiert und das Dashboard der Liste der Favoriten hinzufügt:
{
"displayName": "New Dashboard Name",
"favorite": true
}
Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "New Dashboard Name",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 5,
"height": 5
}
],
"favorite": true
}
Löschen eines Dashboards
Verwenden Sie die folgende Anforderung, um ein Dashboard mithilfe der Dashboard-ID zu löschen:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Auflisten von Dashboards
Verwenden Sie die folgende Anforderung zum Abrufen einer Liste von Dashboards aus Ihrer Anwendung:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:
{
"value": [
{
"id": "dtmi:kkfvwa2xi:p7pyt5x3o",
"displayName": "Dashboard",
"personal": false,
"tiles": [
{
"displayName": "Device templates",
"configuration": {
"type": "markdown",
"description": "Get started by adding your first device.",
"href": "/device-templates/new/devicetemplates",
"image": "f5ba1b00-1d24-4781-869b-6f954df48736"
},
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Quick start demo",
"configuration": {
"type": "markdown",
"description": "Learn how to use Azure IoT Central in minutes.",
"href": "https://aka.ms/iotcentral-pnp-video",
"image": "9eb01d71-491a-44e5-8fac-7af3bc9f9acd"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Tutorials",
"configuration": {
"type": "markdown",
"description": "Step-by-step articles teach you how to create apps and devices.",
"href": "https://aka.ms/iotcentral-pnp-tutorials",
"image": "7d9fc12c-d46e-41c6-885f-0a67c619366e"
},
"x": 3,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 4,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "IoT Central Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": ""
},
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Contoso Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": "c9ac5af4-f38e-4cd3-886a-e0cb107f391c"
},
"x": 0,
"y": 1,
"width": 5,
"height": 3
},
{
"displayName": "Available Memory",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
]
}