すべてのプロダクト
Search
ドキュメントセンター

IoT Platform:デバイスの期待されるプロパティ値

最終更新日:Mar 26, 2025

デバイスを制御するには、IoT Platform で SetDeviceDesiredProperty 操作を呼び出して、デバイスの期待されるプロパティ値を設定します。IoT Platform でデバイスの期待されるプロパティ値を設定すると、デバイスがオンラインの場合はプロパティ値がリアルタイムで更新されます。デバイスがオフラインの場合、期待されるプロパティ値は IoT Platform にキャッシュされます。デバイスが再びオンラインになると、デバイスは期待されるプロパティ値を取得し、既存のプロパティ値を更新します。このトピックでは、デバイスの期待されるプロパティ値に関連するメッセージ形式について説明します。

説明 IoT Platform で SetDeviceDesiredProperty 操作を呼び出してデバイスの期待されるプロパティ値を設定する方法の詳細については、「SetDeviceDesiredProperty」をご参照ください。

期待されるプロパティ値の取得

デバイスが IoT Platform にリクエストを送信し、IoT Platform がデバイスにレスポンスを送信する場合、以下のトピックが使用されます。

デバイスは、IoT Platform から期待されるプロパティ値を取得するためのリクエストを送信します。

  • リクエスト Topic:/sys/${productKey}/${deviceName}/thing/property/desired/get
  • レスポンス Topic:/sys/${productKey}/${deviceName}/thing/property/desired/get_reply

Alink JSON 形式のリクエスト例:

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
  },
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"
}

Alink JSON 形式のレスポンス例:

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}
表 1. リクエストパラメーター
パラメータータイプ説明
idStringメッセージの ID。有効な値:0 ~ 4294967295。各メッセージ ID は、デバイスに対して一意である必要があります。
versionStringプロトコルのバージョン。有効な値:1.0。

sys

Object

拡張機能のパラメーター。値には、各機能のフィールドが含まれています。

説明

デバイス SDK を使用してデバイス機能を開発するときに拡張機能が構成されていない場合、このパラメーターは使用できません。拡張機能はデフォルトの構成を使用します。

ack

Integer

sys パラメーターの拡張機能フィールド。このフィールドは、IoT Platform が登録リクエストのレスポンスデータを返すかどうかを指定します。有効な値:

  • 1: IoT Platform はレスポンスデータを返します。

  • 0: IoT Platform はレスポンスデータを返しません。

重要

このパラメーターの詳細については、「TSL モデルの使用方法の例」をご参照ください。

機能が構成されていない場合、このパラメーターは使用できません。デフォルトでは、IoT Platform は登録リクエストのレスポンスデータを返します。

paramsList期待値を取得するプロパティの識別子リスト。

この例では、次のプロパティ識別子がリストされています。

[ 
 "power",
 "temperature"
 ]

カスタムモジュールプロパティの識別子は、モジュール識別子:プロパティ識別子 の形式です。例:

[ 
 "test:power",
 "test:temperature"
 ]
methodStringリクエストメソッド。有効な値:thing.property.desired.get
表 2. レスポンスパラメーター
パラメータータイプ説明
idStringメッセージの ID。有効な値:0 ~ 4294967295。各メッセージ ID は、デバイスに対して一意である必要があります。
codeIntegerレスポンスの HTTP ステータスコード。詳細については、「デバイスの共通コード」をご参照ください。
dataObject返される期待値情報。

この例では、power プロパティに関する期待値情報が返されます。情報には、プロパティの valueversion が含まれます。

{
  "power": {
    "value": "on", 
    "version": 2
  }
}

カスタムモジュールプロパティの識別子は、モジュール識別子:プロパティ識別子 の形式です。例:

{
  "test:power": {
    "value": "on", 
    "version": 2
  }
}
説明 IoT Platform でプロパティに期待値が設定されていない場合、または期待値が削除されている場合、返されるデータにはこのプロパティの識別子は含まれません。この例では、temperature プロパティには期待値がありません。したがって、返されるデータにはこのプロパティ識別子は含まれません。

data 内のパラメーターの詳細については、次の表を参照してください。

表 3. data
パラメータータイプ説明
keyStringプロパティの識別子 (この例では power)。
valueObject期待値。
versionInteger期待値の現在のバージョン。
説明 期待されるプロパティ値を初めて設定すると、バージョンは 1 になります。その後、期待値を設定するたびにバージョンが 1 ずつ増加します。

期待されるプロパティ値の削除

デバイスが IoT Platform にリクエストを送信し、IoT Platform がデバイスにレスポンスを送信する場合、以下のトピックが使用されます。

デバイスは、IoT Platform にキャッシュされている期待されるプロパティ値を削除するためのリクエストを送信します。

  • リクエスト Topic:/sys/${productKey}/${deviceName}/thing/property/desired/delete
  • レスポンス Topic:/sys/${productKey}/${deviceName}/thing/property/desired/delete_reply

Alink JSON 形式のリクエスト例:

{
    "id": "123",
    "version": "1.0",
    "sys":{
      "ack":0
  },
    "params": {
        "power": {
            "version": 1
        },
        "temperature": { }
    },
    "method":"thing.property.desired.delete"  
}

Alink JSON 形式のレスポンス例:

{
    "id": "123",
    "code": 200,
    "data": { }
}
表 4. リクエストパラメーター
パラメータータイプ説明
idStringメッセージの ID。有効な値:0 ~ 4294967295。各メッセージ ID は、デバイスに対して一意である必要があります。
versionStringプロトコルのバージョン。有効な値:1.0。

sys

Object

拡張機能のパラメーター。値には、各機能のフィールドが含まれています。

説明

デバイス SDK を使用してデバイス機能を開発するときに拡張機能が構成されていない場合、このパラメーターは使用できません。拡張機能はデフォルトの構成を使用します。

ack

Integer

sys パラメーターの拡張機能フィールド。このフィールドは、IoT Platform が登録リクエストのレスポンスデータを返すかどうかを指定します。有効な値:

  • 1: IoT Platform はレスポンスデータを返します。

  • 0: IoT Platform はレスポンスデータを返しません。

重要

このパラメーターの詳細については、「TSL モデルの使用方法の例」をご参照ください。

機能が構成されていない場合、このパラメーターは使用できません。デフォルトでは、IoT Platform は登録リクエストのレスポンスデータを返します。

paramsObject期待値を削除するプロパティのリスト。プロパティは、識別子と version によって識別されます。例:
{
  "power": {
    "version": 1
  }, 
  "temperature": { }
}

カスタムモジュールプロパティの識別子は、モジュール識別子:プロパティ識別子 の形式です。例:

{
  "test:power": {
    "version": 1
  }, 
  "test:temperature": { }
}

params 内のパラメーターの詳細については、次の表を参照してください。

methodStringリクエストメソッド。有効な値:thing.property.desired.delete
表 5. params
パラメータータイプ説明
keyStringプロパティの識別子。この例では、power と temperature というプロパティ識別子がリストされています。
versionInteger削除する期待値のバージョン。
説明
  • version パラメーターの値は、/sys/${productKey}/${deviceName}/thing/property/desired/get トピックから取得できます。
  • version パラメーターを 2 に設定した場合、IoT Platform は現在のバージョンが 2 の場合にのみ期待値を削除します。IoT Platform で期待値の現在のバージョンが 3 の場合、この削除リクエストは無視されます。
  • リクエストで version パラメーターが指定されていない場合、IoT Platform はバージョンを確認せずに、期待値を直接削除します。
表 6. レスポンスパラメーター
パラメータータイプ説明
idStringメッセージの ID。有効な値:0 ~ 4294967295。各メッセージ ID は、デバイスに対して一意である必要があります。
codeIntegerレスポンスの HTTP ステータスコード。詳細については、「デバイスの共通コード」をご参照ください。
dataObject返されるデータ。期待されるプロパティ値を削除するリクエストへのレスポンスでは、データは返されません。

参照