Tworzenie aplikacji usługi IoT Central i zarządzanie nimi przy użyciu interfejsu API REST
Interfejs API REST płaszczyzny sterowania umożliwia tworzenie aplikacji usługi IoT Central i zarządzanie nimi. Możesz również użyć interfejsu API REST, aby:
- Dodaj tożsamość zarządzaną do aplikacji.
- Zarządzanie pulpitami nawigacyjnymi w aplikacji
Aby użyć tego interfejsu API, potrzebujesz tokenu elementu nośnego management.azure.com dla zasobu. Aby uzyskać token elementu nośnego, możesz użyć interfejsu wiersza polecenia platformy Azure:
az account get-access-token --resource https://management.azure.com
Aby dowiedzieć się, jak zarządzać aplikacją usługi IoT Central przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Tworzenie aplikacji usługi IoT Central.
Wyświetlanie listy aplikacji
Aby uzyskać listę aplikacji usługi IoT Central w subskrypcji:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Aby uzyskać listę aplikacji usługi IoT Central w grupie zasobów:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Możesz pobrać szczegóły poszczególnych aplikacji:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Tworzenie aplikacji usługi IoT Central
Aby utworzyć aplikację usługi IoT Central z przypisaną przez system tożsamością zarządzaną:
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
Poniższy ładunek przedstawia konfigurację nowej aplikacji, w tym tożsamość zarządzaną:
{
"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"
}
}
Modyfikowanie aplikacji usługi IoT Central
Możesz zmodyfikować istniejącą aplikację usługi IoT Central. W poniższym przykładzie pokazano, jak zmienić nazwę wyświetlaną i włączyć tożsamość zarządzaną przypisaną przez system:
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
Użyj następującego ładunku, aby zmienić nazwę wyświetlaną i włączyć tożsamość zarządzaną przypisaną przez system:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Uwaga
Tożsamość zarządzaną można dodać tylko do aplikacji usługi IoT Central utworzonej w regionie. Wszystkie nowe aplikacje są tworzone w regionie.
Usuwanie aplikacji usługi IoT Central
Aby usunąć aplikację usługi IoT Central, użyj:
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
Pulpity nawigacyjne
Możesz tworzyć pulpity nawigacyjne skojarzone z określoną organizacją. Pulpit nawigacyjny organizacji jest widoczny tylko dla użytkowników, którzy mają dostęp do organizacji, z którym jest skojarzony pulpit nawigacyjny. Tylko użytkownicy w roli z uprawnieniami pulpitu nawigacyjnego organizacji mogą tworzyć, edytować i usuwać pulpity nawigacyjne organizacji.
Wszyscy użytkownicy mogą tworzyć osobiste pulpity nawigacyjne, widoczne tylko dla siebie. Użytkownicy mogą przełączać się między pulpitami nawigacyjnymi organizacji i osobistymi.
Uwaga
Tworzenie osobistych pulpitów nawigacyjnych przy użyciu interfejsu API nie jest obecnie obsługiwane.
Aby dowiedzieć się, jak zarządzać pulpitami nawigacyjnymi przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Jak zarządzać pulpitami nawigacyjnymi.
Interfejs API REST pulpitów nawigacyjnych
Interfejs API REST usługi IoT Central umożliwia wykonywanie następujących działań:
- Dodawanie pulpitu nawigacyjnego do aplikacji
- Aktualizowanie pulpitu nawigacyjnego w aplikacji
- Pobieranie listy pulpitu nawigacyjnego w aplikacji
- Pobieranie pulpitu nawigacyjnego według identyfikatora
- Usuwanie pulpitu nawigacyjnego w aplikacji
Dodaj pulpit nawigacyjny
Użyj następującego żądania, aby utworzyć pulpit nawigacyjny.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId - Unikatowy identyfikator DTMI dla pulpitu nawigacyjnego.
Treść żądania zawiera kilka wymaganych pól:
@displayName: Nazwa wyświetlana pulpitu nawigacyjnego.@favorite: Czy pulpit nawigacyjny znajduje się na liście ulubionych?group: identyfikator grupy urządzeń.Tile: Konfiguracja określająca obiekt kafelka, w tym układ, nazwę wyświetlaną i konfigurację.
Kafelek ma kilka wymaganych pól:
| Nazwa/nazwisko | opis |
|---|---|
displayName |
Nazwa wyświetlana kafelka |
height |
Wysokość kafelka |
width |
Szerokość kafelka |
x |
Położenie kafelka w poziomie |
y |
Położenie kafelka w pionie |
Wymiary i lokalizacja kafelka używają jednostek całkowitych. Najmniejszy możliwy kafelek ma wysokość i szerokość jednego.
Obiekt kafelka można skonfigurować tak, aby wyświetlał wiele typów danych. Ten artykuł zawiera przykłady kafelków, które pokazują wykresy liniowe, znaczniki markdown i ostatnią znaną wartość. Aby dowiedzieć się więcej o różnych typach kafelków, które można dodać do pulpitu nawigacyjnego, zobacz Typy kafelków.
Kafelek wykresu liniowego
Wykreślij co najmniej jedną zagregowaną wartość telemetrii dla co najmniej jednego urządzenia w danym okresie. Można na przykład wyświetlić wykres liniowy, aby wykreślić średnią temperaturę i ciśnienie jednego lub większej liczby urządzeń w ciągu ostatniej godziny.
Kafelek wykresu liniowego ma następującą konfigurację:
| Nazwa/nazwisko | opis |
|---|---|
capabilities |
Określa zagregowaną wartość telemetrii do wyświetlenia. |
devices |
Lista urządzeń do wyświetlenia. |
format |
Konfiguracja formatu wykresu, taka jak osie do użycia. |
group |
Identyfikator grupy urządzeń do wyświetlenia. |
queryRange |
Zakres czasu i rozdzielczość do wyświetlenia. |
type |
lineChart |
Kafelek Markdown
Kafelki z możliwością klikania, które wyświetlają nagłówek i tekst opisu sformatowany w języku Markdown. Adres URL może być względnym linkiem do innej strony w aplikacji lub bezwzględnym linkiem do witryny zewnętrznej. Kafelek markdown ma następującą konfigurację:
| Nazwa/nazwisko | opis |
|---|---|
description |
Ciąg markdown do renderowania wewnątrz kafelka. |
href |
Link do odwiedzenia po wybraniu kafelka. |
image |
Obraz zakodowany w formacie base64 do wyświetlenia. |
type |
markdown |
Kafelek Ostatnia znana wartość
Wyświetl najnowsze wartości telemetrii dla co najmniej jednego urządzenia. Możesz na przykład użyć tego kafelka, aby wyświetlić najnowsze wartości temperatury, ciśnienia i wilgotności dla co najmniej jednego urządzenia.
Ostatni znany kafelek (LKV) ma następującą konfigurację:
| Nazwa/nazwisko | opis |
|---|---|
capabilities |
Określa telemetrię do wyświetlenia. |
devices |
Lista urządzeń do wyświetlenia. |
format |
Konfiguracja formatu kafelka LKV, na przykład rozmiar tekstu opakowującego wyrazy. |
group |
Identyfikator grupy urządzeń do wyświetlenia. |
showTrend |
Pokaż różnicę między ostatnią znaną wartością a poprzednią wartością. |
type |
lkv |
Poniższy przykład przedstawia treść żądania, która dodaje nowy pulpit nawigacyjny z wykresem liniowym, znacznikami markdown i ostatnimi znanymi kafelkami wartości. Kafelki LKV i wykresu liniowego to 2x2 kafelki. Kafelek markdown to 1x1 kafelek. Kafelki są rozmieszczone w górnym wierszu pulpitu nawigacyjnego:
{
"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
}
Odpowiedź na to żądanie wygląda następująco:
{
"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
}
Dodawanie konfiguracji konta magazynu przekazywania pliku
Użyj następującego żądania, aby utworzyć konfigurację konta usługi Blob Storage przekazywania plików w aplikacji usługi IoT Central:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Treść żądania ma następujące pola:
account: nazwa konta magazynu, do którego ma być przekazywany plik.connectionString: parametry połączenia, aby nawiązać połączenie z kontem magazynu.container: nazwa kontenera na koncie magazynu. W poniższym przykładzie użyto nazwyfileuploads.etag: Element ETag, aby zapobiec konfliktowi z wieloma przekazywaniemsasTtl: standard czasu trwania ISO 8601. Czas żądania przekazania pliku przez urządzenie jest ważny przed jego wygaśnięciem.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
Odpowiedź na to żądanie wygląda następująco:
{
"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\""
}
Pobieranie konfiguracji konta magazynu przekazywania pliku
Użyj następującego żądania, aby pobrać szczegóły konfiguracji konta usługi Blob Storage przekazywania pliku w aplikacji usługi IoT Central:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Odpowiedź na to żądanie wygląda następująco:
{
"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\""
}
Aktualizowanie konfiguracji konta magazynu przekazywania pliku
Użyj następującego żądania, aby zaktualizować konto usługi Blob Storage przekazywania plików parametry połączenia w aplikacji usługi IoT Central:
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/"
}
Odpowiedź na to żądanie wygląda następująco:
{
"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\""
}
Usuwanie konfiguracji konta magazynu przekazywania pliku
Użyj następującego żądania, aby usunąć konfigurację konta magazynu:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Uzyskiwanie pulpitu nawigacyjnego
Użyj następującego żądania, aby pobrać szczegóły pulpitu nawigacyjnego przy użyciu identyfikatora pulpitu nawigacyjnego.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Odpowiedź na to żądanie wygląda następująco:
{
"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
}
Aktualizowanie pulpitu nawigacyjnego
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Poniższy przykład przedstawia treść żądania, która aktualizuje nazwę wyświetlaną pulpitu nawigacyjnego i dodaje pulpit nawigacyjny do listy ulubionych:
{
"displayName": "New Dashboard Name",
"favorite": true
}
Odpowiedź na to żądanie wygląda następująco:
{
"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
}
Usuwanie pulpitu nawigacyjnego
Użyj następującego żądania, aby usunąć pulpit nawigacyjny przy użyciu identyfikatora pulpitu nawigacyjnego:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Wyświetlanie listy pulpitów nawigacyjnych
Użyj następującego żądania, aby pobrać listę pulpitów nawigacyjnych z aplikacji:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
Odpowiedź na to żądanie wygląda następująco:
{
"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
}
]
}