你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 REST API 创建和管理 IoT Central 应用程序

  • 项目

你可以使用控制平面 REST API 来创建和管理 IoT Central 应用程序。 你还可以使用 REST API 执行以下操作：

  • 将托管标识添加到应用程序。
  • 管理应用程序中的仪表板

要使用此 API，需要 management.azure.com 资源的持有者令牌。 若要获取持有者令牌，可使用以下 Azure CLI：

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

若要了解如何使用 IoT Central UI 管理 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 UI 管理仪表板，请参阅如何管理仪表板。

仪表板 REST API

使用 IoT Central REST API 可进行以下操作：

  • 将仪表板添加到应用程序
  • 更新应用程序中的仪表板
  • 获取应用程序中的仪表板列表
  • 按 ID 获取仪表板
  • 在应用程序中删除仪表板

添加仪表板

使用以下请求来创建仪表板。

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

dashboardId - 仪表板的唯一 DTMI 标识符。

请求正文包含某些必填字段：

  • @displayName：仪表板的显示名称。
  • @favorite：仪表板在收藏夹列表中吗？
  • group：设备组 ID。
  • Tile：配置指定磁贴对象，包括布局、显示名称和配置。

磁贴有一些必填字段：

名称 描述
displayName 磁贴的显示名称
height 磁贴的高度
width 磁贴宽度
x 磁贴的水平位置
y 磁贴的垂直位置

磁贴的尺寸和位置均使用整数单位。 磁贴的最小可能高度和宽度均为 1。

可以将磁贴对象配置为显示多种类型的数据。 本文包含显示折线图、Markdown 和上一个已知值的磁贴示例。 若要详细了解可添加到仪表板的不同磁贴类型，请参阅磁贴类型。

折线图磁贴

绘制一段时间内一个或多个设备的一个或多个聚合遥测值。 例如，可以显示绘制一个或多个设备在过去一小时中的平均温度和压力的折线图。

折线图磁贴具有以下配置：

名称 描述
capabilities 指定要显示的遥测数据的聚合值。
devices 要显示的设备的列表。
format 图表的格式配置，例如要使用的轴。
group 要显示的设备组的 ID。
queryRange 要显示的时间范围和分辨率。
type lineChart

Markdown 磁贴

显示 Markdown 格式的标题和描述文本的可单击磁贴。 URL 可以是指向应用程序中其他页面的相对链接，也可以是指向外部站点的绝对链接。 Markdown 磁贴具有以下配置：

名称 描述
description 要在磁贴内呈现的 Markdown 字符串。
href 选中磁贴时要访问的链接。
image 要显示的 base64 编码图像。
type markdown

最后一个已知值磁贴

显示一个或多个设备的最新遥测值。 例如，可以使用此磁贴显示一个或多个设备的最新温度、压力和湿度值。

最后已知值 (LKV) 磁贴具有以下配置：

名称 描述
capabilities 指定要显示的遥测数据。
devices 要显示的设备的列表。
format LKV 磁贴的格式配置，例如自动换行的文本大小。
group 要显示的设备组的 ID。
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
}

获取仪表板

使用以下请求，通过使用仪表板 ID 来检索仪表板的详细信息。

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
}

删除仪表板

使用以下请求，通过使用仪表板 ID 删除仪表板：

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