本文へジャンプします。

ニフクラ ユーザーガイド

クラウド トップ>ユーザーガイド>IoTデバイスハブ>Webhooks スマートモジュールを利用する

Webhooks スマートモジュールを利用する

このページではWebhook スマートモジュールを利用して、 イベントやコマンドと連携するアプリケーションを構築する方法を解説していきます。

事前準備

Webhooks スマートモジュールはHTTP形式でWebhook URLに対してリクエストを行なうので、リクエストを受けるためのWebアプリケーションを用意してください。

このページではWebhooks スマートモジュールのサンプルプロジェクトで動作確認を行っていきます。サーバーを用意してNode.jsをインストールしてください。

参考：パッケージマネージャーを利用したNode.jsのインストール（英語）

以下のリポジトリをgit clone （またはZipファイルのダウンロード）してください。

https://github.com/moderepo/sample-webhooks-handler

git cloneの場合
 $ git clone https://github.com/moderepo/sample-webhooks-handler.git
Zipファイルのダウンロードの場合
 $ wget https://github.com/moderepo/sample-webhooks-handler/archive/master.zip
 $ unzip master.zip

Webhooksスマートモジュールを作成する

IoTデバイスハブのコントロールパネルにアクセスし、左メニューからスマートモジュールを選択してください。
「＋新規」ボタンをクリックするとスマートモジュール一覧が表示されますので、Webhooks の「＋追加」ボタンをクリックしてください。

IoTデバイスハブのコントロールパネル

新規作成するスマートモジュールの設定画面が表示されますので以下の項目を入力してください。

  • モジュールID
  • 説明
  • Command Webhook
    • URL
    • キー
  • Event Webhook
    • URL
    • キー

Webhookの設定はコマンドとイベントで分かれており、処理を行なうWebhookのURLとキーを設定してください。キーはWebhookで来たリクエストの認証に利用するもので、「生成」ボタンをクリックして発行されたものを利用することも可能です。「保存」ボタンをクリックすると、スマートモジュールが作成されます。

新規Webhooksモジュール

Webhookをテストする

Webhook でイベントを受け取ることができるか確認していきます。

サーバーに戻り、サンプルプロジェクトのディレクトリにあるsample.jsを実行してください。${YOUR_ENDPOINT}と${YOUR_EVENT_KEY}には、スマートモジュール作成時に設定した Event Webhook のURLとキーを設定してください。

$ cd ${YOUR_PROJECT_DIRECTORY}
$ EVENT_URL=${YOUR_ENDPOINT} EVENT_KEY=${YOUR_EVENT_KEY} node sample.js

サンプルプロジェクトの起動が完了していれば、ブラウザでEvent WebhookのURLにアクセスすると「No device event.」と表示されます。 この状態で、特定のホームに所属しているデバイスのデバイスシミュレーターからイベントを送信すると、ブラウザ上で以下のようなイベントデータを確認することができます。

.{"homeId":50,"timestamp":"2016-09-12T11:19:55.308+09:00","eventType":"test","eventData":{"key":1},"originDeviceId":71,"originDeviceClass":"raspberry","originDeviceIp":"111.87.41.73"}

イベントやコマンドを処理する

デバイスからイベントデータが送信された場合、IoTデバイスハブはEvent WebhookのURLに対してPOSTリクエストを作成します。
POSTの内容はJSONフォーマットであり、`Content-Type` も `application/json` となります。
また、HTTPヘッダーの `X-Mode-Signature` フィールドにはリクエスト内容を検証するためのシグネチャがあるので、後述する方法でシグネチャを検証することができます。

POST リクエストの内容は以下のようになります。

POST /event_webhook HTTP/1.0
Content-Type: application/json
X-Mode-Signature: d3b07384d113edec49eaa6238ad5ff00

{
 "eventType":"abc",
 "eventData":{"key":"value"},
 "homeId":3,
 "timestamp":"2016-09-23T08:37:37.997281148Z",
 "originDeviceId":3
}

イベントデータは [event data](リンクはまだない) オブジェクトとして受け取ることができます。

Command Webhookは、IoTデバイスハブに対してアプリなどからコマンドが送信された場合にリクエストするWebhookを設定するものです。

コマンド送信リクエスト（PUTメソッド）は以下のような形式となります。

https://iot-device.jp-east-1.api.cloud.nifty.com/homes/HOME_ID/smartModules/MODULE_ID/command

HOME_IDには、リクエストしているプロジェクトに属しているホームのIDを指定し、MODULE_IDには作成したスマートモジュールのIDを指定します。

PUTのリクエスト内容として、actionとparametersフィールドを含むJSONオブジェクトを指定する必要があります。

参考：デバイスコマンドオブジェクト

Webhook のシグネチャを検証する

HTTPヘッダーの `X-Mode-Signature`にあるシグネチャをチェックすることで、IoTデバイスハブからWebhook URLへのリクエストかどうかを検証できます。シグネチャは、Webhook URLとリクエストBodyにSHA-256のハッシュ化アルゴリズムを適用して作成されます。

シグネチャの検証に必要な要素は以下の通りです。

  • Event / Command Webhook URL
  • Event / Command Webhook キー
  • リクエストBody

シグネチャを検証するためには、はじめにEvent / Command Webhook キーの使ってHMACを作成する必要があります。その後、Webhook URLとリクエストBodyを連携したものを組み合わせてSHA-256のダイジェストを作成し、16進数文字列としてエンコードしたものを比較します。

以下のサンプルコードは、Node.jsの[crypto]モジュールを利用してシグネチャを作成するプログラムです。

  • EventURL : https://www.example.com/command_webhook
  • Eventキー : 6idnnaidkdkdr5zq1838jGV
  • リクエストBody : {"homeId":4567,"timestamp":"2016-09-23T23:07:48.513902477Z","eventType":"counter","eventData":{"cnt":120},"originDeviceId":1234}
crypto = require("crypto");
var webhook_url = 'https://www.example.com/command_webhook';
var webhook_key = '6idnnaidkdkdr5zq1838jGV';
var body = '{"homeId":4567,"timestamp":"2016-09-23T23:07:48.513902477Z","eventType":"counter","eventData":{"cnt":120},"originDeviceId":1234}';

var hmac = crypto.createHmac('sha256', webhook_key);
hmac.update(webhook_url + body)
var generated_signature = hmac.digest('hex');

上記のサンプルを実行して得られるシグネチャは `cd722849acbb86776fa3a9bd8895649f7ba1ff89055c7018fb787906a2f337a3` となります。 HTTPヘッダーの `X-Mode-Signature` の値と上の手順で作成したシグネチャを比較し、一致しなかった場合はリクエストを拒否してください。

その他の設定

サブスクライブするイベントを指定する

スマートモジュールにて、Webhook URLをリクエストするためにサブスクライブするイベントのデータを指定することができます。
デフォルトではすべてのイベント（*）をサブスクライブしていますが、`motion-detected`と`home-status`イベントのみをサブスクライブする場合は、以下のように設定します。

motion-detected
home-status
複数のスマートモジュールを作成する

Webhooks スマートモジュールは、1つのプロジェクトで複数作成することができます。
それぞれサブスクライブしているイベントが発行されたタイミングでWebhook URLがリクエストされるので、デバッグなど異なる目的で複数のスマートモジュールを利用することが可能です。

IP制限を行う

IPアドレスを指定してWebhooks スマートモジュールからのアクセスのみを行う場合は、ファイアーウォールグループの設定で164.70.5.141 , 164.70.5.142を指定してください。

推奨画面サイズ　1024×768 以上

ページの先頭へ