Webhookによるデバイスステータス変化通知

概要

デバイスの接続状態(デバイスステータス)が変化したことをWebhookで通知する機能を提供します。Webhookとは、外部サービスにHTTPプロトコル(HTTPS含む)で通知を行う仕組みのことです。

Webhookの通知設定はコネクション毎に1つ設定できます。コネクションに含まれるデバイスの接続状態が変化した場合、通知先のURLにPOSTリクエストを送ります。1つの接続状態変化につき、1回のリクエストを送ります。

通知先でメール送信やSlackのメッセージ送信を行う機能を準備することで、運用中のデバイスが予期せずネットワークと切断された場合に、迅速に切断されたことを知れるようになります。

通知先は、たとえば以下を利用して準備できます。

  • enebularのHerokuデプロイ/Lambdaデプロイ機能
    enebularでデバイスの接続状態が変化したときに実行したい処理をNode-REDフローとして作成します。そのフローは、HTTPリクエストを契機として動作するようにします。作成したフローを、HerokuやLambdaにデプロイし、Webhookの通知先のURLとして設定することで、デバイスの接続状態が変化したときにそのフローが実行されるようになります。

  • IFTTT
    複数のソーシャルサービスやプラットフォームを連携して動作させるためのWebサービスです。トリガーと、トリガーが発生したときのアクションを指定できます。デバイスステータス変化通知機能を利用する場合は、トリガーとしてWeb Requestを指定することになります。

本機能は有償機能であり、エンタープライズおよびトライアルプランのプロジェクトでのみ利用できます。

使い方

  1. デバイスステータス変更通知を行いたいコネクションがあるプロジェクトを開きます
  2. 左側のメニューからDevicesをクリックします
  3. デバイスステータス変更通知を行いたいコネクションをクリックします
  4. Devices画面の右上部のSettingsをクリックします
  5. 表示されたサブメニューの中からWebhookをクリックします
  6. Webhooksダイアログが表示されたらAdd Webhookをクリックします(すでに通知設定が存在する場合、その設定が表示されます。内容を修正したい場合は、通知設定をクリックしてください)
  7. Create Webhookダイアログが表示されたら、Name、URL、Key Nameの各設定項目を入力します(設定項目の説明は以下にあります)
  8. Testをクリックすると入力したURLにダミーのデータを送信し、結果を表示します
  9. 結果が正常であれば、Saveボタンが表示されます(結果にエラーが返った場合、URLを見直すなどして再度Testをクリックしてください)
  10. SaveボタンをクリックするとWebhookの設定が保存されます

通知設定の項目

Webhookの通知設定の項目を以下に示します。

項目 説明
Name 通知設定に付ける名前です。
URL 通知先のURLです。
Key Name 通知先の制約で、通知のデータをJSONの1つのキーに割り当てる場合があります。この場合、この項目にキーの名前を指定します。たとえば、IFTTTの場合、value1〜value3のいずれかのキー名を指定する必要があります。

Webhookの通知先への送信

送信データ

通知設定で指定したURLに送信するデータについて説明します。通知設定のKey Nameの指定の有無により送信するデータが異なります。

Key Nameの指定がない場合

以下の情報をJSON形式で送信します。

  • projectName: プロジェクト名
  • connectionName: コネクション名
  • deviceName: デバイス名
  • trigger: トリガー(onConnect / onDisconnect)
    • onConnect: disconnectからconnectに変化した場合
    • onDisconnect: connectからdisconnectに変化した場合
  • ts: タイムスタンプ(UTCミリ秒)
  • deviceLogUrl: enebularのログ画面のURL

以下に例を示します。

{
  "projectName": "temperature-today",
  "connectionName": "aws-us-west",
  "deviceName": "thermo-sensor-a",
  "trigger": "onDisconnect",
  "ts": 1615277649908,
  "deviceLogUrl": "https://enebular.com/app/project/44be37d9-e847-4cd9-ab05-0e65b5196f2f/logs/8173f588-d48a-431a-9c34-be7aed03bf19/webhook-aws-999"
}

Key Nameの指定がある場合

上記のKey Nameの指定がない場合のデータに加え、Key Nameで指定したキー名にデータを割り当てます。

Key Nameで指定したキー名に割り当てるデータには以下の情報をHTML形式で追加します。

  • Project: プロジェクト名
  • Connection: コネクション名
  • Device Name: デバイス名
  • Trigger: トリガー(onConnect / onDisconnect)
  • Timestamp: タイムスタンプ
    • <日> <月> <年>, <時分> (<タイムゾーン>)の形式
    • タイムゾーンはUTC固定です
    • 例: 9th Mar 2021, 08:14 am (UTC)
  • Device Log URL: enebularのログ画面のURL

Key NameにanyKeyNameを指定した場合の例を以下に示します(anyKeyName以外はKey Nameの指定がない場合と同じです)。

{
  "projectName": "temperature-today",
  "connectionName": "aws-us-west",
  "deviceName": "thermo-sensor-a",
  "trigger": "onDisconnect",
  "ts": 1615277649908,
  "deviceLogUrl": "https://enebular.com/app/project/44be37d9-e847-4cd9-ab05-0e65b5196f2f/logs/8173f588-d48a-431a-9c34-be7aed03bf19/webhook-aws-999",
  "anyKeyName": "<b>Project:</b> temperature-today<br><b>Connection:</b> aws-us-west<br><b>Device Name:</b> thermo-sensor-a<br><b>Trigger:<b/> onDisconnect<br><b>Timestamp:</b> 9th Mar 2021, 08:14 am (UTC)<br><b>Device Log URL:</b> https://enebular.com/app/project/44be37d9-e847-4cd9-ab05-0e65b5196f2f/logs/8173f588-d48a-431a-9c34-be7aed03bf19/webhook-aws-999"
}

リクエスト形式

通知先へのリクエストの形式は以下です。

  • HTTP Method: POST
  • Content-Type: application/json

通知のリトライ処理

通知先へのリクエストに失敗した場合は、5秒後にリトライします。リトライは1回のみ実施します。

注意事項

  • 多くのデバイスの接続状態変化が同時に発生した場合、Webhookの実行に失敗することがあります(利用するサービスによって同時実行数に制約がありますので利用サービスの同時実行数の上限を確認してください)
  • 通知先のURLにリクエストを送信した結果、リダイレクトを指示する応答が返ってきた場合はエラーとして扱います

results matching ""

    No results matching ""