Udostępnij za pośrednictwem


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
}

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