PicoGW PubSub API

PicoGW PubSub API

2019年4月28日 Documentation 0

PubSubとは、Publish/Subscribeを略したもので、情報伝達のための一形態です。

このモデルでは、情報を受信する側は購読者(Subscriber)と呼ばれ、あらかじめ関心がある情報の種類を購読(Subscribe)しておきます。他方、情報を提供する側が出版者(Publisher)であり、自らが望むタイミングで情報を送信(Publish)すると、その情報をSubscribeしているSubscriberに対して情報が配信されます。

PubSubモデルを用いている代表的なプロトコルの一つがMQTTです。MQTTではSubscriberとPublisherの間に、情報配信だけを担当するブローカーというサーバーが挟まっています。SubscriberはBrokerに対して、あらかじめ自分が関心のある情報の種類(トピックという文字列で指定される)をSubscribeすることを伝えます。Publisherがそのトピックに対してPublishすると、BrokerがSubscriberすべてに情報を配信します。MQTTではローパワーなセンサーデバイスなどが情報受信者のことを意識せずに情報配信でき、この通信自体も軽量になるよう設計されているため、IoTに非常に適しておりよく使われています。

前節で述べたように、PicoGWは3種類のAPIを提供しています。このうちRESTは機器側からの通知を扱うことができませんが、WebSocket/MQTT APIでは接続が維持されるため、PubSubモデルに近い方式で情報配信することができます。

WebSocket APIにおけるPubSub

前節ではPicoGW APIでは以下の形式のJSONオブジェクトを全APIに共通するリクエストの型として用いると説明しました。

{
    "method": "GET, PUTなどメソッド名の文字列",
    "path": "アクセスする情報のパス文字列。REST的に言えばリソース名",
    "args": {呼び出しが必要とする引数のJSONオブジェクト。場合により省略可}
}

この形式はHTTP RESTに直接適用されるため、methodとしてはGET, POST, PUT, DELETEという、いわゆるCRUDはもちろんあります。しかし、RESTの制約から離れたWebSocket APIでのPubSubの実装においても、極力このJSONオブジェクトの型を意識したAPIになっています。つまり、PubSubのためのmethodとしてSUBUNSUBが追加されており、それらのリクエストオブジェクトは次のようになります。

{
    "method": "SUB",
    "path": "購読する情報のパス文字列。REST的に言えばリソース名"
}

SUBを発行しておけば、当該パス文字列が情報発信した時に以下のオブジェクトを受け取ることができます。

{
    "method": "PUB",
    "出版者が情報発信したパス文字列(リソース名)": {情報のペイロード(通常はJSONオブジェクト)}
}

発信元パスが(valueでなく)keyに入っている理由は、複数のパスからの同時配信を可能にするためです。(余談ですが、echonetプラグインではGETメソッドのパスにワイルドカードが使えるようになっており、複数の情報を同時に受け取ることができます。上記のPUBのオブジェクトの方は、こちらと合わせるという面もあります)

購読状態を解除するにはUNSUBを使います。

{
    "method": "UNSUB",
    "path": "購読する情報のパス文字列。REST的に言えばリソース名",
}

なお、PicoGWのすべてのパスがPublishを行うわけではありません。むしろ、Publish可能なパスは非常に限られています。ECHONET Liteであれば、電源など自発的な状態変更通知があるプロパティのみがPublishを行うことができます。Subscribe自体はPublishしないパスであれ問題なくできてしまうので、当該パスがPublishできるかどうか、把握したうえでPubSubを用いてください。

MQTT APIにおけるPubSub

本節の最初で述べたように、MQTTはもともとPubSubをベースに作られています。前節で説明した、RESTと並列に置かれたMQTTでは[PicoGW ID(MAC)]-reqと[PicoGW ID(MAC)]という二つのトピックのみを用い、単なる双方向通信通信路としてのみMQTTを用いていました。
しかし、PubSubの実装においては、よりMQTTらしい呼び出しを行うようになっています。すなわち、あるパスについてSubscribeしたい場合は、WebSocketと共通の

{
    "method": "SUB",
    "path": "[PATH]"
}

という文字列を[PicoGW ID(MAC)]-reqに送るのではなく、[PicoGW ID(MAC)][PATH]という名前のトピックを直接MQTTに沿った形でSubscribeしておけば、当該トピックへのPicoGWからのPublishを受信することができます。例えばPicoGWのIDが11:22:33:44:55:66で、ECHONET Liteのエアコンの電源プロパティの変更通知をPubSubで得たい場合は、11:22:33:44:55:66/v1/echonet/airconditioner_1/operationstateというトピックにSubscribeすればOKです。

これでPicoGW APIの呼び出しの基本的なところについてはおさえたので、あとはパスのリストさえわかれば使えるはずです。


日本語ドキュメントのトップに戻る