プロダクトに TSL を定義している場合、このプロダクトのデバイスは定義したプロパティ、イベント、およびサービスに関するデータを個別に報告できます。 このトピックでは、TSL に基づいてデータがどのように報告されるか説明します。 TSL のデータ形式の詳細は、「TSL 形式 (The TSL format)」をご参照ください。

プロダクトを作成するときは、そのプロダクトのデバイスのデータタイプを選択する必要があります。 IoT Platform は、ICA 標準データ形式 (Alink JSON) と解析しない/カスタマイズの 2 つのデータタイプをサポートします。
  • ICA 標準データ形式 (Alink JSON) : デバイスは IoT Platform で定義されている標準形式でデータを生成し、そのデータをIoT Platform に報告します。 このデータタイプの選択を推奨します。 このトピックの以下の例では Alink JSON 形式を使用していることにご注目ください。
  • 解析しない/カスタマイズ : デバイスはバイナリデータなどの生データをIoT Platform に報告し、その後 IoT Platform はコンソールでサブミットした解析スクリプトを使用して生データを標準データに解析します。 データ解析スクリプトの編集方法の詳細は、 「データ解析 (Data parsing)」をご参照ください。

デバイスレポートのプロパティ

レポートデータ (解析しない/カスタマイズ)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/model/up_raw
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/model/up_raw_reply

レポートデータ (Alink JSON)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/event/property/post
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/event/property/post_reply

ルールエンジンを設定して受信したプロパティデータを別の Alibaba Cloud プロダクトインスタンスに転送できます。 ルールアクションの設定例を以下の図に示します。

リクエストメッセージ

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": {
      "value": "on",
      "time": 1524448722000
    },
    "WF": {
      "value": 23.6,
      "time": 1524448722000
    }
  },
  "method": "thing.event.property.post"
}

レスポンスデータ

  • プロダクトのデータタイプが [解析しない/カスタマイズ] の場合、レスポンスデータと類似したデータとなり、デバイスに送信される前にデータ解析スクリプトを使用して IoT Platform によって解析されます。 データ処理手順の詳細は、「デバイスレポートのプロパティとイベント」をご参照ください。

    {
    "id":"123",
    "code":200,
    "method":"thing.event.property.post"
    "data":{}
    }
  • Alink レスポンスメッセージ

    {
      "id": "123",
      "code": 200,
      "data": {}
    }
表 1. リクエストパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
version 文字列 プロトコルのバージョンです。 現在、値は 1.0 です。
params オブジェクト リクエストパラメーターです。 上記のリクエスト例では、デバイスは Power とWF の 2 つのプロパティを報告します。 プロパティ情報には、時間 (プロパティが報告された時間) と値 (プロパティの値) が含まれます。
time Long プロパティが報告された時刻
value オブジェクト プロパティの値
method 文字列 リクエストメソッド
表 2. レスポンスパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
code 整数 結果コードです。 「デバイスの共通コード」をご参照ください。
data 文字列 リクエストが成功したときに返されるデータ

エラーメッセージ

エラーコード エラーメッセージ 説明
460 request parameter error リクエストパラメーターが正しくありません。
6106 map size must less than 200 報告されたプロパティの数が上限を超えています。 一回で報告できるプロパティの最大数は 200 です。
6313 tsl service not available

TSL 検証サービスは利用できません。

IoT Platform は、プロダクトの TSL に従って受信したすべてのプロパティを検証します。 システム例外が発生するとこのエラーが報告されます。 TSL の定義については、「TSL (Thing Specification Language) の説明」をご参照ください。

TSL 検証サービスが利用可能であっても報告されたいくつかのプロパティが TSL で定義されたどのプロパティとも一致しない場合、IoT Platform は無効なプロパティを無視します。 報告されたすべてのプロパティが TSL で定義されたどのプロパティとも一致しない場合、IoT Platform はすべてプロパティを無視します。 この場合、レスポンスは依然として検証が成功したことを示しています。

デバイスプロパティを設定

データをデバイスにプッシュ (解析しない/カスタマイズ)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/model/down_raw
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/model/down_raw_reply

データをデバイスにプッシュ (Alink JSON)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/service/property/set
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/service/property/set_reply
プロパティ設定の結果は、以下のとおりデータ交換のトピックから取得できます。/sys/{productKey}/{deviceName}/thing/downlink/reply/messageルールエンジンを設定して受信したプロパティ設定の結果を別の Alibaba Cloud プロダクトインスタンスに転送できます。 ルールアクションの設定例を以下の図に示します。

リクエストメッセージ

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}

レスポンスメッセージ

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 3. リクエストパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
version 文字列 プロトコルのバージョンです。 現在、値は 1.0 です。
params オブジェクト プロパティパラメーターです。 上記のリクエスト例では、設定されるプロパティは以下のとおりです。
{ "temperature": "30.5" }
.
method 文字列 リクエストメソッド
表 4. レスポンスパラメーター
パラメーター データ 説明
id 文字列 メッセージ ID
code 整数 結果コードです。 「デバイスの共通コード」をご参照ください。
data 文字列 リクエストが成功したときに返されるデータ

デバイスレポートイベント

レポートデータ (解析しない/カスタマイズ)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/model/up_raw
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/model/up_raw_reply

レポートデータ (Alink JSON)

  • リクエストトピック : /sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post
  • レスポンストピック : /sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post_reply

ルールエンジンを設定して受信したイベントデータを別の Alibaba Cloud プロダクトインスタンスに転送できます。 ルールアクションの設定例を以下の図に示します。

Request message

{
  "id": "123",
  "version": "1.0",
  "params": {
    "value": {
      "Power": "on",
      "WF": "2"
    },
    "time": 1524448722000
  },
  "method": "thing.event.{tsl.event.identifier}.post"
}

レスポンスメッセージ

  • プロダクトのデータ型が [解析しない/カスタマイズ] の場合、レスポンスデータは以下の出力と類似したデータとなり、デバイスに送信される前にデータ解析スクリプトを使用して IoT Platform によって解析されます。 データ処理手順の詳細は、「デバイスレポートのプロパティとイベント (Devices report properties and events)」をご参照ください。

    {
    "id":"123",
    "code":200,
    "method":"thing.event.{tsl.event.identifier}.post"
    "data":{}
    }
  • Alink レスポンスメッセージ

    {
      "id": "123",
      "code": 200,
      "data": {}
    }
表 5. リクエストパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
version 文字列 プロトコルのバージョンです。 現在、値は 1.0 です。
params オブジェクト 報告されたイベントのパラメーター
value オブジェクト イベント情報です。 上記のリクエスト例では、イベントは以下のとおりです。
{
      "Power": "on",
      "WF": "2"
    }
time Long イベントが発生したときの UTC タイムスタンプ
method 文字列 リクエストメソッド
表 6. レスポンスパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
code 整数 結果コードです。 「デバイスの共通コード」をご参照ください。
data 文字列 リクエストが成功したときに返されるデータ

たとえば、イベントアラームはプロダクトのTSLで定義されています。

{
  "schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
  "link": "/sys/${productKey}/airCondition/thing/",
  "profile": {
    "productKey": "al123456789",
    "deviceName": "airCondition"
  },
  "events": [
    {
      "identifier": "alarm",
      "name": "alarm",
      "desc": "Fan alarm",
      "type": "alert",
      "required": true,
      "outputData": [
        {
          "identifier": "errorCode",
          "name": "ErrorCode",
          "dataType": {
            "type": "text",
            "specs": {
              "length": "255"
            }
          }
        }
      ],
      "method": "thing.event.alarm.post"
    }
  ]
}

リクエストメッセージ

{
  "id": "123",
  "version": "1.0",
  "params": {
    "value": {
      "errorCode": "error"
    },
    "time": 1524448722000
  },
  "method": "thing.event.alarm.post"
}
  • tsl.event.identifier は TSL 内のイベント ID を示します。 TSL テンプレートの詳細は、 TSL (Thing Specification Language) の説明をご参照ください。
  • IoT Platform は、デバイスが報告したすべてのイベントをプロダクトの TSL に従って検証します。 報告されたイベントが TSL で定義されているどのイベントとも一致しない場合は、エラーコードが返されます。

デバイスサービスの呼び出し

  • データをデバイスにプッシュ (解析しない/カスタマイズ)

    • リクエストトピック : /sys/{productKey}/{deviceName}/thing/model/down_raw
    • レスポンストピック : /sys/{productKey}/{deviceName}/thing/model/down_raw_reply
  • データをデバイスにプッシュ (Alink JSON)

    • リクエストトピック : /sys/{productKey}/{deviceName}/thing/service/{tsl.service.identifier}
    • レスポンストピック : /sys/{productKey}/{deviceName}/thing/service/{tsl.service.identifier}_reply
サービスを定義するときは、サービスの方式を選択する必要があります。 サービスの方式は、同期方式または非同期方式のどちらでもかまいません。
  • 同期方式 : IoT Platform は RRPC 方式を使用してリクエストをデバイスにプッシュします。 RRPC 方式の詳細は、「RRPC について (What is RRPC)」をご参照ください。
  • 非同期方式 : IoT Platform は非同期的にリクエストをデバイスにプッシュし、デバイスは非同期的にオペレーション結果を返します。

    IoT Platform がレスポンストピックをサブスクライブするのはサービスに対して非同期方式が選択されている場合だけです。 オペレーション結果は、以下のとおりデータ交換のトピックから取得できます。/sys/{productKey}/{deviceName}/thing/downlink/reply/message.

    ルールエンジンを設定してデバイスから返されるサービス呼び出しの結果を別の Alibaba Cloud プロダクトインスタンスに転送できます。 ルールアクションの設定例を以下の図に示します。

リクエストメッセージ

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": "on",
    "WF": "2"
  },
  "method": "thing.service.{tsl.service.identifier}"
}

レスポンスメッセージ

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 7. リクエストパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
version 文字列 プロトコルのバージョンです。 現在、値は 1.0 です。
params オブジェクト サービスの呼び出しに使用されるパラメーターで、サービスの識別子と値が含まれます。 例 :
{
      "Power": "on",
      "WF": "2"
    }
method 文字列 リクエスト方式
表 8. レスポンスパラメーター
パラメーター データタイプ 説明
id 文字列 メッセージ ID
code 整数 結果コードです。 「デバイスの共通コード」をご参照ください。
data 文字列 リクエストが成功したときに返されるデータです。

データの値はプロダクトの TSL によって決まります。 デバイスがサービスに関する情報を返さない場合、data の値は空です。 デバイスがサービス情報を返す場合、返されるデータ値は TSL 内のサービスの定義に厳密に準拠します。

たとえば、サービス SetWeight の プロダクトの TSL 内の定義は以下のとおりです。

{
  "schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
  "profile": {
    "productKey": "testProduct01"
  },
  "services": [
    {
      "outputData": [
        {
          "identifier": "OldWeight",
          "dataType": {
            "specs": {
              "unit": "kg",
              "min": "0",
              "max": "200",
              "step": "1"
            },
            "type": "double"
          },
          "name": "OldWeight"
        },
        {
          "identifier": "CollectTime",
          "dataType": {
            "specs": {
              "length": "2048"
            },
            "type": "text"
          },
          "name": "CollectTime"
        }
      ],
      "identifier": "SetWeight",
      "inputData": [
        {
          "identifier": "NewWeight",
          "dataType": {
            "specs": {
              "unit": "kg",
              "min": "0",
              "Max": 200,
              "step": "1"
            },
            "type": "double"
          },
          "name": "NewWeight"
        }
      ],
      "method": "thing.service.SetWeight",
      "name": "SetWeight",
      "required": false,
      "callType": "async"
    }
  ]
}

サービス呼び出しのためのリクエストメッセージ:

{
  "method": "thing.service.SetWeight",
  "id": "105917531",
  "param": {
    "NewWeight": 100.8
  },
  "version": "1.0.0"、
}

レスポンスメッセージ:

{
  "id": "105917531",
  "code": "200",
  "data": {
    "CollectTime": "1536228947682",
    "OldWeight": 100.101
  }
}
tsl.service.identifier は、TSL でのサービスの識別子を示しています。TSL の定義方法について詳しくは、「TSL (Thing Specification Language) の説明」をご参照ください。

ゲートウェイデバイスレポートデータ

ゲートウェイデバイスは、そのサブデバイスも含めてプロパティとイベントを IoT Platform にレポートすることができます。

  • 200 までプロパティをレポートできます。
  • ゲートウェイは一度に 20 までイベントをレポートできます。
  • ゲートウェイは 20 までのサブデバイスのプロパティとイベントをレポートできます。
  • IoT Platform は、デバイス、位相関係、TSL でのプロパティとイベントの定義を検証します。いずれか1つの検証が失敗すると、データも失敗とレポートします。

レポートデータ (解析しない/カスタマイズ)

  • リクエストトピック: Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw
  • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/add_reply

レスポンスデータ (Alink JSON)

  • リクエストトピック: /sys/{productKey}/{deviceName}/thing/event/property/pack/post
  • レスポンストピック: /sys/{productKey}/{deviceName}/thing/event/property/pack/post_reply

リクエストメッセージ

{
  "id": "123", 
  "version": "1.0"、 
  "param": {
    "properties": {
      "Power": {
        "value": "on", 
        "time": 1524448722000
      }, 
      "WF": {
        "value":{ 
        "time": 1524448722000
      }
    }, 
    "events": {
      "alarmEvent1": {
        "value":{
          "param1": "on", 
          "param2": "2"
        }, 
        "time": 1524448722000
      }, 
      "alertEvent2": {
        "value":{
          "param1": "on", 
          "param2": "2"
        }, 
        "time": 1524448722000
      }
    }, 
    "subDevices": [
      {
        "identity": {
          "productKey": "", 
          "deviceName": ""
        }, 
        "properties": {
          "Power": {
            "value": "on", 
            "time": 1524448722000
          }, 
          "WF": {
            "value": { }, 
            "time": 1524448722000
          }
        }, 
        "events": {
          "alarmEvent1": {
            "value": {
              "param1": "on", 
              "param2": "2"
            }, 
            "time": 1524448722000
          }, 
          "alertEvent2": {
            "value": {
              "param1": "on", 
              "param2": "2"
            }, 
            "time": 1524448722000
          }
        }
      }
    ]
  }, 
  "method": "thing.event.property.pack.post"
}

レスポンスメッセージ

{
  "id": "123",
  "code": 200,
  "data": {}
}

リクエストパラメーター

パラメーター データタイプ 説明
id 文字列 メッセージ ID
version 文字列 プロトコルのバージョンです。 現在、値は 1.0 です。
params オブジェクト リクエストパラメーターです。
properties オブジェクト プロパティ名、値、プロパティが生成された時刻など、プロパティに関する情報
events オブジェクト プロパティ名、値、イベントが生成された時刻など、イベントに関する情報
subDevices オブジェクト サブデバイス情報
productKey 文字列 サブデバイスの ProductKey
deviceName 文字列 サブデバイスの名前
method 文字列 リクエスト方式

レスポンスパラメーター

パラメーター データタイプ 説明
id 文字列 メッセージ ID
code 整数 結果コードです。 200 はリクエストが成功したことを示します。
data オブジェクト リクエストが成功したときに返されるデータ