Incoming Webhook
[更新: 2023年06月29日]
1. サービスアダプタ作成
さくらのクラウドコントロールパネルより新規にIncoming Webhookサービスアダプタを作成します。 サービスアダプタの追加画面からIncoming Webhookに必要な情報を入力します。
名前 |
サービスアダプタを管理する名前を入力します。 |
プロジェクト |
サービスアダプタを接続するプロジェクトを選択します。 |
サービスアダプタ |
incoming webhookを選択します。 |
シークレット |
任意に文字列を設定します。Incoming WebhookのURLへ届いたメッセージをIoTクラウドコア側でメッセージの検証を行い、メッセージの改ざんなどを防止します。 |
各項目を入力し、「作成」ボタンをクリックするとサービスアダプタを作成できます。なお、入力した項目は後からでも変更ができます。
参考
双方向通信を行う Webアプリケーション実装例 にて、Incoming Webhookを用いた作例を参照できます。
2. メッセージの送信
Incoming Webhook用のURLにデータを送信することで、デバイス方向へメッセージを送信できます。 URLは暗号化プロトコル（HTTPS）のみ対応しています。
例としてdata.jsonというファイルを準備し、以下のjsonメッセージを記載します。
その際、 <device_id> は適宜書き換えます、 device_id はプロジェクトのSIM一覧画面から確認することができます。
{
"device_id":"<device_id>",
"type":"object",
"payload":[
{
"type":"int32",
"tag":"FF",
"value":15
},
{
"type":"float64",
"tag":"00",
"value":3.141592653589793
}
]
}
メッセージデータを送信する前に末尾の改行コードを削除します。
$ sed -i -z 's/\n//g' data.json
また、シークレットを設定している場合リクエストボディをメッセージとしてHMAC-SHA1を計算します。 <secret>は適宜書き換えます。
$ cat data.json | openssl dgst -sha1 -hmac "<secret>"
(stdin)= xxxxxx
上記のHMAC-SHA1を X-Sakura-Signature ヘッダに入れて、POSTリクエストを送ります。 <token>は適宜書き換えます。
正しく送信ができた場合、サービスアダプタはnotifyタイプのデータを応答します。
curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://incoming.sipf.iot.sakura.ad.jp/v0/<token>'
{"device_id":"<device_id>","type":"notify","id":"xxxxxxxxxxxxxxxx"}
シークレットに誤りあり送信が失敗した場合、サービスアダプタはerrorタイプのデータを応答します。
curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://incoming.sipf.iot.sakura.ad.jp/v0/<token>'
{"device_id":"<device_id>","type":"error","datetime":"<datetime>>","payload":{"error":"Invalid Signature","detail":"invalid signature"}}
参考
3. エラーレスポンスの一覧
Incoming Webhook に対してリクエストに誤りがあった場合、以下のようなエラーが返されます。
HTTP Status |
エラーの原因と対処法 |
400(Bad Request) |
正しいメッセージフォーマットでリクエストてください |
401(Unauthorized) |
正しいトークンを含めてアクセスしてください |
403(Forbidden) |
デバイスID がサービスアダプタと連携されていません |
404(Not Found) |
デバイス、もしくはデバイスに対するサービスアダプタが見つかりません |
405(MethodNotAllowed) |
POST 以外の HTTP Request は許可されておりません |
422(Unprocessable Entity) |
JSON の形式が間違っています。 |
429(Too Many Request) |
プラットフォームへのリクエストが多すぎます。 |
500(Internal Server Error) |
内部エラーです。時間をおいてリクエストしてください |