2024年5月時点で最新のswitchBot APIをpythonで使う方法を紹介します。まずはswitchBot API1.1を使い機器リストを取得するところからすべてが始まります。APIを利用するには、Open Tokenが必要です。Open Tokenの生成は、アプリ操作が必要です。

まずApp StoreやGoogle Play StoreでSwitchBotアプリをインストールして、アカウントの登録やログインを済ませます。

Open Tokenの生成方法は以下です。

1. プロフィール > 設定に移動
2. アプリバージョンを10回タップ。開発者オプションが表示される
3. 開発者オプションをタップ
4. トークンを取得

これでトークン（Open Token）とクライアントシークレット（シークレットキー）が取得できます。

SwitchBot API v1.1
https://github.com/OpenWonderLabs/SwitchBotAPI

 

SwitchBot API v1.1では、APIを通じてプライベートデータにアクセスするために、トークンとクライアントシークレットを使用してユニークな署名を生成する必要があります。リクエストを行う際、認証トークンと署名が同時に検証されます。13桁のタイムスタンプを出力し、それをトークンと連結します。シークレットキーと前のステップで作成した文字列を使用して署名を生成します。署名を大文字に変換します。

必要な環境はPython 3.6以降で、インストールや仮想環境の準備など適宜に、requestsとpandasのパッケージも必要です。requestsとpandasのパッケージのインストール例です。Python の環境は適宜に適宜してください。

pip install requests pandas

以下サンプルコードです。SwitchBot APIを使用してデバイスリストを取得し、結果をDataFrameに変換して表示するスクリプトです。

api_tokenにトークン（Open Token）、secret_tokenにクライアントシークレット（シークレットキー）を入れてください。XXXXXXXで代入してあります。X部分にキーを入れます。カンマはそのまま残します。

 

switchbot_device_api_client.py

import requests
import time
import uuid
import hmac
import hashlib
import base64
import pandas as pd

def get_device_list(api_token, secret_token):
    url = "https://api.switch-bot.com/v1.1/devices"
    t = int(time.time() * 1000)
    nonce = str(uuid.uuid4())
    string_to_sign = f"{api_token}{t}{nonce}".encode('utf-8')
    secret_key = secret_token.encode('utf-8')
    signature = hmac.new(secret_key, string_to_sign, hashlib.sha256).digest()
    sign = base64.b64encode(signature).decode('utf-8').upper()

    headers = {
        "Authorization": api_token,
        "Content-Type": "application/json",
        "t": str(t),
        "nonce": nonce,
        "sign": sign
    }

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()
    else:
        return response.status_code, response.text

api_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
secret_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
devices = get_device_list(api_token, secret_token)

print(devices)

if isinstance(devices, dict) and 'body' in devices and 'deviceList' in devices['body']:
    data = devices['body']['deviceList']
    df = pd.DataFrame(data, columns=['deviceId', 'deviceName', 'deviceType', 'enableCloudService', 'hubDeviceId'])
    print(df.to_string(index=False))
else:
    print("Failed to retrieve the device list.")

コードの補足です。

import requests # HTTPリクエストを送信するためのライブラリ
import time # 時間関連の関数を提供するモジュール
import uuid # UUID（一意識別子）を生成するためのモジュール
import hmac # HMAC（ハッシュベースのメッセージ認証コード）を生成するためのモジュール
import hashlib # ハッシュ関数を提供するモジュール
import base64 # Base64エンコード/デコードを行うためのモジュール
import pandas as pd # データ操作と分析のためのライブラリ
です。

get_device_list(api_token, secret_token)関数は、SwitchBot APIとの通信を行います。SwitchBot APIへのセキュアなリクエストを行うためまずSwitchBotデバイス情報を取得するAPIエンドポイントのURLが指定されます。次に、リクエストのタイムスタンプとして現在の時刻をミリ秒単位で取得し、安全性を高めるためにランダムなUUID（ノンス）を生成します。これらをAPIトークンと組み合わせて、署名用の文字列を作成し、シークレットトークンを用いてこの文字列をHMAC-SHA256で署名します。最後に、この署名をBase64でエンコードし、大文字に変換してリクエストヘッダーに使用します。

次にSwitchBot APIへのHTTP GETリクエストを送信するための準備を行います。まず、リクエストに必要なヘッダーを設定します。これにはAPIトークン、コンテンツタイプ（JSON形式）、タイムスタンプ、一意の識別子（nonce）、そして署名が含まれます。これらの情報をヘッダーに設定することで、認証とデータ整合性の保証が行われます。次に、設定したヘッダーを使ってAPIのURLに対してGETリクエストを送信します。リクエストが成功（ステータスコード200）すると、APIはJSON形式でデータを返します。リクエストが失敗すると、ステータスコードとエラーメッセージが返されます。

実行するとdeviceId、deviceName、deviceType、enableCloudService、hubDeviceIdを出力してくれます。SwitchBot APIを使用すると、deviceIdを利用して各デバイスを直接操作し、オン/オフ切り替えや設定の変更などのコマンドが実行できます。さらに自動化ルールを作成し、他のシステムとの統合も可能でしょう。Pythonを用いてこれらの操作を行うことで、効率的かつ柔軟なスマートホーム環境を構築できます。

APIのリクエストは1日あたり10,000回まで、超えると認証エラーが発生します。特定のデバイスはCloud Servicesを有効にする必要があるほか、一部のデバイスはハブを介してのみ操作が可能です。

SwitchBot API v1.1
https://github.com/OpenWonderLabs/SwitchBotAPI