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

:トポロジ関係の管理

最終更新日:Feb 06, 2024

サブデバイスがIoT Platformに登録された後、ゲートウェイはサブデバイスとゲートウェイの間のトポロジ関係を報告して、サブデバイスをIoT Platformに接続する必要があります。

サブデバイスがIoT Platformに接続すると、IoT PlatformはそのIDと、サブデバイスとゲートウェイの間のトポロジ関係を検証します。 検証に成功すると、IoT Platform はサブデバイスとの論理接続を確立し、ゲートウェイの物理接続と論理接続を関連付けます。 サブデバイスとIoT Platform間の通信プロトコルは、直接接続されたデバイスとIoT Platform間の通信プロトコルと同じです。 ゲートウェイ情報は、通信プロトコルにおいて必要とされない。

トポロジ関係が削除された場合、サブデバイスはゲートウェイを使用してIoT Platformに接続できません。 サブデバイスをIoT Platformに接続すると、次のエラーが発生する可能性があります。 トポロジー関係は存在しません。 2. 検証に失敗しました。

サブデバイスのトポロジ関係を追加する

トピックを使用して、ゲートウェイとサブデバイス間のトポロジ関係を追加するリクエストを送信できます。 トポロジ関係が追加された場合、サブデバイスに関する情報が返されます。

重要 一度に最大30のサブデバイスを追加できます。

次のトピックは、サブデバイスがIoT Platformにリクエストを送信し、IoT Platformがサブデバイスに応答を送信する場合に使用されます。

  • リクエストトピック: /sys/${productKey}/${deviceName}/thing/topo/add
  • レスポンストピック: /sys/${productKey}/${deviceName}/thing/topo/add_reply

Alink JSON形式のサンプルリクエスト:

{
  "id": "123",
  "version": "1.0"、
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554",
      "sign": "xxxxxx",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "xxxxxx"
    }
  ],
  "method": "thing.topo.add"
} 

Alink JSON形式のサンプル応答:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

リクエストパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。

sys

オブジェクト

拡張フィーチャのパラメータ。The parameter for extended features. 値には、各フィーチャのフィールドが含まれます。

説明

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

ack

Integer

sysパラメーターの拡張機能フィールド。 このフィールドは、IoT Platformが登録要求の応答データを返すかどうかを指定します。 有効な値:

  • 1: IoT Platformは応答データを返します。

  • 0: IoT Platformは応答データを返しません。

重要

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

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

paramsListリクエストのパラメーター
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー
サインString

署名。

署名方法:

  1. signパラメーターとsignMethodパラメーターを除く、サーバーに送信されたすべてのパラメーターをアルファベット順に並べ替え、接続記号を使用せずにパラメーターと値を順番に接続します。
  2. signMethodパラメーターで指定されたアルゴリズムとDeviceSecretパラメーターの値を使用して、署名を計算します。
例:
sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)
signmethodString署名アルゴリズム。 サポートされているアルゴリズムは、HMACSHA1、HMACSHA256、HMACMD5、およびSHA256です。
timestampStringタイムスタンプ。
clientIdStringオプションです。 デバイスのオンプレミス識別子。 このパラメーターは、次の構文に基づいてProductKeyとDeviceNameを組み合わせた値に設定できます。
メソッドStringリクエスト方式。 値をthing.topo.addに設定します。

レスポンスパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
コードIntegerステータスコード。 値200は、リクエストが成功したことを示します。
データオブジェクトリクエストが成功した場合に返されるサブデバイス情報。 パラメーターの詳細については、次の表をご参照ください。
表1. データ
パラメーターデータ型説明
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

エラーメッセージ

HTTPステータスコードエラーメッセージ説明
460request parameter errorリクエストパラメーターが無効な場合に返されるエラーメッセージ。
6402topo relation cannot add by selfデバイスを自分のサブデバイスとして追加できない場合に返されるエラーメッセージ。
401request auth error署名の検証に失敗した場合に返されるエラーメッセージ。

サブデバイスのトポロジ関係を削除する

トピックを使用して、ゲートウェイとサブデバイス間のトポロジ関係を削除する要求を送信できます。 トポロジ関係が削除された場合、サブデバイスに関する情報が返されます。

重要 一度に最大30のサブデバイスを削除できます。

次のトピックは、サブデバイスがIoT Platformにリクエストを送信し、IoT Platformがサブデバイスに応答を送信する場合に使用されます。

  • リクエストトピック: /sys/${productKey}/${deviceName}/thing/topo/delete
  • レスポンストピック: /sys/${productKey}/${deviceName}/thing/topo/delete_reply

Alink JSON形式のサンプルリクエスト:

{
  "id": "123",
  "version": "1.0"、
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.de lete"
} 

Alink JSON形式のサンプル応答:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

リクエストパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。

sys

オブジェクト

拡張フィーチャのパラメータ。The parameter for extended features. 値には、各フィーチャのフィールドが含まれます。

説明

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

ack

Integer

sysパラメーターの拡張機能フィールド。 このフィールドは、IoT Platformが登録要求の応答データを返すかどうかを指定します。 有効な値:

  • 1: IoT Platformは応答データを返します。

  • 0: IoT Platformは応答データを返しません。

重要

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

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

paramsListリクエストのパラメーター
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー
メソッドStringリクエスト方式。 値をthing.topo.de leteに設定します。

レスポンスパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
コードIntegerステータスコード。 値200は、リクエストが成功したことを示します。
データオブジェクトリクエストが成功した場合に返されるサブデバイス情報。 パラメーターの詳細については、次の表をご参照ください。
表2. データ
パラメーターデータ型説明
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

エラーメッセージ

HTTPステータスコードエラーメッセージ説明
460request parameter errorリクエストパラメーターが無効な場合に返されるエラーメッセージ。
6100device not foundデバイスが存在しない場合に返されるエラーメッセージ。

サブデバイスのトポロジ関係のクエリ

次のトピックは、サブデバイスがIoT Platformにリクエストを送信し、IoT Platformがサブデバイスに応答を送信する場合に使用されます。

  • リクエストトピック: /sys/${productKey}/${deviceName}/thing/topo/get
  • レスポンストピック: /sys/${productKey}/${deviceName}/thing/topo/get_reply

トピックを使用して、ゲートウェイとサブデバイス間のトポロジ関係を照会するリクエストを送信できます。

Alink JSON形式のサンプルリクエスト:

{
  "id": "123",
  "version": "1.0"、
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
} 

Alink JSON形式のサンプル応答:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

リクエストパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。

sys

オブジェクト

拡張フィーチャのパラメータ。The parameter for extended features. 値には、各フィーチャのフィールドが含まれます。

説明

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

ack

Integer

sysパラメーターの拡張機能フィールド。 このフィールドは、IoT Platformが登録要求の応答データを返すかどうかを指定します。 有効な値:

  • 1: IoT Platformは応答データを返します。

  • 0: IoT Platformは応答データを返しません。

重要

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

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

paramsオブジェクトリクエストのパラメーター パラメータは空のままにすることができます。
メソッドStringリクエスト方式。 値をthing.topo.getに設定します。

レスポンスパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
コードIntegerステータスコード。 値200は、リクエストが成功したことを示します。
データオブジェクトリクエストが成功した場合のレスポンスデータ。
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

エラーメッセージ

HTTPステータスコードエラーメッセージ説明
460request parameter errorリクエストパラメーターが無効な場合に返されるエラーメッセージ。

新しく発見されたサブデバイスの送信

次のトピックは、サブデバイスがIoT Platformにリクエストを送信し、IoT Platformがサブデバイスに応答を送信する場合に使用されます。

  • リクエストトピック: /sys/${productKey}/${deviceName}/thing/list/found
  • レスポンストピック: /sys/${productKey}/${deviceName}/thing/list/found_reply

特定のシナリオでは、ゲートウェイは新しいサブデバイスを検出できます。 ゲートウェイは、新しいサブデバイスに関する情報をIoT Platformに報告します。 IoT Platformは情報をサードパーティアプリケーションに転送し、サードパーティアプリケーションはゲートウェイに接続するサブデバイスを選択します。

Alink JSON形式のサンプルリクエスト:

{
  "id": "123",
  "version": "1.0"、
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.list.found"
} 

Alink JSON形式のサンプル応答:

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

リクエストパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。

sys

オブジェクト

拡張フィーチャのパラメータ。The parameter for extended features. 値には、各フィーチャのフィールドが含まれます。

説明

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

ack

Integer

sysパラメーターの拡張機能フィールド。 このフィールドは、IoT Platformが登録要求の応答データを返すかどうかを指定します。 有効な値:

  • 1: IoT Platformは応答データを返します。

  • 0: IoT Platformは応答データを返しません。

重要

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

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

paramsオブジェクトリクエストのパラメーター パラメータは空のままにすることができます。
メソッドStringリクエスト方式。 値をthing.list.foundに設定します。
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

レスポンスパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
コードIntegerステータスコード。 値200は、リクエストが成功したことを示します。
データオブジェクトリクエストが成功した場合のレスポンスデータ。

エラーメッセージ

HTTPステータスコードエラーメッセージ説明
460request parameter errorリクエストパラメーターが無効な場合に返されるエラーメッセージ。
6250product not foundサブデバイスが属する製品が存在しない場合に返されるエラーメッセージ。
6280devicename not meet specsゲートウェイによって報告されたサブデバイスのDeviceNameが無効な場合に返されるエラーメッセージ。

ゲートウェイに通知してサブデバイスのトポロジ関係を追加する

次のトピックは、IoT Platformがサブデバイスにリクエストを送信し、サブデバイスがIoT Platformに応答を送信する場合に使用されます。

  • リクエストトピック: /sys/${productKey}/${deviceName}/thing/topo/add/notify
  • レスポンストピック: /sys/${productKey}/${deviceName}/thing/topo/add/notify_reply

IoT Platformは、トピックを使用してゲートウェイに通知し、サブデバイスのトポロジ関係を追加できます。 これは、ゲートウェイが新しいサブデバイスを発見し、サブデバイス情報をIoT Platformに報告した後に適用されます。 IoT Platformは、次のデータ転送トピックをサブスクライブして、ゲートウェイから応答を受信できます。/${productKey}/${deviceName}/thing/downlink/reply/message

Alink JSON形式のサンプルリクエスト:

{
  "id": "123",
  "version": "1.0"、
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.add.notify"
} 

Alink JSON形式のサンプル応答:

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

リクエストパラメーター

パラメーターデータ型説明
idString

IoT Platformによって生成されるメッセージID。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。

バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。
paramsオブジェクトリクエストのパラメーター パラメータは空のままにすることができます。
メソッドStringリクエスト方式。 値をthing.topo.add.notifyに設定します。
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

レスポンスパラメーター

パラメーターデータ型説明
idStringメッセージの ID 。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。
コードIntegerステータスコード。 値200は、リクエストが成功したことを示します。
データオブジェクトリクエストが成功した場合のレスポンスデータ。

トポロジ関係の変更をゲートウェイに通知する

IoT Platformは、トポロジ関係の変更をゲートウェイに通知します。

ゲートウェイは、次のトピックをサブスクライブする必要があります。/sys/${productKey}/${deviceName}/thing/topo/change

API 操作行動通知方法
ゲートウェイにサブデバイスを追加します。ゲートウェイとサブデバイス間のトポロジ関係を追加します。 ゲートウェイに通知します。
サブデバイスを削除します。サブデバイスとゲートウェイ間のトポロジ関係を削除します。
サブデバイスを無効にします。サブデバイスと、サブデバイスとゲートウェイ間のトポロジ関係を無効にします。
サブデバイスを有効にします。サブデバイスを有効にし、サブデバイスとゲートウェイ間のトポロジ関係を復元します。

Alink JSON形式のサンプルリクエスト:

{
    "id":"123",
    "version": "1.0"、
    "param": {
        "status":0, // 0-追加1-削除2-再開無効8-無効
        "subList":[{
            "productKey":"a1hRrzD ****" 、
            "deviceName":"abcd"
        }]
    }, 
  "method":"thing.topo.change"
} 

リクエストパラメーター

パラメーターデータ型説明
idString

IoT Platformによって生成されるメッセージID。 有効な値: 0 ~ 4294967295 各メッセージIDは、デバイスに対して一意である必要があります。

バージョンStringプロトコルのバージョン番号。 値を 1.0 に設定します。
メソッドStringリクエスト方式。 値をthing.topo.changeに設定します。
paramsオブジェクトstatusおよびsubListパラメーターを含むリクエストパラメーター。 statusパラメーターは、トポロジー関係のステータスを指定します。 subListパラメーターは、サブデバイスのリストを指定します。
statusIntegerトポロジー関係のステータス。
  • 0: トポロジー関係が追加されます。
  • 1: トポロジー関係が削除されます。
  • 2: トポロジー関係が有効になります。
  • 8: トポロジー関係は無効です。
deviceNameStringサブデバイスのDeviceName。
productKeyStringサブデバイスが属するプロダクトのプロダクトキー

Alink JSON形式のサンプル応答:

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