cloudBitのpub/sub APIを試す


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

すべて2014年9月時点、Version 2 のAPIを使った場合の情報です。普通の API を使う方法については[こちら](http://qiita.com/kinu/items/569b5b909b51e1a5d4fd)

# 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 コマンドで試してみます：

```bash: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) の情報を取得できます：

```bash: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 ではないのかも…）

```javascript: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 でデコードできました：

```go: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` の両方を指定する必要があります。

```bash: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 メソッドなんてなかなか見ませんけど、わかりやすいといえばわかりやすいですね…