Verwenden der REST-API zum Erstellen und Verwalten von IoT Central-Anwendungen

Artikel
06/26/2024

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-ID
Tile: Konfiguration, die ein 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
}

Hinzufügen einer Speicherkontokonfiguration für Dateiuploads

Verwenden Sie die folgende Anforderung, um eine Blobspeicherkontokonfiguration für Dateiuploads in Ihrer IoT Central-Anwendung zu erstellen:

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Der Anforderungstext enthält folgende Felder:

account: Der Name des Speicherkontos, in das die Datei hochgeladen werden soll.
connectionString: Die Verbindungszeichenfolge für die Verbindung mit dem Speicherkonto.
container: Der Name des Containers im Speicherkonto. Das folgende Beispiel verwendet den Namen fileuploads.
etag: ETag zum Verhindern von Konflikten mit mehreren Uploads
sasTtl: Der Zeitraum, für den die Anforderung eines Geräts zum Hochladen einer Datei gültig ist, angegeben gemäß ISO 8601-Standard.

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Abrufen einer Speicherkontokonfiguration für Dateiuploads

Verwenden Sie die folgende Anforderung, um die Details einer Blobspeicherkontokonfiguration für Dateiuploads in Ihrer IoT Central-Anwendung abzurufen:

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Aktualisieren einer Speicherkontokonfiguration für Dateiuploads

Verwenden Sie die folgende Anforderung, um die Verbindungszeichenfolge eines Blobspeicherkontos für Dateiuploads in Ihrer IoT Central-Anwendung zu aktualisieren:

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

Entfernen einer Speicherkontokonfiguration für Dateiuploads

Verwenden Sie die folgende Anforderung, um eine Speicherkontokonfiguration zu löschen:

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

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
        }
    ]
}

Freigeben über

Verwenden der REST-API zum Erstellen und Verwalten von IoT Central-Anwendungen

Auflisten Ihrer Anwendungen

Erstellen einer IoT Central-Anwendung

Ändern einer IoT Central-Anwendung

Löschen einer IoT Central-Anwendung

Dashboards

REST-API für Dashboards

Ein Dashboard hinzufügen

Kachel „Liniendiagramm“

Markdown-Kachel

Kachel mit letztem bekannten Wert

Hinzufügen einer Speicherkontokonfiguration für Dateiuploads

Abrufen einer Speicherkontokonfiguration für Dateiuploads

Aktualisieren einer Speicherkontokonfiguration für Dateiuploads

Entfernen einer Speicherkontokonfiguration für Dateiuploads

Abrufen eines Dashboards

Aktualisieren eines Dashboards

Löschen eines Dashboards

Auflisten von Dashboards

Feedback

Zusätzliche Ressourcen