REST API를 사용하여 IoT Central 애플리케이션 만들기 및 관리
컨트롤 플레인 REST API를 사용하여 IoT Central 애플리케이션을 만들고 관리할 수 있습니다. REST API를 사용하여 다음을 수행할 수도 있습니다.
- 애플리케이션에 관리 ID를 추가합니다.
- 애플리케이션에서 대시보드 관리
이 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 애플리케이션 만들기
시스템 할당 관리 ID로 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
다음 페이로드는 관리 ID를 포함하여 새 애플리케이션에 대한 구성을 보여 줍니다.
{
"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 애플리케이션을 수정할 수 있습니다. 다음 예에서는 표시 이름을 변경하고 시스템이 할당한 관리 ID를 사용하도록 설정하는 방법을 보여 줍니다.
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
다음 페이로드를 사용하여 표시 이름을 변경하고 시스템이 할당한 관리 ID를 사용하도록 설정합니다.
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
참고 항목
지역에서 만들어진 IoT Central 애플리케이션에만 관리 ID를 추가할 수 있습니다. 모든 새 애플리케이션은 지역에서 만들어집니다.
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 및 마지막으로 알려진 값을 표시하는 타일의 예가 포함되어 있습니다. 대시보드에 추가할 수 있는 다양한 타일 형식에 대한 자세한 내용은 타일 형식을 참조하세요.
꺾은선형 차트 타일
일정 기간에 걸쳐 하나 이상의 디바이스에 대한 하나 이상의 집계 원격 분석 값을 플로팅합니다. 예를 들어 지난 1시간 동안 하나 이상 디바이스의 평균 온도와 압력을 플로팅하는 꺾은선형 차트를 플로팅할 수 있습니다.
꺾은선형 차트 타일에는 다음과 같은 구성이 있습니다.
| 이름 | 설명 |
|---|---|
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
}
]
}