連携サービスAPI¶
ここでは、 連携サービスのAPIの使い方について説明します。
Incoming Webhook API¶
Incoming Webhook を利用することで、各モジュールにメッセージを送信することができます。 プロジェクトごとに、複数のIncoming Webhook APIを作成することができ、 そのプロジェクトに属するモジュールにメッセージを送信することができます。
Incoming Webhook APIを設定するごと Token が発行され、このTokenを用いて、APIにアクセスします。 各Tokenごとに、 Secret を設定することができ、APIを安全に利用することができます。
連携サービスの作成¶
コントロールパネルから連携サービスの追加を行い、 Incoming Webhook を追加します。
Secretとして、以下では、 _secret_ を入力したとします。
作成したIncoming Webhookの連携サービス画面からTokenが確認できます。 これを以下では _token_ とします。
データの準備¶
送信対象のモジュールと、モジュールに送信するデータを決めます。 データの送信には、モジュールのIDです。コントロールパネルまたは管理APIから確認することができます。
モジュールのIDを <module id> 、送信するデータは
- チャンネル 0 に int32_t 型の 0という数値を送る
- チャンネル 1 に int32_t 型の 0という数値を送る
とします。
これを data.json というファイルに書いたことにします。
{
"type": "channels",
"module": "<module id>",
"payload": {
"channels": [
{
"channel": 0,
"type": "i",
"value": 0
},
{
"channel": 1,
"type": "i",
"value": 0
}
]
}
}
データ送信¶
最後に改行コードが入っているとうまく行かないので、ファイル末尾の改行コードを削除しておきます。
$ perl -pi -e 'chomp if eof' data.json
$ cat data.json # module id が module-name のモジュールに送る例
{"type":"channels","module":"module-name","payload":{"channels":[{"channel":0,"type":"i","value":10},{"channel":1,"type":"f","value":1.5}]}}%
リクエストボディをメッセージとして、 Secret をKeyとするHMAC-SHA1を計算します。
$ cat data.json | openssl dgst -sha1 -hmac "_secret_"
(stdin)= xxxxxx
上記の HMAC-SHA1 を X-Sakura-Signature ヘッダに入れて、POSTリクエストを送ります。
curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://api.sakura.io/incoming/v1/_token_'
{"status":"ok"}
Arduino の sakura.io スケッチ例のStandard を使ってシリアルモニタ経由で見た例が以下です。 受信できていることが確認できます。
API リファレンス¶
DataStore v2 API¶
DataStore v2 を利用することで、sakura.ioモジュールからのメッセージを保存することができます。 外部システムやWebブラウザから、DataStore v2 APIのエンドポイントに対して、HTTPSリクエストを送信することで、DataStore V2に保存されたメッセージを参照することができます。
使い方については、 APIの基本的な使い方 をご覧ください。