仮想デバイスミラーの作成と管理

最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。

Classic/VPC環境で利用できます。

仮想デバイスミラー

仮想デバイスミラーの作成および管理方法と、仮想デバイスミラーの Update動作原理について説明します。

仮想デバイスミラーの作成

仮想デバイスミラーを作成する方法は次の通りです。

1. NAVERクラウドプラットフォームコンソールで、Services > Internet of Things > Cloud IoT Core > Virtual Devicesをクリックします。
2. 仮想デバイスを作成します。
   • 仮想デバイスを作成する方法は、仮想デバイスの作成をご参照ください。
3. ミラー作成する仮想デバイスを選択し、 [修正] ボタンをクリックします。
4. ミラー設定領域で [追加] ボタンをクリックします。
5. ミラー名を入力します。
6. ミラーを選択し、 [詳細を見る] ボタンをクリックします。
7. ポップアップウィンドウが表示されたら、ミラーの状態を確認し、 [確認] ボタンをクリックします。
8. [完了] ボタンをクリックします。

仮想デバイスミラーの修正

NAVERクラウドプラットフォームコンソールで仮想デバイスミラーの修正する方法は、以下の通りです。

1. NAVERクラウドプラットフォームコンソールで、Services > Internet of Things > Cloud IoT Core > Virtual Devicesをクリックします。
2. 仮想デバイスを選択し、 [修正] ボタンをクリックします。
3. ミラー設定領域で修正するミラーを選択し、 [詳細を見る] ボタンをクリックします。
4. ポップアップウィンドウが表示されたら、ミラーの状態を修正し、 [確認] ボタンをクリックします。
5. ミラー設定が完了したら、仮想デバイスの修正ページの [完了] ボタンをクリックします。

MQTTメッセージで仮想デバイスミラーを作成したり修正する方法は次の通りです。

1. MQTTメッセージを送信します。
   • トピックは、仮想デバイスミラー MQTT専用トピックのルールに合わせて指定します。
   • updateの場合、$ncp/device/{仮想デバイス名}/mirror/updateに指定し payloadは仮想デバイスミラー updatepayload形式に合ったメッセージを送信します。
2. $ncp/device/{仮想デバイス名}/mirror/update/accepted トピックを購読して、作成および修正が完了していることを確認します。

例) $ncp/device/{仮想デバイス名}/mirror/update/accepted トピックを購読した例は次の通りです。

 $ncp/device/air_conditioner/mirror/update/accepted 
{
  "state": {
    "reported": {
      "temperature": 20
    }
  },
  "metadata": {                             -- (1)
    "reported": {
      "temperature": {
        "timestamp": 1616090000
      }
    }
  },
  "timestamp": 1616090000,                  -- (2)
  "version": 3                              -- (3)
}

• $ncp/device/{仮想デバイス名}/mirror/update/acceptedの内容は、現在保存されているミラーの内容ではなく、updateリクエスト時の MQTTメッセージ payloadの内容をそのまま表示します。例えば、ミラーに desiredの値が保存されていても update payloadで reported値だけ作成して updateする場合は、$ncp/device/{仮想デバイス名}/mirror/update/acceptedメッセージには reportedに関する内容のみ表示されます。
• payloadを使用して clientTokenを伝達できます。
• metadataは、ミラーの保存された時刻の timestamp(1970年1月1日 00:00:00協定世界時(UTC)からの経過時間を秒に換算して定数で表したもの)で、update payloadのstate JSONメッセージと同様の仕組みになっています。
• timestampは、acceptedメッセージが発行された timestampです。ミラーが保存された時間と同じです。
• versionは保存されたミラーの version値です。

仮想デバイスミラーの確認

NAVERクラウドプラットフォームコンソールで、仮想デバイスミラーの情報を確認する方法は次の通りです。

1. NAVERクラウドプラットフォームコンソールで、Services > Internet of Things > Cloud IoT Core > Virtual Devicesをクリックします。
2. ミラーが属する仮想デバイスを選択し、 [修正] ボタンをクリックします。
3. ミラー設定領域で修正するミラーを選択し、 [詳細を見る] ボタンをクリックします。
4. ミラー情報ポップアップウィンドウが表示されたら、保存されたミラーの状態およびメタデータ情報を確認します。

MQTTメッセージで仮想デバイスミラーの情報を確認する方法は次の通りです。

1. 仮想デバイスと仮想デバイスミラーがあることを確認します。
2. MQTTメッセージを送信します。
   • トピックは、仮想デバイスミラー MQTT専用トピックのルールに合わせて指定します。
   • getの場合、$ncp/device/{仮想デバイス名}/mirror/getで指定し、payload入力なしでメッセージを送信します。
3. ncp/device/{仮想デバイス名}/mirror/get/acceptedトピックを購読して、保存されているミラーの内容を確認します。

例) ncp/device/air_conditioner/mirror/get/accepted トピックを購読した例は次の通りです。

$ncp/device/air_conditioner/mirror/get/accepted 
{
  "state": {
    "desired": {
      "temperature": 17
    },
    "reported": {
      "temperature": 20,
      "list" : ["a", "b", {"c" : 2}]
    },
    "delta": {                        
      "temperature": 20
    }
  },
  "metadata": {                       
    "desired": {
      "temperature": {
        "timestamp": 1616010000
      }
    },
    "reported": {
      "temperature": {
        "timestamp": 1616060000
      },
      "list" : [ {"timestamp": 1616060000}, {"timestamp": 1616060000}, {"c" : {"timestamp": 1616060000}} ]
    }
  }
  "timestamp": 1616090000,              
  "version": 3                        
}

• deltaが存在する場合、stateの deltaで確認できます。
• payloadを使用して clientTokenを伝達できます。
• metadataはミラーが保存された時刻の timestamp(1970年1月1日 00:00:00協定世界時(UTC)からの経過時間を秒に換算して定数で表したもの)で値が保存された時間です。state JSONメッセージと同じ仕組みになっています。参考までに、metadataで deltaメッセージに該当する timestampはありません。
• timestampは、acceptedメッセージが発行された timestampです。ミラーが保存された時間と同じです。
• versionは、保存されたミラーの version値を表示します。

仮想デバイスミラーの削除

NAVERクラウドプラットフォームコンソールで仮想デバイスミラーを削除する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、Services > Internet of Things > Cloud IoT Core > Virtual Devicesをクリックします。
2. 削除するミラーが属する仮想デバイスを選択し、 [修正] ボタンをクリックします。
3. ミラー設定領域から削除するミラーを選択し、 [削除] ボタンをクリックします。
4. 仮想デバイスの修正ページの [保存] ボタンをクリックします。

MQTTメッセージで仮想デバイスミラーを削除する方法は次の通りです。

1. MQTTメッセージを送信します。
   • トピックは、仮想デバイスミラー MQTT専用トピックのルールに合わせて指定します。
   • deleteの場合、$ncp/device/{仮想デバイス名}/mirror/deleteで指定し、payload入力なしでメッセージを送信します。
2. $ncp/device/{仮想デバイス名}/mirror/delete/accepted トピックを購読して、削除が完了していることを確認します。

例) ncp/device/air_conditioner/mirror/delete/accepted トピックを購読した例は次の通りです。

$ncp/device/air_conditioner/mirror/delete/accepted 
{
  "timestamp": 1616090000,     
  "version": 3                                       
}

• payloadを使用して clientTokenを伝達できます。
• 最上位 timestamp値は acceptedメッセージが発行された timestampを表示します。
• versionは、最後に保存されたミラーの version値を表示します。

仮想デバイスミラーの Update動作原理

update時、payloadの key値が追加または変更されます。key1がある状態で key2 メッセージを updateすると key2の値が修正され、key2がない場合には key2の値が新たに追加されます。keyを削除するには、「key」: nullで updateします。JSON listは値として扱われ、全体が置き換えられます。

<保存されているミラー>
{
"state": {
  "repoted" : {
     "key1" : 1
   }
 }
}
<updateメッセージ>
{
"state": {
  "repoted" : {
     "key2" : "string2"
   }
 }
}
<最終保存されるミラー>
{
"state": {
  "repoted" : {
     "key1" : 1 
     "key2" : "string2"
   }
 }
}

<保存されているミラー>
{
"state": {
  "repoted" : {
     "key1" : ["a","b", {"nested" : 1} ]
   }
 }
}
<updateメッセージ>
{
"state": {
  "repoted" : {
     "key1" : []
   }
 }
}
<最終保存されるミラー>
{
"state": {
  "repoted" : {
     "key1" : []
   }
 }
}

UPDATE時に発行される deltaメッセージ

Update時、Cloud IoT Coreで $ncp/device/{仮想デバイス名}/mirror/update/delta メッセージが追加で発行されることがあります。deltaとは、state内部の desired(仮想デバイスが要求された状態)と reported(仮想デバイスの現在の状態)を仮想デバイスミラーに転送して得られた2つの値の違いを指します。deltaを確認して desired状態と同じ状態で IoT機器を設定する組み込みプログラミングを作成できます。

• deltaメッセージの発行条件: Update時に保存されたミラーの desiredと reportedで同じキー値に差がある場合、仮想デバイスミラーに delta値が保存され、Cloud IoT Coreで $ncp/device/{仮想デバイス名}/mirror/update/deltaメッセージが発行されます。Deltaメッセージを購読すると、desiredと reportedとの間に差異が発生したことが確認できます。
• reportedにはキー値があるのに desiredにキー値がない場合は、deltaが発生しません。
• 下位レベルの値との差異も比較します。
• 値が JSON List構造である場合は、完全に同じ形式でない限り、deltaが発生します。

$ncp/device/air_conditioner/mirror/update 伝達
{
  "state": {
    "desired": {
       "temperature" : 17,
       "id" : {
            "main" : 1 
       }
    },
    "reported": {
       "temperature" : 20,
        "id" : {
            "main" : 2,
            "sub" : 1
        },
       "another" : "ignored"
    }
  }
}


<deltaメッセージ例>

$ncp/device/air_conditioner/mirror/update/delta
{
  "state": {
    "temperature": 17,   --- (1) temperatureの値が異なり delta発生、
                         --- (2) another keyは reportedにのみあり desiredにない delta発生しない。
     "id" : {
            "main" : 2
      }                    
  },
  "metadata": {
    "temperature": {
      "timestamp": 1616090000
    },
    "id" : {
         "main" : {
             "timestamp": 1616090000
         }
      }  
  },
  "timestamp": 1616090000,
  "version": 3
}

• metadataはミラーが保存された時刻の timestamp(1970年1月1日 00:00:00協定世界時(UTC)からの経過時間を秒に換算して定数で表したもの)で値が保存された時間です。
• timestampは$ncp/device/{仮想デバイス名}/mirror/update/deltaが発行された時刻です。
• versionは最後に保存されたミラーの versionを表示します。
• delta MQTTメッセージで差異が発生した desiredの keyは、すべて stateに表示されます。

UPDATEに発行される doucumentメッセージ

Update時、Cloud IoT Coreで $ncp/device/{仮想デバイス名}/mirror/update/documentsメッセージが発行されます。documentsとは、以前(previous)に保存されたミラーの内容と現在(current)保存されたミラーの内容を一緒に盛り込んだメッセージです。

例)

 $ncp/device/air_conditioner/mirror/update/documents
{
  "previous": { 
    "state": {
      "reported": {
        "temperature": 20
      }
    },
    "metadata": {
      "reported": {
        "temperature": {
          "timestamp": 1616010000
        }
      }
    },
    "version": 2
  },
  "current": {
    "state": {
      "desired": {
        "temperature": 17
      },
      "reported": {
        "temperature": 20
      },
      "delta" : {
        "temperature" : 17
      }
    },
    "metadata": {
      "desired": {
        "temperature": {
          "timestamp": 1616090000
        }
      },
      "reported": {
        "temperature": {
          "timestamp": 1616010000
        }
      }
    },
    "version": 3
  },
  "timestamp": 1616090000
}

• timestampは$ncp/device/{仮想デバイス名}/mirror/update/documentsが発行された時刻です。

仮想デバイスミラーの update payload形式

仮想デバイスミラーの update payload形式は、JSON形式の文字列でなければならず、次のようなメッセージ形式で送信する必要があります。そうでなければ Cloud IoT Coreで$ncp/device/{仮想デバイス名}/mirror/{アクション名}/rejectedメッセージを発行します。

{  
"state" : {
       "reported" : {
          "light" : "on",
          "id_list" : ["sn01", 110, "b10"]
       },
       "desired" : {
          "light" : "off"
       }
   },
  "clientToken" : "ThisIsTokenLengthMaximun1-64byte",          -- (1) option
  "version" : 1                                                -- (2) option
}

• 文書全体は JSON形式で、最上位は JSON Object({} 中括弧)である必要があります。
• 最上位にstateは必ず存在しなければならず、値は必ず JSON Objectである必要があります。
• stateの下位に desiredと reported以外の keyを置いてはいけません。
• desiredと reportedは必須ではなく、任意事項です。ただし、いずれも JSON Objectである必要があります。
• desiredとreportedの下位の JSON Objectの内容は自由形式です。
• desiredとreportedの下位段階 JSON(Nested JSON)は最大 6段階まで許可します。
• clientTokenと versionはすべて選択事項(option)です。

 {
   "state": {
      "reported": {
         "1": { "2": { "3": { "4": { "5": {
                      "6": {    }           -- 最大下位レベル超過 rejected,
                      "6-1": "value"        -- 最大下位レベル許可 accepted
          } } } } }
        }
    }
}

• payloadに clientTokenを持たせてメッセージを送信すると、acceptedメッセージで購読する際に同じ clientTokenが記入されたメッセージを確認できます。使用目的は、どの機器がミラーメッセージを送信して acceptedが発生したのかを識別することにあります。String値で1Byte~64Byteの文字列である必要があり、updateのように get、deleteメッセージでも clientTokenを含む payloadを作成できます。
• payloadに versionを持たせてメッセージを送信すると、現在のミラーの versionと一致するかを確認し、ミラーを修正または削除できます。versionは0より大きい整数である必要があり、渡された versionが保存されたミラーの versionと異なる場合、コンソールで rejectedメッセージを発行します。updateのように deleteメッセージでも versionを含む payloadを作成できます。