Nature Remo にログインしてトークンを払い出して API が動くか試すまで

はじめに

DIY スマートホームを構築して家電操作をするために Nature Remo 3 を購入しました。
ローカルから API を叩いて自室の照明が操作できるところまでの手順をまとめています。
（英語の記事はこちら）

Nature Remo 3

シーケンス

想定読者

1. Nature Remo 3 の API を試したい人向け。
2. 短期記憶が揮発性な3ヶ月後の自分向け。

手順

ログイン

アクセストークンを払い出す

払い出したものを 1Password に保存しておく。

API が動くのか試す

制限の確認

API につきものの制約を確認しておく。
https://developer.nature.global/

リクエスト制限 #
サーバはNatureアカウント(メールアドレスで一意に特定する)につき 5分以内に30回 以上のリクエストを受けるとその後ステータスコード 429 を返します。

お客様の要件によりこの制限は緩和することができます。Natureの担当者にご連絡ください。

以下のHTTPリクエストのレスポンスヘッダで最新の制限状態を確認できます。

X-Rate-Limit-Limit : 5分以内に受けられるリクエスト数の上限です。5分以内に30回の制限がかかっている場合には、X-Rate-Limit-Limitは30となります。
X-Rate-Limit-Reset : リクエスト数の制限をリセットする時刻を表すepoch timeです。この時刻を過ぎると、次のリセット時刻までにX-Rate-Limit-Limitの数のリクエストを受けられます。epoch timeについては詳しくはUNIX時間Wikipediaをご確認ください。
X-Rate-Limit-Remaining : X-Rate-Limit-Resetの時刻までに受けられる残りリクエスト数を表します。X-Rate-Limit-Reset直後にはX-Rate-Limit-Limitと一致し、リクエストを受けるたびに数が減っていきます。

個人で使う分には十分そう。テストで沢山叩いても 5分待てば再開可能と。

自宅のどの家電をどう動かすのか調べる

自室の照明を点けたり消したりするには？

メニューにある API 仕様を眺めてみる。

Swagger のドキュメントが開いた。適当な GET メソッドのリクエストを試す。

ACCESS_TOKEN="さっき取得したアクセストークン"
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -X GET "https://api.nature.global/1/users/me"

# 結果
{"id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","nickname":"tqer39"}% 

登録されているリモコンの設定一覧を取得できそうなのを実行

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -X GET "https://api.nature.global/1/appliances" \
  | jq | pbcopy

整形された json でクリップボードに入ったので貼り付け。

[
  {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "device": {
      "name": "Remo3 自室",
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "created_at": "2024-09-17T17:13:49Z",
      "updated_at": "2024-09-22T05:58:38Z",
      "mac_address": "xx:xx:xx:xx:xx:xx",
      "bt_mac_address": "xx:xx:xx:xx:xx",
      "serial_number": "XXXXXXXXXXXXXX",
      "firmware_version": "Remo/1.14.6",
      "temperature_offset": 0,
      "humidity_offset": 0
    },
    "model": null,
    "type": "IR",
    "nickname": "照明",
    "image": "ico_light",
    "settings": null,
    "aircon": null,
    "signals": [
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "消灯",
        "image": "ico_off"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "豆球",
        "image": "ico_night_light"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "調光",
        "image": "ico_lightdown"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "全灯",
        "image": "ico_lightup"
      }
    ]
  }
]

この 照明 の 消灯 を試してみる。

1. 更新リクエストをするから POST メソッドかな？
2. で signals に id があるのでこれを指定できる API
3. ならたぶん POST /1/signals/{signalid}/send これっぽい。

send の Example Value | Schema は空 {} みたいなので特に指定なしで signalId があればよさそう。

signalid="しょうとうのidを設定"
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -X POST "https://api.nature.global/1/signals/${signalid}/send"

# 結果
{}               

動きました

いま作業してる部屋の電気が消えました。
フツーに動いてしまうのでテストしてもいいデバイスで試した方がよいです。

さいごに

イメージしてた通りの操作感でした。
活用して他のサービスや IoT デバイスと連携していこうと思います。