PythonでSwitchBot API v1.1を利用してデバイス一覧を取得する

この記事は、筆者のアイデアをもとにAI(Gemini)を活用して執筆しています。
内容は筆者が最終確認し、加筆・編集を行っています。

SwitchBot API v1.1を使用して、自分のアカウントに紐付いているデバイス一覧を取得する実装の備忘録です。
旧バージョン(v1.0)とは異なり、現在はHMAC-SHA256を用いた署名（sign）の生成が必須となっています。単純なトークンのみでは認証エラー（401 Unauthorized）が発生するため、その解決策をまとめました。
今回こちらの記事を参考にさせていただきました。

---

目次

1. 事前準備：認証情報の取得
2. 実行環境
3. 実装コード（署名生成とAPIリクエスト）
4. 実行結果の確認とレスポンス構造
5. 注意点とトラブルシューティング
6. 今後の展望

---

1. 事前準備：認証情報の取得

APIを利用するためには、SwitchBotアプリから「トークン」と「クライアントシークレット」を取得する必要があります。

1. SwitchBotアプリを開く
2. 右下の「プロフィール」タブ ＞ 「設定」を選択
3. 「開発者向けオプション」をタップ
   • ※表示されない場合は、アプリの「バージョン」項目（最下部付近）を10回連打してください。
4. 表示された「トークン」と「クライアントシークレット」をコピーして控えます。
   

2. 実行環境

• 言語: Python 3.12
• 使用ライブラリ: requests
  • 未インストールの場合は pip install requests で追加してください。

3. 実装コード

以下のコードは、リクエストのたびに現在のタイムスタンプ（t）とトークンを組み合わせ、シークレットキーでハッシュ化した署名（sign）を生成します。

import time
import hashlib
import hmac
import base64
import requests

# 1. アプリから取得した認証情報を設定
# ※公開時は必ずサンプル文字列に書き換えてください
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
SECRET_KEY = "YOUR_SECRET_KEY"

# 2. 署名（sign）の生成ロジック
# v1.1以降、署名がないリクエストは401 Unauthorizedとなります
nonce = "" # 任意の識別子（空でも動作可能）
t = str(int(time.time() * 1000))
string_to_sign = f"{ACCESS_TOKEN}{t}{nonce}"
string_to_sign = bytes(string_to_sign, 'utf-8')
secret = bytes(SECRET_KEY, 'utf-8')

sign = base64.b64encode(
    hmac.new(secret, msg=string_to_sign, digestmod=hashlib.sha256).digest()
)

# 3. HTTPヘッダーの構築
headers = {
    "Authorization": ACCESS_TOKEN,
    "sign": sign,
    "t": t,
    "nonce": nonce,
    "Content-Type": "application/json; charset=utf8"
}

# 4. デバイスリスト取得APIの実行
url = "[https://api.switch-bot.com/v1.1/devices](https://api.switch-bot.com/v1.1/devices)"
response = requests.get(url, headers=headers)

# 5. 結果の出力
if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

4. 実行結果の確認とレスポンス構造

APIの呼び出しに成功すると、以下のようなJSONデータが返ってきます。物理デバイス（プラグミニ等）と赤外線リモコン（エアコン等）が分かれて格納されています。

{
    "statusCode": 100,
    "body": {
        "deviceList": [
            {
                "deviceId": "XXXXXXXXXXXX",
                "deviceName": "プラグミニ",
                "deviceType": "Plug Mini (JP)",
                "enableCloudService": true,
                "hubDeviceId": "000000000000"
            },
            {
                "deviceId": "YYYYYYYYYYYY",
                "deviceName": "Switch botハブ2",
                "deviceType": "Hub 2",
                "enableCloudService": true,
                "hubDeviceId": "000000000000"
            }
        ],
        "infraredRemoteList": [
            {
                "deviceId": "02-XXXXXXXXXXXX-XXXXXXXX",
                "deviceName": "エアコン",
                "remoteType": "Air Conditioner",
                "hubDeviceId": "YYYYYYYYYYYY"
            }
        ]
    },
    "message": "success"
}

実際の起動した際は下記のようになりました。(ほぼほぼ見せられないので白塗りですが…)

※ deviceId は各機器を操作するコマンドを送る際に必要となります。

5. 注意点とトラブルシューティング

• 認証失敗 (401):
  • トークンだけでなく「クライアントシークレット」を正しく設定しているか確認してください。
  • PCの時刻が大幅にズレていると、タイムスタンプの不一致でエラーになる場合があります。
• セキュリティ:
  • deviceId や hubDeviceId は固有の識別子です。ブログ等に掲載する際は、必ず上記サンプルのようにマスク処理を行ってください。
• 拡張性:
  • 特定のデバイスを操作する場合は、エンドポイントを /v1.1/devices/{deviceId}/commands に変更して POST リクエストを送信します。

6. 今後の展望

今回はデバイス一覧の取得までを行いましたが、これで各デバイスの deviceId が特定できました。今後は、ハブ2に搭載されている温湿度計のデータと組み合わせて、以下のような自動化を実装予定です。

• 自動温度調整: 室温が一定温度を超えたら自動でエアコンを冷房稼働
• 電気代の最適化: 外部の電力APIや時間帯と連携したスマートなON/OFF制御

SwitchBot APIを活用することで、公式アプリの「シーン」機能よりもさらに柔軟な、自分専用のスマートホーム環境を構築していきたいと思います。

---

執筆の励みになりますので、ストック・いいね等いただけますと幸いです！

---