【完走賞ゲット-17】SwitchBot の新バージョンAPI v1.1 の情報を調べてみたり旧バージョンの API も見てみたり

## はじめに
こちらは、[完走賞ゲットのため小ネタを毎日投稿しようとチャレンジする Advent Calendar 2022](https://qiita.com/advent-calendar/2022/youtoy) の 17日目の記事です。

内容は、以下でツイートもしていた SwitchBot の新バージョンAPI（v1.1）の話と、旧バージョンAPI の話です。

https://twitter.com/youtoy/status/1603905926540701696

## 過去に SwitchBot 関連で書いた記事
今回の話は、SwitchBot 製品を、専用アプリからではなく自分が書いたプログラムから扱う話です。
そういった方向性の話については、過去に BLE を使った方法の記事を書いたことがありました。

- [SwitchBot温湿度計を Web Bluetooth API でスキャンする【試行錯誤中】 - Qiita](https://qiita.com/youtoy/items/e28a10866dd0050251c0)
- [SwitchBot温湿度計のデータを Web Bluetooth API で取得する：【未完】準備や試行錯誤のメモ - Qiita](https://qiita.com/youtoy/items/6abcc9d704aaebcf5b18)
- [SwitchBot温湿度計のデータを Web Bluetooth API で取得する【完結編】 - Qiita](https://qiita.com/youtoy/items/8e3cca2172e2c4806846)

今回は、上記のような近接通信ではなく、Web経由の API を使ったものという内容になります。

## SwitchBot の新バージョンAPI v1.1
### SwitchBot の新バージョンAPI v1.1 に関する公式情報の概要
この新API の話が出たのは、どうやら 2ヶ月前くらいの話のようでした。

●【API】新バージョンAPI v1.1を公開しました - SwitchBot Magazine | スマートホームで暮らしをシンプルに
　https://blog.switchbot.jp/announcement/api-v1-1/

上記の記事の冒頭には、GitHub へのリンクがあったりします。

●OpenWonderLabs/SwitchBotAPI: SwitchBot Open API Documents
　https://github.com/OpenWonderLabs/SwitchBotAPI

### 自分が所有している SwitchBot製品と 新API での対応状況
ここで API関連の話から、いったん自分が所有している SwitchBot製品の話へ（自分のメモも兼ねて）。

だいたい Amazon で買っているので、購入履歴からピックアップしてみます。
![所有しているものの リスト1](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/f8ccc3f2-6739-6b7b-93c7-9f1f05cac6c2.png)
![所有しているものの リスト2](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/e71c8129-6ee4-fe38-01c8-890e9fc30c16.png)
![所有しているものの リスト3](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/63973e59-1dd1-f3a3-0e65-e72ded4e9171.png)

先ほどの公式ページのリストの中では、以下があるという状況です。
![所有しているものの API対応](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/9b85ef3d-81aa-02ba-a143-fa85a48fb725.png)

持っているものは、全て新API で扱えそうな感じです。

### SwitchBot の新バージョンAPI v1.1 に関する公式情報の詳細
さらに、新API の公式情報を見てみます。

#### APIトークンを取得
API を利用するためのトークンが必要で、それは SwitchBot のアプリで取得する形です。以下に記載があります。
![トークンの取得](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/bf38742e-c716-0787-e72a-f29c58b7c5a6.png)
スマホの公式アプリでログインした状態まで進め、そこから、アプリ右下の「プロフィール」を押し、「設定」を選んでから出てくるメニュー内の「アプリバージョンを 10回タップ」という操作を行います。

この操作を行うと、以下の画面がアプリ上で見られるようになります。
![トークンが表示された画面](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/dd733243-e513-34b8-01ed-86d103bf99b2.png)

### API v1.1 の使い方を見ていく
新バージョンAPI の使い方を見ていきます。

こちらは、「Authentication」の項目。

https://github.com/OpenWonderLabs/SwitchBotAPI#authentication
![authentication](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/b6b1a82f-09df-a7dc-3aa1-2b1ccdfc729b.png)
![authenticationの続き](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/01862bf7-6a80-925f-83f5-9669e01dce56.png)

どうやら、新API では、トークンとシークレットキーを使って、ユニークなシグネチャ（署名）を生成する必要があるようです。

API v1.1 をプログラムから利用する際のサンプルのプログラムも掲載されていました。いくつかの言語の事例が書かれていますが、自分が使いそうな JavaScript のものを掲載してみます。

```javascript
const token = "yourToken";
const secret = "yourSecret";
const t = Date.now();
const nonce = "requestID";
const data = token + t + nonce;
const signTerm = crypto.createHmac('sha256', secret)
    .update(Buffer.from(data, 'utf-8'))
    .digest();
const sign = signTerm.toString("base64");
console.log(sign);

const body = JSON.stringify({
    "command": "turnOn",
    "parameter": "default",
    "commandType": "command"
});
const deviceId = "MAC";
const options = {
    hostname: 'api.switch-bot.com',
    port: 443,
    path: `/v1.1/devices/${deviceId}/commands`,
    method: 'POST',
    headers: {
        "Authorization": token,
        "sign": sign,
        "nonce": nonce,
        "t": t,
        'Content-Type': 'application/json',
        'Content-Length': body.length,
    },
};

const req = https.request(options, res => {
    console.log(`statusCode: ${res.statusCode}`);
    res.on('data', d => {
        process.stdout.write(d);
    });
});

req.on('error', error => {
    console.error(error);
});

req.write(body);
req.end();
```

このサンプルは、HTTPリクエストの POSTメソッドを使う形のようです。

また、API Usage の部分を見ると、API v1.1 を使う際に指定すべき URL や利用可能なメソッド（GET・PUT・POST・DELETE）や、コンテンツタイプ・リクエストを送信可能な制限（1日に 1万回）などの記載があります。

https://github.com/OpenWonderLabs/SwitchBotAPI#api-usage
![api-usage](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/cbc323d6-f5df-8fbf-ef89-42a44cc8a88c.png)
![api-usageの続き](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/e2cf0bbb-899b-5fb2-4598-6ea0c7f13fc8.png)

最近、自分が買って専用アプリから触ってみた、スマート電球に関する記載もありました。

https://github.com/OpenWonderLabs/SwitchBotAPI#color-bulb
![color-bulb](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/0a51b6f5-f898-76f5-3f3e-f5ebfde731a3.png)

ちなみに、スマート電球をアプリから触ってみた時の様子は、こんな感じです。

https://twitter.com/youtoy/status/1603900072017956864

## 旧バージョンの API でまずは試すのが良いかも
上記の仕様を見ていて、もう少しシンプルに使える方法がないかなとも思いました。

以前、「旧バージョンの API の使い方をざっくり見てみた時は、使い方がもっとシンプルだった気がする」という記憶があり、旧バージョンの API の仕様もあらためて見てみました。それと合わせて、旧バージョンの API を使った話の記事も見てみたり。

そうすると、やはり旧バージョンは「新バージョンの API で必要だった、取得したトークンでシグネチャを生成をする」という手順がなくて良さそうです。

●SwitchBotAPI/README-v1.0.md at main · OpenWonderLabs/SwitchBotAPI · GitHub
　https://github.com/OpenWonderLabs/SwitchBotAPI/blob/main/README-v1.0.md

●SwitchBotのAPIを使ってみる。 | メモ帳兼日記帳なブログ
　https://memo-nikki.info/?p=1131
![SwitchBotのAPIを使ってみる。](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/50868/ab744eb9-9733-23b9-b1ef-75999559bc1d.png)

この後、自分がとりあえず使ってみるという時には、旧バージョンの API から試してみるのも良さそかなと思いました。