Создание приложений IoT Central и управление ими с помощью REST API

Статья
03/08/2024

REST API уровня управления можно использовать для создания приложений IoT Central и управления ими. Rest API также можно использовать для следующих способов:

Добавьте управляемое удостоверение в приложение.
Управление панелями мониторинга в приложении

Для использования этого API требуется маркер носителя для management.azure.com ресурса. Чтобы получить маркер носителя, можно использовать Azure CLI:

az account get-access-token --resource https://management.azure.com

Сведения об управлении приложением IoT Central с помощью пользовательского интерфейса IoT Central см. в статье "Создание приложения IoT Central".

Вывод списка приложений

Чтобы получить список приложений IoT Central в подписке:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

Чтобы получить список приложений IoT Central в группе ресурсов:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

Вы можете получить сведения о отдельном приложении:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01

Создание приложения IoT Central

Чтобы создать приложение IoT Central с назначенным системой управляемым удостоверением:

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

В следующей полезных данных показана конфигурация нового приложения, включая управляемое удостоверение:

{
  "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"
  }
}

Изменение приложения IoT Central

Можно изменить существующее приложение IoT Central. В следующем примере показано, как изменить отображаемое имя и включить управляемое удостоверение, назначенное системой:

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

Используйте следующую полезные данные, чтобы изменить отображаемое имя и включить управляемое удостоверение, назначенное системой:

{
  "properties": {
    "displayName": "Contoso IoT Central App"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Примечание.

Управляемое удостоверение можно добавить только в приложение IoT Central, созданное в регионе. Все новые приложения создаются в регионе.

Удаление приложения IoT Central

Чтобы удалить приложение IoT Central, используйте:

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

Панели мониторинга

Вы можете создавать панели мониторинга, связанные с определенной организацией. Панель мониторинга организации отображается только для пользователей, имеющих доступ к той организации, с которой связана эта панель мониторинга. Только пользователи в роли с разрешениями панели мониторинга организации могут создавать, изменять и удалять панели мониторинга организации.

Все пользователи могут создавать персональные панели мониторинга, видимые только для себя. Пользователи могут переключаться между панелями мониторинга организации и персональными панелями мониторинга.

Примечание.

Создание личных панелей мониторинга с помощью API в настоящее время не поддерживается.

Сведения об управлении панелями мониторинга с помощью пользовательского интерфейса IoT Central см. в статье "Управление панелями мониторинга".

REST API панелей мониторинга

С помощью REST API IoT Central вы можете:

Добавление панели мониторинга в приложение
Обновление панели мониторинга в приложении
Получение списка панели мониторинга в приложении
Получение панели мониторинга по идентификатору
Удаление панели мониторинга в приложении

Добавление панели мониторинга

Используйте следующий запрос, чтобы создать панель мониторинга.

PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

dashboardId — уникальный идентификатор DTMI для панели мониторинга.

Текст запроса содержит некоторые обязательные поля:

@displayName: отображаемое имя панели мониторинга.
@favorite: находится ли панель мониторинга в списке избранного?
group: идентификатор группы устройств.
Tile : настройка, указывающая объект плитки, включая макет, отображаемое имя и конфигурацию.

Плитка содержит некоторые обязательные поля:

Имя	Описание
`displayName`	Отображаемое имя плитки
`height`	Высота плитки
`width`	Ширина плитки
`x`	Горизонтальное положение плитки
`y`	Вертикальное положение плитки

Измерения и расположение плитки используют целые единицы. Наименьшая возможная плитка имеет высоту и ширину одного.

Вы можете настроить объект плитки для отображения нескольких типов данных. В этой статье приведены примеры плиток, показывающих графики, markdown и последнее известное значение. Дополнительные сведения о различных типах плиток, которые можно добавить на панель мониторинга, см. в разделе "Типы плиток".

Плитка "График"

Настройте одно или несколько статистических значений телеметрии для одного или нескольких устройств за период времени. Например, можно отобразить график со средними значениями температуры и давления на одном или нескольких устройствах за прошедший час.

Плитка графики имеет следующую конфигурацию:

Имя	Описание
`capabilities`	Указывает статистическое значение отображаемой телеметрии.
`devices`	Список отображаемых устройств.
`format`	Конфигурация формата диаграммы, например осей для использования.
`group`	Идентификатор отображаемой группы устройств.
`queryRange`	Диапазон времени и разрешение для отображения.
`type`	`lineChart`

Плитка Markdown

Плитки с щелчком, отображающие заголовок и описание, отформатированные в Markdown. URL-адрес может представлять собой относительную ссылку на другую страницу в приложении или абсолютную ссылку на внешний сайт. Плитка Markdown имеет следующую конфигурацию:

Имя	Описание
`description`	Строка markdown для отрисовки внутри плитки.
`href`	Ссылка для посещения при выборе плитки.
`image`	Отображаемое изображение в кодировке Base64.
`type`	`markdown`

Последняя известная плитка значения

Отображение последних значений телеметрии для одного или нескольких устройств. Например, такую плитку можно использовать для отображения актуальных значений температуры, давления и влажности на одном или нескольких устройствах.

Последняя известная плитка (LKV) имеет следующую конфигурацию:

Имя	Описание
`capabilities`	Указывает данные телеметрии для отображения.
`devices`	Список отображаемых устройств.
`format`	Конфигурация формата плитки LKV, например размер текста оболочки слова.
`group`	Идентификатор отображаемой группы устройств.
`showTrend`	Отображение разницы между последним известным значением и предыдущим значением.
`type`	`lkv`

В следующем примере показан текст запроса, который добавляет новую панель мониторинга с графиком, markdown и последними известными плитками значений. Плитки LKV и графиков являются 2x2 плитками. Плитка Markdown — это плитка 1x1 . Плитки расположены в верхней строке панели мониторинга:

{
    "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
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "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
}

Получение панели мониторинга

Используйте следующий запрос, чтобы получить сведения о панели мониторинга с помощью идентификатора панели мониторинга.

GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "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
}

Обновление панели мониторинга

PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

В следующем примере показан текст запроса, который обновляет отображаемое имя панели мониторинга и добавляет панель мониторинга в список избранного:


{
    "displayName": "New Dashboard Name",
    "favorite": true
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "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
}

Удаление панели мониторинга

Используйте следующий запрос, чтобы удалить панель мониторинга с помощью идентификатора панели мониторинга:

DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

Вывод списка панелей мониторинга

Используйте следующий запрос, чтобы получить список панелей мониторинга из приложения:

GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Создание приложений IoT Central и управление ими с помощью REST API

Вывод списка приложений

Создание приложения IoT Central

Изменение приложения IoT Central

Удаление приложения IoT Central

Панели мониторинга

REST API панелей мониторинга

Добавление панели мониторинга

Плитка "График"

Плитка Markdown

Последняя известная плитка значения

Получение панели мониторинга

Обновление панели мониторинга

Удаление панели мониторинга

Вывод списка панелей мониторинга

Дополнительные ресурсы