cloudBitのpub/sub APIを試す

さわっただけでほとんど何もしてないですが一応メモ。

すべて2014年9月時点、Version 2 のAPIを使った場合の情報です。普通の API を使う方法についてはこちら

Pub/sub APIでセンサ入力をモニタする

cloudBit には簡単な Publisher/Subscriber API が用意されており、センサなどの値を継続的に任意のサービスやプログラムに流し込むことができます。そのうち気温センサなども発売される予定のようなので、cloudBit でセンサシステムを作るというのもありなのかも。

cloudBitからの入力を購読する

入力を購読するために、外部からの POST を受け付ける HTTP エンドポイントを準備します(https はサポートしてないようです)。自前サーバ、heroku、appengine などなどお好きな環境でどうぞ。

購読するには https://api-http.littlebitscloud.cc/devices/subscriptions という URL に以下の様なパラメータを指定して POST します：

パラメータ名	説明
publisher_id	自分のデバイスの Device ID (必須)
subscriber_id	コールバックされるエンドポイントのURLもしくはデバイスID (必須)
publisher_events	購読するチャネルタイプの配列 (オプショナル、複数指定可、後述)

例によって curl コマンドで試してみます：

Terminal

$ curl -i -XPOST \
   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
   -H "Accept: application/vnd.littlebits.v2+json" \
   https://api-http.littlebitscloud.cc/subscriptions \
   -d publisher_id=YOUR_DEVICE_ID \
   -d subscriber_id=http://YOUR_CALLBACK_URL \
   -d publisher_events='["amplitude"]'

これで定期的に YOUR_DEVICE_ID で指定されるデバイスの入力が http://YOUR_CALLBACK_URL にポストされます。

publisher_id だけを指定して同じ URL を GET すると、現在の購読者 (subscriber) の情報を取得できます：

Terminal

$ curl -i -XGET \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "Accept: application/vnd.littlebits.v2+json" \
   'https://api-http.littlebitscloud.cc/subscriptions?publisher_id=DEVICE_ID'
...
{"subscriber_id":"http://YOUR_CALLBACK_URL","publisher_id":"DEVICE_ID","publisher_events":["amplitude"]}

publisher_events に指定できるチャネルには次のようなものがあります：

タイプ	説明
amplitude	電圧があるかぎり常に
amplitude:delta:sustain	一定の高い電圧があるとき (ボタンが押されているなど)
amplitude:delta:ignite	電圧が急にあがったとき (default)
amplitude:delta:release	電圧が急に下がったとき
amplitude:delta:nap	一定の低い電圧があるとき
amplitude:level:active	電圧が高いとき
amplitude:level:idle	電圧が低いとき

入力イベントを処理する

エンドポイントの URL に POST されるデータは次のような JSON データです。（なぜかドキュメントにある内容と微妙に違うので、stable ではないのかも…）

event.json

{
   "type": "amplitude",
   "bit_id": "YOUR_DEVICE_ID",
   "user_id": 00001,
   "timestamp": 12345678,
   "payload":
   {
      "percent": 74,
      "level": "active",
      "delta": "sustain",
   }
}

type は購読してるチャネルタイプ、timestamp は UNIX Epoch 秒、bit_id は購読している cloudBit の Device ID 文字列が入ります。

例えば go の encoding/json では次のような struct でデコードできました：

parseevent.go

type cloudBitEvent struct {
  BitId string      `json:"bit_id"`
  UserId int        `json:"user_id"`
  Timestamp int     `json:"timestamp"`
  Type string       `json:"type"`
  Payload struct {
    Percent int     `json:"percent"`
    Level string    `json:"level"`
    Delta string    `json:"delta"`
  }                 `json:"payload"`
}

POST される間隔ですが、amplitude のように常時データがあるようなチャネルの場合、30秒〜1分おきくらいに継続的に現在のデータが POST されるようです。

購読をやめる

購読をやめるには、https://api-http.littlebitscloud.cc/subscriptions に DELETE メソッドを送ります。購読を中止する publisher_id と subscriber_id の両方を指定する必要があります。

Terminal

$ curl -i -XDELETE \
   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
   -H "Accept: application/vnd.littlebits.v2+json" \
   https://api-http.littlebitscloud.cc/subscriptions \
   -d publisher_id=YOUR_DEVICE_ID \
   -d subscriber_id=http://YOUR_CALLBACK_URL

DELETE メソッドなんてなかなか見ませんけど、わかりやすいといえばわかりやすいですね…