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

## はじめに

DIY スマートホームを構築して家電操作をするために Nature Remo 3 を購入しました。
ローカルから API を叩いて自室の照明が操作できるところまでの手順をまとめています。
（英語の記事は[こちら](https://dev.to/tqer39/getting-started-with-nature-remo-control-your-rooms-lighting-via-shell-script-and-api-1ap8)）

[Nature Remo 3](https://shop.nature.global/products/nature-remo-3?srsltid=AfmBOorDvvXA03hbsTuBYSpAetZHH22byhzTq0cK8YWKDs_lC1z_Xywo)
<img alt="Nature Remo 3 の商品イメージ" width="50%" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/76211d47-ec42-eb2e-a4b6-838e909b5fa9.png" />

### シーケンス

```mermaid
sequenceDiagram
    participant User as ローカル<br>シェルスクリプト
    participant API as Nature Remo<br>クラウドAPI
    participant Device as Nature Remo<br>デバイス
    participant Light as 自室の照明

    User->>API: シグナル送信リクエスト<br>（アクセストークン使用）
    API->>Device: シグナル送信コマンド
    Device->>Light: 赤外線シグナル送信
    Light-->>Device: 照明が操作される
    Device-->>API: 状態更新
    API-->>User: レスポンス<br>（成功/失敗）
```

## 想定読者

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

# 手順

## ログイン

https://api.nature.global/login

![Nature Remo: login](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/d8a102a1-9d93-400c-0372-f58111f7de62.png)

![Nature Remo: login](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/cf0d77df-f4f7-988b-b993-830d3f44aca1.png)

![Nature Remo: request access](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/d5419dd6-a3f8-4dc5-4c50-76fff09806de.png)

![Nature Remo: go](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/59f8fc98-1ac5-b33d-2cb2-8de2a22b89bb.png)

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

![generate a new token](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/7d7160ec-5da4-5cfc-ed7d-9d0d15f7bcf7.png)

払い出したものを 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 仕様を眺めてみる。
![documentation: CLOUD API](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/1083d936-d6f2-bdfe-d583-9e4c7c7826de.png)

Swagger のドキュメントが開いた。適当な GET メソッドのリクエストを試す。
![Swagger](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/f53a299e-6624-0e05-9e1d-cb0e5ae19d20.png)

```shell
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"}% 
```

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

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

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

```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 メソッドかな？
1. で `signals` に `id` があるのでこれを指定できる API
1. ならたぶん `POST /1/signals/{signalid}/send` これっぽい。

send の `Example Value | Schema` は空 `{}` みたいなので特に指定なしで `signalId` があればよさそう。
![send method](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112128/fa3e4588-23f1-0ca2-6765-8b57ba4705ae.png)

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

# 結果
{}               
```

動きました :smiley: 

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

## さいごに

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