共用方式為


使用 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 \(英文\) 可讓您:

  • 將儀表板新增至您的應用程式
  • 更新應用程式中的儀表板
  • 取得應用程式中儀表板的清單
  • 依識別碼取得儀表板
  • 刪除應用程式中的儀表板

新增儀表板

使用下列要求來建立儀表板。

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 圖格的垂直位置

圖格的維度和位置都使用整數單位。 最小可能的圖格高度和寬度為 1。

您可以設定圖格物件來顯示多種資料類型。 本文包含顯示折線圖、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
}

新增檔案上傳儲存體帳戶設定

使用下列要求,在 IoT Central 應用程式中建立檔案上傳 Blob 儲存體帳戶設定:

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

要求本文具有下列欄位:

  • account:要將檔案上傳至其中的儲存體帳戶名稱。
  • connectionString:要連線到儲存體帳戶的連接字串。
  • container:儲存體帳戶內的容器名稱。 下列範例使用 fileuploads 名稱。
  • etag:防止與多個上傳發生衝突的 Etag
  • sasTtl:ISO 8601 持續時間標準。裝置上傳檔案要求在到期前有效的時間量。
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

此要求的回應如下列範例所示:

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

}

取得檔案上傳儲存體帳戶設定

使用下列要求,在 IoT Central 應用程式中擷取檔案上傳 Blob 儲存體帳戶設定的詳細資料:

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

此要求的回應如下列範例所示:

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

}

更新檔案上傳儲存體帳戶設定

使用下列要求,在 IoT Central 應用程式中更新檔案上傳 Blob 儲存體帳戶連接字串:

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

此要求的回應如下列範例所示:


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

移除檔案上傳儲存體帳戶設定

使用下列要求來刪除儲存體帳戶設定:

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

取得儀表板

使用下列要求,使用儀表板識別碼擷取儀表板的詳細資料。

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