使用 REST API 來建立和管理 IoT Central 應用程式

發行項
06/27/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 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
        }
    ]
}

共用方式為

使用 REST API 來建立和管理 IoT Central 應用程式

列出您的應用程式

建立 IoT Central 應用程式

修改 IoT Central 應用程式

刪除 IoT Central 應用程式

儀表板

儀表板 REST API

新增儀表板

折線圖圖格

Markdown 圖格

上次已知的值圖格

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

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

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

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

取得儀表板

更新儀表板

刪除儀表板

列出儀表板

意見反應

意見反應

其他資源

共用方式為

使用 REST API 來建立和管理 IoT Central 應用程式

列出您的應用程式

建立 IoT Central 應用程式

修改 IoT Central 應用程式

刪除 IoT Central 應用程式

儀表板​​

儀表板 REST API

新增儀表板

折線圖圖格

Markdown 圖格

上次已知的值圖格

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

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

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

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

取得儀表板

更新儀表板

刪除儀表板

列出儀表板

意見反應

意見反應

其他資源

儀表板