そのREST APIを使用して作成し、 IoT Centralアプリケーションを管理します

[アーティクル]
03/09/2024

コントロールプレーン 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"
  }
}

Note

マネージド ID は、リージョンで作成された 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

ダッシュボード

特定の組織に関連付けられたダッシュボードを作成できます。組織ダッシュボードは、ダッシュボードが関連付けられている組織へのアクセス許可を持つユーザーにのみ表示されます。組織ダッシュボードのアクセス許可が与えられているロールのユーザーのみが組織ダッシュボードを作成、編集、削除できます。

すべてのユーザーが個人用ダッシュボードを作成して、自分だけが見ることができます。ユーザーは、組織および個人用ダッシュボードを切り替えることができます。

Note

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 です。

複数の種類のデータを表示するようにタイルオブジェクトを構成できます。この記事には、折れ線グラフ、マークダウン、最後の既知の値を表示するタイルの例が含まれています。ダッシュボードに追加できるさまざまなタイルの種類の詳細については、「タイルの種類」を参照してください。

折れ線グラフタイル

1 台以上のデバイスの一定期間にわたるテレメトリの集計値がプロットされます。たとえば、1 台以上のデバイスについて過去 1 時間の平均温度と気圧をプロットした折れ線グラフを表示できます。

折れ線グラフタイルの構成は次のとおりです。

名前	説明
`capabilities`	表示するテレメトリの集計値を指定する。
`devices`	表示するデバイスの一覧。
`format`	使用する軸などのグラフの書式構成。
`group`	表示するデバイスグループの ID。
`queryRange`	表示する時間範囲と解像度。
`type`	`lineChart`

マークダウンタイル

Markdown で書式設定された見出しと説明のテキストを表示するクリック可能なタイル。 URL には、アプリケーション内の別のページへの相対リンク、または外部サイトへの絶対リンクを指定できます。マークダウンタイルの構成は次のとおりです。

名前	説明
`description`	タイル内にレンダリングするマークダウン文字列。
`href`	タイルが選択されたときにアクセスするリンク。
`image`	表示する base64 でエンコードされた画像。
`type`	`markdown`

最後の既知の値のタイル

1 台以上のデバイスの最新のテレメトリ値が表示されます。たとえば、このタイルを使用して、1 台以上のデバイスについて、最新の温度、気圧、および湿度の値を表示できます。

最後の既知の値 (LKV) タイルの構成は次のとおりです。

名前	説明
`capabilities`	表示するテレメトリを指定する。
`devices`	表示するデバイスの一覧。
`format`	ワードの折り返しのテキストサイズなど、LKV タイルの書式構成。
`group`	表示するデバイスグループの ID。
`showTrend`	最後の既知の値と前の値の差を表示します。
`type`	`lkv`

次の例は、折れ線グラフ、マークダウン、最後の既知の値タイルを含む新しいダッシュボードを追加する要求本文を示しています。 LKV タイルと折れ線グラフタイルは 2x2 タイルです。マークダウンタイルは 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
        }
    ]
}

次の方法で共有

そのREST APIを使用して作成し、 IoT Centralアプリケーションを管理します

アプリケーションを一覧表示する

IoT Central アプリケーションを作成する

IoT Centralアプリケーションの変更

IoT Centralアプリケーションを削除する

ダッシュボード

ダッシュボード REST API

ダッシュボードを追加する

折れ線グラフタイル

マークダウンタイル

最後の既知の値のタイル

ダッシュボードを取得する

ダッシュボードの更新

ダッシュボードを削除する

ダッシュボードを一覧表示する

その他のリソース

次の方法で共有

そのREST APIを使用して作成し、 IoT Centralアプリケーションを管理します

アプリケーションを一覧表示する

IoT Central アプリケーションを作成する

IoT Centralアプリケーションの変更

IoT Centralアプリケーションを削除する

ダッシュボード​​

ダッシュボード REST API

ダッシュボードを追加する

折れ線グラフ タイル

マークダウン タイル

最後の既知の値のタイル

ダッシュボードを取得する

ダッシュボードの更新

ダッシュボードを削除する

ダッシュボードを一覧表示する

その他のリソース

ダッシュボード

折れ線グラフタイル

マークダウンタイル