IoT Central REST API を使用してデバイステンプレートを管理する方法

[アーティクル]
06/14/2023

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 REST API を使用すると、ご自身の IoT Central アプリケーション内でデバイステンプレートを管理することができます。

すべての IoT Central REST API 呼び出しに承認ヘッダーが必要です。詳細については、「IoT Central REST API 呼び出しを認証および承認する方法」を参照してください。

IoT Central REST API のリファレンスドキュメントについては、「Azure IoT Central REST API リファレンス」をご覧ください。

ヒント

Postman を使用して、この記事で説明されている REST API 呼び出しを試してみることができます。 IoT Central Postman コレクションをダウンロードし、Postman にインポートしてください。コレクションでは、アプリのサブドメインや管理者トークンなどの変数を設定する必要があります。

IoT Central UI を使用してデバイステンプレートを管理する方法については、「デバイステンプレートを設定する方法」および「デバイステンプレートを編集する方法」を参照する

デバイステンプレート

デバイステンプレートには、デバイスモデルとビュー定義が含まれています。 REST API を使用すると、クラウドプロパティ定義を含むデバイスモデルを管理できます。 UI を使用してビューを作成および管理する必要があります。

デバイステンプレートのデバイスモデルセクションでは、アプリケーションに接続するデバイスの機能が指定されています。機能には、テレメトリ、プロパティ、コマンドが含まれます。モデルは、DTDL V2 を使用して定義されます。

注意

IoT Central では、DTDL 言語の拡張機能がいくつか定義されています。詳細については、「 IoT Central 拡張機能」を参照してください。

デバイステンプレート REST API

IoT Central REST API を使用すると、次のことができます。

アプリケーションにデバイステンプレートを追加します
アプリケーション内でデバイステンプレートを更新します
アプリケーションでデバイステンプレートの一覧を取得します
ID ごとにデバイステンプレートを取得します
アプリケーション内でデバイステンプレートを削除します
アプリケーション内のデバイステンプレートの一覧をフィルター処理する

デバイステンプレートの追加

次の要求を使用して、新しいデバイステンプレートを作成して発行します。既定のビューは、この方法で作成されたデバイステンプレートに対して自動的に生成されます。

PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31

注意

デバイステンプレートの ID は、 DTDL の名前付け規則に従います。次に例を示します。 dtmi:contoso:mythermostattemplate;1

次の例は、サーモスタットデバイス用のデバイステンプレートを追加するための要求本文を示しています。 capabilityModel には、温度テレメトリ、2 つのプロパティ、およびコマンドが含まれます。デバイステンプレートは CustomerName クラウドプロパティを定義し、decimalPlaces、displayUnit、maxValue、minValue を使用して targetTemperature プロパティをカスタマイズします。デバイステンプレート @id は URL の deviceTemplateId の値と一致する必要があります。デバイステンプレートの値 @id は、 capabilityModel@id と同じ値ではありません。

{
    "displayName": "Thermostat",

    "@id": "dtmi:contoso:mythermostattemplate;1",
    "@type": [
        "ModelDefinition",
        "DeviceModel"
    ],
    "@context": [
        "dtmi:iotcentral:context;2",
        "dtmi:dtdl:context;2"
    ],
    "capabilityModel": {
        "@id": "dtmi:contoso:Thermostat;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "Temperature"
                ],
                "description": "Temperature in degrees Celsius.",
                "displayName": "Temperature",
                "name": "temperature",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Allows to remotely specify the desired target temperature.",
                "displayName": "Target Temperature",
                "name": "targetTemperature",
                "schema": "double",
                "unit": "degreeCelsius",
                "writable": true,
                "decimalPlaces": 1,
                "displayUnit": "C",
                "maxValue": 80,
                "minValue": 50
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Returns the max temperature since last device reboot.",
                "displayName": "Max temperature since last reboot.",
                "name": "maxTempSinceLastReboot",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": "Command",
                "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                "displayName": "Get report",
                "name": "getMaxMinReport",
                "request": {
                    "@type": "CommandPayload",
                    "description": "Period to return the max-min report.",
                    "displayName": "Since",
                    "name": "since",
                    "schema": "dateTime"
                },
                "response": {
                    "@type": "CommandPayload",
                    "displayName": "Temperature Report",
                    "name": "tempReport",
                    "schema": {
                        "@type": "Object",
                        "fields": [
                            {
                                "displayName": "Max temperature",
                                "name": "maxTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Min temperature",
                                "name": "minTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Average Temperature",
                                "name": "avgTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Start Time",
                                "name": "startTime",
                                "schema": "dateTime"
                            },
                            {
                                "displayName": "End Time",
                                "name": "endTime",
                                "schema": "dateTime"
                            }
                        ]
                    }
                }
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Customer Name",
                "name": "CustomerName",
                "schema": "string"
            }
        ],
        "description": "Reports current temperature and provides desired temperature control.",
        "displayName": "Thermostat"
    }
}

要求本文には、いくつかの必須フィールドがあります。

@id: 単純な Uniform Resource Name 形式の一意の ID。
@type: 最上位のオブジェクトがであることを "ModelDefinition","DeviceModel"宣言します。
@context: インターフェイスに使用される DTDL バージョンを指定します。
contents: デバイスを構成するプロパティ、テレメトリ、およびコマンドが一覧表示されます。機能は、複数のインターフェイスで定義される場合があります。
capabilityModel :すべてのデバイステンプレートに機能モデルがあります。各モジュール機能モデルとデバイスモデルの間にリレーションシップが確立されます。機能モデルは、1 つまたは複数のモジュールインターフェイスを実装します。

ヒント

デバイステンプレート JSON は標準的な DTDL ドキュメントではありません。デバイステンプレート JSON には、クラウドプロパティの定義や表示単位など、IoT Central 固有のデータが含まれます。 REST API、CLI、UI からデバイステンプレート JSON 形式を使用して、IoT Central のデバイステンプレートをインポートしたりエクスポートしたりできます。

他にも表示名や説明など、機能モデルに詳細を追加するために使用できるオプションのフィールドがいくつかあります。

implements セクションのインターフェイス一覧の各エントリには、次のフィールドがあります。

name: インターフェイスのプログラミング名。
schema: 機能モデルが実装するインターフェイス。

この要求に対する応答は、次の例のようになります。

{
    "etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
    "displayName": "Thermostat",
    "capabilityModel": {
        "@id": "dtmi:contoso:Thermostat;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "Temperature"
                ],
                "description": "Temperature in degrees Celsius.",
                "displayName": "Temperature",
                "name": "temperature",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": [
                    "Property",
                    "Temperature",
                    "NumberValue"
                ],
                "description": "Allows to remotely specify the desired target temperature.",
                "displayName": "Target Temperature",
                "name": "targetTemperature",
                "schema": "double",
                "unit": "degreeCelsius",
                "writable": true,
                "decimalPlaces": 1,
                "displayUnit": "C",
                "maxValue": 80,
                "minValue": 50
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Returns the max temperature since last device reboot.",
                "displayName": "Max temperature since last reboot.",
                "name": "maxTempSinceLastReboot",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": "Command",
                "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                "displayName": "Get report",
                "name": "getMaxMinReport",
                "request": {
                    "@type": "CommandPayload",
                    "description": "Period to return the max-min report.",
                    "displayName": "Since",
                    "name": "since",
                    "schema": "dateTime"
                },
                "response": {
                    "@type": "CommandPayload",
                    "displayName": "Temperature Report",
                    "name": "tempReport",
                    "schema": {
                        "@type": "Object",
                        "fields": [
                            {
                                "displayName": "Max temperature",
                                "name": "maxTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Min temperature",
                                "name": "minTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Average Temperature",
                                "name": "avgTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Start Time",
                                "name": "startTime",
                                "schema": "dateTime"
                            },
                            {
                                "displayName": "End Time",
                                "name": "endTime",
                                "schema": "dateTime"
                            }
                        ]
                    }
                }
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Customer Name",
                "name": "CustomerName",
                "schema": "string"
            }
        ],
        "description": "Reports current temperature and provides desired temperature control.",
        "displayName": "Thermostat"
    },
    "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
    "@type": [
        "ModelDefinition",
        "DeviceModel"
    ],
    "@context": [
        "dtmi:iotcentral:context;2",
        "dtmi:dtdl:context;2"
    ]
}

デバイステンプレートを取得する

お使いのアプリケーションからデバイステンプレートの詳細を取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31

注意

デバイスをマウスでポイントすると、IoT Central のアプリケーション UI から deviceTemplateId を取得できます。

この要求に対する応答は、次の例のようになります。

{
    "etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
    "displayName": "Thermostat",
    "capabilityModel": {
        "@id": "dtmi:contoso:Thermostat;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "Temperature"
                ],
                "description": "Temperature in degrees Celsius.",
                "displayName": "Temperature",
                "name": "temperature",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": [
                    "Property",
                    "Temperature",
                    "NumberValue"
                ],
                "description": "Allows to remotely specify the desired target temperature.",
                "displayName": "Target Temperature",
                "name": "targetTemperature",
                "schema": "double",
                "unit": "degreeCelsius",
                "writable": true,
                "decimalPlaces": 1,
                "displayUnit": "C",
                "maxValue": 80,
                "minValue": 50
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Returns the max temperature since last device reboot.",
                "displayName": "Max temperature since last reboot.",
                "name": "maxTempSinceLastReboot",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": "Command",
                "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                "displayName": "Get report",
                "name": "getMaxMinReport",
                "request": {
                    "@type": "CommandPayload",
                    "description": "Period to return the max-min report.",
                    "displayName": "Since",
                    "name": "since",
                    "schema": "dateTime"
                },
                "response": {
                    "@type": "CommandPayload",
                    "displayName": "Temperature Report",
                    "name": "tempReport",
                    "schema": {
                        "@type": "Object",
                        "fields": [
                            {
                                "displayName": "Max temperature",
                                "name": "maxTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Min temperature",
                                "name": "minTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Average Temperature",
                                "name": "avgTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Start Time",
                                "name": "startTime",
                                "schema": "dateTime"
                            },
                            {
                                "displayName": "End Time",
                                "name": "endTime",
                                "schema": "dateTime"
                            }
                        ]
                    }
                }
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Customer Name",
                "name": "CustomerName",
                "schema": "string"
            }
        ],
        "description": "Reports current temperature and provides desired temperature control.",
        "displayName": "Thermostat"
    },
    "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
    "@type": [
        "ModelDefinition",
        "DeviceModel"
    ],
    "@context": [
        "dtmi:iotcentral:context;2",
        "dtmi:dtdl:context;2"
    ]
}

デバイステンプレートを更新します

PATCH https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31

サンプル要求本文は、デバイステンプレートのにクラウドプロパティを LastMaintenanceDate 追加する capabilityModel 次の例のようになります。

{
    "capabilityModel": {
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "Temperature"
                ],
                "description": "Temperature in degrees Celsius.",
                "displayName": "Temperature",
                "name": "temperature",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Allows to remotely specify the desired target temperature.",
                "displayName": "Target Temperature",
                "name": "targetTemperature",
                "schema": "double",
                "unit": "degreeCelsius",
                "writable": true,
                "decimalPlaces": 1,
                "displayUnit": "C",
                "maxValue": 80.0,
                "minValue": 50.0
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Returns the max temperature since last device reboot.",
                "displayName": "Max temperature since last reboot.",
                "name": "maxTempSinceLastReboot",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": "Command",
                "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                "displayName": "Get report",
                "name": "getMaxMinReport",
                "request": {
                    "@type": "CommandPayload",
                    "description": "Period to return the max-min report.",
                    "displayName": "Since",
                    "name": "since",
                    "schema": "dateTime"
                },
                "response": {
                    "@type": "CommandPayload",
                    "displayName": "Temperature Report",
                    "name": "tempReport",
                    "schema": {
                        "@type": "Object",
                        "fields": [
                            {
                                "displayName": "Max temperature",
                                "name": "maxTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Min temperature",
                                "name": "minTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Average Temperature",
                                "name": "avgTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Start Time",
                                "name": "startTime",
                                "schema": "dateTime"
                            },
                            {
                                "displayName": "End Time",
                                "name": "endTime",
                                "schema": "dateTime"
                            }
                        ]
                    }
                }
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Customer Name",
                "name": "CustomerName",
                "schema": "string"
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Last Maintenance Date",
                "name": "LastMaintenanceDate",
                "schema": "dateTime"
            }
        ],
        "description": "Reports current temperature and provides desired temperature control.",
        "displayName": "Thermostat"
    }
}

この要求に対する応答は、次の例のようになります。

{
    "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
    "displayName": "Thermostat",
    "capabilityModel": {
        "@id": "dtmi:contoso:Thermostat;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "Temperature"
                ],
                "description": "Temperature in degrees Celsius.",
                "displayName": "Temperature",
                "name": "temperature",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Allows to remotely specify the desired target temperature.",
                "displayName": "Target Temperature",
                "name": "targetTemperature",
                "schema": "double",
                "unit": "degreeCelsius",
                "writable": true,
                "decimalPlaces": 1,
                "displayUnit": "C",
                "maxValue": 80,
                "minValue": 50
            },
            {
                "@type": [
                    "Property",
                    "Temperature"
                ],
                "description": "Returns the max temperature since last device reboot.",
                "displayName": "Max temperature since last reboot.",
                "name": "maxTempSinceLastReboot",
                "schema": "double",
                "unit": "degreeCelsius"
            },
            {
                "@type": "Command",
                "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                "displayName": "Get report",
                "name": "getMaxMinReport",
                "request": {
                    "@type": "CommandPayload",
                    "description": "Period to return the max-min report.",
                    "displayName": "Since",
                    "name": "since",
                    "schema": "dateTime"
                },
                "response": {
                    "@type": "CommandPayload",
                    "displayName": "Temperature Report",
                    "name": "tempReport",
                    "schema": {
                        "@type": "Object",
                        "fields": [
                            {
                                "displayName": "Max temperature",
                                "name": "maxTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Min temperature",
                                "name": "minTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Average Temperature",
                                "name": "avgTemp",
                                "schema": "double"
                            },
                            {
                                "displayName": "Start Time",
                                "name": "startTime",
                                "schema": "dateTime"
                            },
                            {
                                "displayName": "End Time",
                                "name": "endTime",
                                "schema": "dateTime"
                            }
                        ]
                    }
                }
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": "Customer Name",
                "name": "CustomerName",
                "schema": "string"
            },
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "DateTimeValue"
                ],
                "displayName": "Last Maintenance Date",
                "name": "LastMaintenanceDate",
                "schema": "dateTime"
            }
        ],
        "description": "Reports current temperature and provides desired temperature control.",
        "displayName": "Thermostat"
    },
    "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
    "@type": [
        "ModelDefinition",
        "DeviceModel"
    ],
    "@context": [
        "dtmi:iotcentral:context;2",
        "dtmi:dtdl:context;2"
    ]
}

デバイステンプレートを削除します

デバイステンプレートを削除するには、次の要求を使用します。

DELETE https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31

デバイステンプレートを一覧表示する

お使いのアプリケーションからデバイステンプレートのリストを取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
            "displayName": "Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:Thermostat;1",
                "@type": "Interface",
                "contents": [
                    {
                        "@type": [
                            "Telemetry",
                            "Temperature"
                        ],
                        "description": "Temperature in degrees Celsius.",
                        "displayName": "Temperature",
                        "name": "temperature",
                        "schema": "double",
                        "unit": "degreeCelsius"
                    },
                    {
                        "@type": [
                            "Property",
                            "Temperature",
                            "NumberValue"
                        ],
                        "description": "Allows to remotely specify the desired target temperature.",
                        "displayName": "Target Temperature",
                        "name": "targetTemperature",
                        "schema": "double",
                        "unit": "degreeCelsius",
                        "writable": true,
                        "decimalPlaces": 1,
                        "displayUnit": "C",
                        "maxValue": 80,
                        "minValue": 50
                    },
                    {
                        "@type": [
                            "Property",
                            "Temperature"
                        ],
                        "description": "Returns the max temperature since last device reboot.",
                        "displayName": "Max temperature since last reboot.",
                        "name": "maxTempSinceLastReboot",
                        "schema": "double",
                        "unit": "degreeCelsius"
                    },
                    {
                        "@type": "Command",
                        "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                        "displayName": "Get report",
                        "name": "getMaxMinReport",
                        "request": {
                            "@type": "CommandPayload",
                            "description": "Period to return the max-min report.",
                            "displayName": "Since",
                            "name": "since",
                            "schema": "dateTime"
                        },
                        "response": {
                            "@type": "CommandPayload",
                            "displayName": "Temperature Report",
                            "name": "tempReport",
                            "schema": {
                                "@type": "Object",
                                "fields": [
                                    {
                                        "displayName": "Max temperature",
                                        "name": "maxTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Min temperature",
                                        "name": "minTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Average Temperature",
                                        "name": "avgTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Start Time",
                                        "name": "startTime",
                                        "schema": "dateTime"
                                    },
                                    {
                                        "displayName": "End Time",
                                        "name": "endTime",
                                        "schema": "dateTime"
                                    }
                                ]
                            }
                        }
                    },
                    {
                        "@type": [
                            "Property",
                            "Cloud",
                            "StringValue"
                        ],
                        "displayName": "Customer Name",
                        "name": "CustomerName",
                        "schema": "string"
                    }
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~XS5GovPNzJqFIwkkV/vyWW5U/6if2NwC/NqUlDxExAY=\"",
            "displayName": "Thermostat2",
            "capabilityModel": {
                "@id": "dtmi:contoso:Thermostat2;1",
                "@type": "Interface",
                "contents": [
                    {
                        "@type": [
                            "Telemetry",
                            "Temperature"
                        ],
                        "description": "Temperature in degrees Celsius.",
                        "displayName": "Temperature",
                        "name": "temperature",
                        "schema": "double",
                        "unit": "degreeCelsius"
                    },
                    {
                        "@type": [
                            "Property",
                            "Temperature",
                            "NumberValue"
                        ],
                        "description": "Allows to remotely specify the desired target temperature.",
                        "displayName": "Target Temperature",
                        "name": "targetTemperature",
                        "schema": "double",
                        "unit": "degreeCelsius",
                        "writable": true,
                        "decimalPlaces": 1,
                        "displayUnit": "C",
                        "maxValue": 80,
                        "minValue": 50
                    },
                    {
                        "@type": [
                            "Property",
                            "Temperature"
                        ],
                        "description": "Returns the max temperature since last device reboot.",
                        "displayName": "Max temperature since last reboot.",
                        "name": "maxTempSinceLastReboot",
                        "schema": "double",
                        "unit": "degreeCelsius"
                    },
                    {
                        "@type": "Command",
                        "description": "This command returns the max, min and average temperature from the specified time to the current time.",
                        "displayName": "Get report",
                        "name": "getMaxMinReport",
                        "request": {
                            "@type": "CommandPayload",
                            "description": "Period to return the max-min report.",
                            "displayName": "Since",
                            "name": "since",
                            "schema": "dateTime"
                        },
                        "response": {
                            "@type": "CommandPayload",
                            "displayName": "Temperature Report",
                            "name": "tempReport",
                            "schema": {
                                "@type": "Object",
                                "fields": [
                                    {
                                        "displayName": "Max temperature",
                                        "name": "maxTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Min temperature",
                                        "name": "minTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Average Temperature",
                                        "name": "avgTemp",
                                        "schema": "double"
                                    },
                                    {
                                        "displayName": "Start Time",
                                        "name": "startTime",
                                        "schema": "dateTime"
                                    },
                                    {
                                        "displayName": "End Time",
                                        "name": "endTime",
                                        "schema": "dateTime"
                                    }
                                ]
                            }
                        }
                    },
                    {
                        "@type": [
                            "Property",
                            "Cloud",
                            "StringValue"
                        ],
                        "displayName": "Customer Name",
                        "name": "CustomerName",
                        "schema": "string"
                    }
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u67",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        }
    ]
}

ODATA フィルターを使用する

プレビューバージョンの API (api-version=2022-10-31-preview) では、ODATA フィルターを使用して、リストデバイステンプレート API によって返される結果をフィルター処理して並べ替えることができます。

maxpagesize

maxpagesize フィルターを使用して、結果のサイズを設定します。返される結果の最大サイズは 100 で、既定のサイズは 25 です。

以下の要求を使用して、アプリケーションから上位 10 個のデバイステンプレートを取得します。

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
            "displayName": "Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:Thermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
            "displayName": "Thermostat3",
            "capabilityModel": {
                "@id": "dtmi:contoso:Thermostat;3",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat3"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;3",
                "dtmi:dtdl:context;2"
            ]
        },
        // ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31&%24top=1&%24skiptoken=%7B%22token%22%3A%22%2BRID%3A%7EJWYqAKZQKp20qCoAAAAACA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65551%23QCF%3A4%22%2C%22range%22%3A%7B%22min%22%3A%2205C1DFFFFFFFFC%22%2C%22max%22%3A%22FF%22%7D%7D"
}

応答には、次の結果ページを取得するために使用できる nextLink 値が含まれています。

filter

フィルターを使用して、デバイステンプレートの一覧をフィルター処理する式を作成します。次の表は、使用できる比較演算子を示しています。

比較演算子	Symbol	例
等しい	eq	`'@id' eq 'dtmi:example:test;1'`
等しくない	ne	`displayName ne 'template 1'`
以下	le	`displayName le 'template A'`
より小さい	lt	`displayName lt 'template B'`
以上	ge	`displayName ge 'template A'`
より大きい	gt	`displayName gt 'template B'`

次の表は、 フィルター 式で使用できるロジック演算子を示しています。

論理演算子	Symbol	例
AND	および	`'@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1'`
OR	or	`'@id' eq 'dtmi:example:test;1' or displayName ge 'template'`

現在、 フィルター は次のデバイステンプレートフィールドで動作します。

FieldName	Type	説明
`@id`	string	デバイステンプレート ID
`displayName`	string	プロファイルテンプレートの表示名
`capabilityModelId`	string	デバイステンプレート機能モデル ID

フィルターでサポートされている関数:

現在、デバイステンプレートリストでサポートされているフィルター関数は、contains 関数のみです。

filter=contains(displayName, 'template1')

次の例は、表示名に文字列 thermostat が含まれている上位 2 つのデバイスを取得する方法を示しています。

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
            "displayName": "Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:Thermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
            "displayName": "Room Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:RoomThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current room temperature and provides desired temperature control.",
                "displayName": "Room Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P7q/KxCU2xskrmk=\"",
            "displayName": "Vehicle Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:VehicleThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current vehicle temperature and provides desired temperature control.",
                "displayName": "Vehicle Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lt7u39u7",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        }
    ]
}

orderby

orderby を使用して結果を並べ替えます。現在、 orderby では displayName でのみ並べ替えることができます。既定では、 orderby は昇順で並べ替えられます。次に例を示すとおり、降順で並べ替えを行うには desc を使用します。

orderby=displayName
orderby=displayName desc

次の例では、結果が displayName で並べ替えられたすべてのデバイステンプレートを取得する方法を示します。

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
            "displayName": "Aircon Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:AirconThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
            "displayName": "Room Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:RoomThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current room temperature and provides desired temperature control.",
                "displayName": "Room Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P7q/KxCU2xskrmk=\"",
            "displayName": "Vehicle Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:VehicleThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current vehicle temperature and provides desired temperature control.",
                "displayName": "Vehicle Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lt7u39u7",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        }
    ]
}

また、2 つ以上のフィルターを組み合わせることもできます。

次の例は、表示名に文字列 thermostat が含まれている上位 2 つのデバイステンプレートを取得する方法を示しています。

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')&maxpagesize=2

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
            "displayName": "Aircon Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:AirconThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current temperature and provides desired temperature control.",
                "displayName": "Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        },
        {
            "etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
            "displayName": "Room Thermostat",
            "capabilityModel": {
                "@id": "dtmi:contoso:RoomThermostat;1",
                "@type": "Interface",
                "contents": [
                    ...
                ],
                "description": "Reports current room temperature and provides desired temperature control.",
                "displayName": "Room Thermostat"
            },
            "@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
            "@type": [
                "ModelDefinition",
                "DeviceModel"
            ],
            "@context": [
                "dtmi:iotcentral:context;2",
                "dtmi:dtdl:context;2"
            ]
        }
    ]
}

次の手順

REST API を使用してデバイステンプレートを管理する方法を学習しましたので、次のステップとしては、「IoT Central GUI からデバイステンプレートを作成する方法」をお勧めします。

Share via

IoT Central REST API を使用してデバイステンプレートを管理する方法

デバイステンプレート

デバイステンプレート REST API

デバイステンプレートの追加

デバイステンプレートを取得する

デバイステンプレートを更新します

デバイステンプレートを削除します

デバイステンプレートを一覧表示する

ODATA フィルターを使用する

maxpagesize

filter

orderby

次の手順

その他のリソース

Share via

IoT Central REST API を使用してデバイス テンプレートを管理する方法

デバイス テンプレート

デバイス テンプレート REST API

デバイス テンプレートの追加

デバイス テンプレートを取得する

デバイス テンプレートを更新します

デバイス テンプレートを削除します

デバイス テンプレートを一覧表示する

ODATA フィルターを使用する

maxpagesize

filter

orderby

次の手順

その他のリソース

IoT Central REST API を使用してデバイステンプレートを管理する方法

デバイステンプレート

デバイステンプレート REST API

デバイステンプレートの追加

デバイステンプレートを取得する

デバイステンプレートを更新します

デバイステンプレートを削除します

デバイステンプレートを一覧表示する