プラットフォームドキュメント

/

データプッシュ

データプッシュは、NEQTO.aiからMQTTまたはWebSocketのデバイスエンドポイントに、必要なときにペイロードを送信します。1回限りの送信や送信履歴の確認には、データプッシュの画面を使います。よく使うコマンドには、ダッシュボードにデータプッシュのウィジェットを追加してください。

アラートの発生をきっかけに送信する場合:データプッシュは、ユーザー自身が手動で行う送信を対象としています。アラートが発生した際にペイロードを自動で送信するには、アラートに送信先を設定します。設定内容はアクションページで確認してください。どちらの送信方法も、アカウント全体で共通の送信枠を消費します。
対応しているエンドポイント:データプッシュは、MQTTとWebSocketエンドポイントで利用できます。HTTP/HTTPSエンドポイントはプッシュを受信できないため、データプッシュは利用できません。なお、WebSocketエンドポイントへプッシュを送信する際は、送信時に少なくとも1つのアクティブな接続が確立されている必要があります。
権限:データプッシュの画面の表示および送信を実行するには、「デバイスエンドポイントを編集」の権限が必要です。送信先リストや履歴の読み込みを行うには、「デバイスエンドポイントを表示」の権限も必要です。データプッシュのウィジェットの新規作成や編集には、それぞれ「ウィジェットを作成」または「ウィジェットを編集」の権限が必要です。ロールに必要な権限が付与されていない場合、操作ボタンやメニューが非表示になったり、リクエストが失敗したりすることがあります。ダッシュボードでは、ロールで送信できない場合、データプッシュのウィジェットは表示されますが無効になります。ポインターを合わせると理由が表示されます。
プラン制限:データプッシュには、アカウントの月間の送信枠および1分あたりの送信レート制限が適用されます。検証とプラン制限チェックを通過したすべてのペイロードは、実際に配信が試行される前に送信回数としてカウントされます。そのため、その後に失敗のステータスになった場合でも、送信実績としてカウントされます。複数のコマンドが登録されたボタンのウィジェットでは、各コマンドが個別のプッシュとして送信されます。
アラートがきっかけとなるプッシュはアクションです。このページでは、ユーザーが手動で送信するプッシュ(データプッシュの画面またはダッシュボードのウィジェットから)について説明します。アラートに設定したペイロード送信は、代わりに送信アクションになります。新しい送信先は、アクション画面で承認され有効化されてから送信を始めます。未承認のまま稼働中の状態にある旧来の送信先は、承認なしで送信を続けます。その画面では、アクションをドライランして何が送られるかを確認したり、アラートの発生を待たずに実際のペイロードを1つテスト送信したりすることもできます。このページのプッシュとは2つの点が異なります。アクションのペイロードはJSONまたはテキストとして送られ、16進数の数字からバイナリと判定されることはありません。また、その結果は、下の履歴の保留中、成功、失敗のステータスではなく、「キュー登録済み」、「失敗」、「スキップ(送信先が対象外)」として記録されます。

対応しているデータ

ペイロードはテキストとして入力します。NEQTO.aiが、テキスト、JSON、バイナリのどのデータとして送るかを判定します。入力の上限4,096文字には、整形用のスペース、改行、バイナリの区切り文字も含まれます。

形式 NEQTO.aiの判定と送信の方法 入力の上限
テキスト JSONにもバイナリにも該当しない入力すべて。送信前に、前後の空白が取り除かれます。 4,096文字
JSON 最初の文字が{または[の、有効なJSONのオブジェクトまたは配列。NEQTO.aiは値を解析し、送信前に整形用の空白を取り除きます。 圧縮前の入力で4,096文字
バイナリ 偶数桁の16進文字列(空文字は不可)。値をバイトに変換するとき、途中のスペースとハイフンは無視されます。 スペースやハイフンなしで16進数を4,096桁入力した場合に2,048バイト
形式の判定の詳細:
  • 入力が空白で始まるか空白で終わる場合、NEQTO.aiはその空白を取り除き、残りの値をテキストとして送ります。その後でJSONやバイナリとして解釈し直すことはありません。
  • 1234のような、16進数のみで構成される偶数桁の値をテキストとして送るには、末尾にスペースを1つ加えます。このスペースによってテキストと判定され、スペースは送信前に取り除かれます。
  • "ready"、true、12のような最上位のJSONのプリミティブ値は、JSONとは判定されません。テキストとして扱われるか、値が偶数の長さの16進数の並びであればバイナリとして扱われます。
WebSocketのプロトコルとの互換性:JSONプロトコルのWebSocket接続は、テキスト、JSON、バイナリのフレームを受信できます。ArubaOS 8またはArubaOS 10のprotobufプロトコルを使うWebSocket接続は、バイナリのペイロードだけを受け付けます。テキストとJSONのペイロードはそれらのクライアントには送られないため、ペイロードは16進数のデータとして入力してください。

データプッシュの画面から送信する

この画面は、デバイス → デバイスエンドポイントの一覧で、エンドポイントの「操作」列の3点メニューから開きます。1つのダイアログに、ペイロードの欄、送信の操作、そのエンドポイントの送信履歴がまとまっています。

データプッシュの画面を開く

  • 1
    デバイス → デバイスエンドポイントを開きます。対象のエンドポイントを見つけ、「操作」列の3点メニューを開いてデータプッシュを選択します。
    デバイスエンドポイントの一覧で、WebSocket(WSS)のエンドポイントPlant WSの「操作」列の3点メニューを開いたところ。メニューには詳細を表示、データプッシュ、削除、編集があり、3点ボタンとデータプッシュが赤枠で強調されています。一覧にはPlant MQTT(MQTT)とPlant HTTP(HTTPS)も並んでいます。
    対象のエンドポイントの「操作」列の3点メニューから、データプッシュを開きます。
  • 2
    送信先デバイスエンドポイントを確認します。ペイロードの欄には、0 / 4096のような文字数カウンターが表示されます。
    WebSocketのエンドポイントPlant WSに対するデータプッシュのダイアログ。送信先デバイスエンドポイントの欄、文字列・JSON・16進数表記のバイナリデータを入力するよう示すプレースホルダーのある空のペイロード欄、0 / 4096のカウンター、送信履歴とヘルプのボタン、キャンセルと送信のボタンがあります。
    ペイロードを入力する前に、エンドポイントを確認します。
MQTTの送信先:MQTTのエンドポイントでは、ペイロードがパブリッシュされる読み取り専用の制御用トピックもダイアログに表示されます。データプッシュのウィジェットも、同じエンドポイントの制御用トピックを使います。画面からトピックを変更することはできません。
MQTTのエンドポイントPlant MQTTに対するデータプッシュのダイアログ。送信先デバイスエンドポイントの欄とペイロードの欄の間に、ctrl/v1/で始まる制御用トピックを示す送信先トピックの欄があります。
MQTTの送信先トピックは、送信する前に表示されます。

ペイロードを入力して送信する

ペイロードを入力し、送信をクリックします。成功のトーストは、NEQTO.aiがリクエストを受け付けたことを意味します。送信は非同期で行われるため、トーストはデバイス側の受信確認ではありません。処理のステータス(保留中、成功、失敗)は、送信履歴で確認してください。

ペイロードの欄にSet cooler setpoint to 3.5 Cというテキストがあるデータプッシュのダイアログ。カウンターは28 / 4096で、ペイロードの欄と送信ボタンが赤枠で強調され、データが送信されたことを示す成功のトーストが表示されています。
成功のトーストは、プッシュのリクエストが受け付けられたことを示します。

JSONとバイナリの例

JSONでは、読みやすくするために、オブジェクトや配列の中にスペースや改行を入れられます。NEQTO.aiは、解析した値を圧縮した形で送ります。

temperature、humidity、modeのフィールドを持つ複数行のJSONオブジェクトが入ったデータプッシュのダイアログ。カウンターは59 / 4096で、データが送信されたことを示す成功のトーストが表示されています。
有効なJSONオブジェクトは、送信前に圧縮されます。

バイナリのデータは、16進数のバイトの組として入力します。たとえば、010300000002C40Bは8バイトです。大文字と小文字は区別されません。バイトの組の間にスペースやハイフンを入れてもかまいませんが、最初の数字の前と最後の数字の後には空白を入れないでください。

16進数のバイナリのペイロード010300000002C40Bが入ったデータプッシュのダイアログ。カウンターは16 / 4096で、データが送信されたことを示す成功のトーストが表示されています。
バイナリのデータは、偶数桁の16進数として入力します。

送信履歴を確認して再利用する

履歴には、データプッシュの画面とダッシュボードのウィジェットから、このエンドポイントに送ったプッシュが含まれます。履歴は、アカウントのプランに応じて保持されます。

  • 1
    ダイアログのタイトルの横にある送信履歴ボタンをクリックします。
    データプッシュのダイアログの上部、タイトルの右にある送信履歴ボタンが赤枠で強調されています。その横にヘルプボタンがあります。
    送信履歴ボタンから、これまでの送信の一覧を開きます。
  • 2
    新しいものから順に並んだ履歴を確認します。各行には、TEXT、JSON、BINのいずれかのバッジ、ローカルのタイムゾーンでの送信日時、保留中、成功、失敗のいずれかのステータスが表示されます。理由がある場合は、ステータスにポインターを合わせると表示されます。
    ペイロード、送信日時、ステータスの列があるデータプッシュの送信履歴の表が赤枠で強調されています。行にはBIN、JSON、TEXTのバッジと、日本時間の送信日時、成功のステータスがあります。下部のページ送りには1 / 15ページと表示されています。
    履歴には、各プッシュの形式と処理結果が表示されます。
ステータスの見方:「保留中」は、プッシュがキューにあるか、実行中か、再試行を待っていることを意味します。「成功」は、プラットフォームが送信の処理を完了したことを意味し、デバイス側のアプリケーションがペイロードを受信確認したり、それに応じて動作したりしたことを意味するものではありません。「失敗」は、プラットフォームが送信を完了できなかったことを意味します。アクティブな接続がないWebSocketへのプッシュは、すぐに失敗になります。

履歴の表示では、次のことができます。

  • ペイロードの入力に戻る:ダイアログの上部にある戻るボタンをクリックします。
    データプッシュの送信履歴の表示で、タイトルの右にある戻る矢印のボタンが赤枠で強調されています。
    ダイアログを閉じずに、ペイロードの欄に戻ります。
  • 履歴を移動する:1ページには最大10件が表示されます。前へまたは次へを使うか、ページの表示を選択して特定のページに移動します。
    データプッシュの送信履歴で、表の下にある1 / 15ページの表示が赤枠で強調されています。右側には前へ、1から5と15のページ番号、次へのボタンがあります。
    ページ切り替えで、過去の送信履歴をさかのぼって確認できます。
  • ペイロードを再利用する:履歴の表でそのペイロードを選択します。NEQTO.aiは入力の表示に戻り、ペイロードの欄に値を入れます。JSONは読みやすく整形され、バイナリのデータは16進数の数字として復元されます。
    データプッシュの送信履歴で、Set cooler setpoint to 3…で始まるTEXTの行のペイロードが、再利用のために赤枠で強調されています。
    ペイロードを選択して再利用します。
    再利用したテキストSet cooler setpoint to 3.5 Cがペイロードの欄に入り、カウンターは29 / 4096になっています。
    選んだ値を確認して、そのまま再送信できます。
    再利用したテキストは1文字多く表示されることがあります:NEQTO.aiはテキストの復元時に末尾へ半角スペースを付加し、16進数のように見えるテキストが誤ってバイナリと再判定されるのを防ぎます。このスペースは送信時に取り除かれるため、送信されるテキストは変わりません。

ウィジェットから送信する

データプッシュのウィジェットは、繰り返し使えるコントロールをダッシュボードに配置します。ペイロードを送信するフォームまたはボタンか、値を送信して最後に送信した値を表示するトグル、スライダー、ラジオボタン、チェックボックスのコントロールです。

データプッシュのウィジェットを作成する

  • 1
    ダッシュボードを開き、ツールバーのウィジェットを作成(+)をクリックします。
    Office Climateのダッシュボードのツールバーで、ウィジェットを作成のプラスボタンが赤枠で強調され、ウィジェットを作成のツールチップが表示されています。ダッシュボードはまだ空です。
    ダッシュボードのウィジェットを作成ボタンから始めます。
    ウィジェットを作成のダイアログ。上部にAtolla入力欄があり、Office Climateに固定されたダッシュボードの欄、ダッシュボードの作成のリンク、Fan speedが入ったウィジェットのタイトル、任意の説明の欄、ウィジェットの種類のメニュー、プレビュー(サンプル)のパネルがあります。
    種類を選ぶ前に、ウィジェットの共通の設定を入力します。
  • 2
    ウィジェットの種類でデータプッシュを選択します。メニューには、チャート、シングルステータス、マルチステータス、XYチャート、デバイスリスト、アラートリストもあります。
    ウィジェットを作成のダイアログでウィジェットの種類のメニューが開き、チャート、シングルステータス、マルチステータス、データプッシュ、XYチャート、デバイスリスト、アラートリストが並んでいます。データプッシュは赤枠で強調されています。
    ウィジェットの種類としてデータプッシュを選択します。
  • 3
    スタイルでコントロールを選択します。
    • フォーム:ウィジェットを使う人が送信のたびに編集できるテキストの欄です。
    • ボタン:保存した最大4つのコマンドを送信する1つのボタンです。
    • トグル:リレーやポンプなどに使うオン/オフのスイッチです。
    • スライダー:調光のレベルや設定値など、範囲内の数値です。
    • ラジオボタン:運転モードなど、選択肢から1つを選びます。
    • チェックボックス:一覧から任意の数の選択肢を選びます。
    データプッシュのウィジェットのスタイルのメニューが開き、フォーム、ボタン、トグル、スライダー、ラジオボタン、チェックボックスの6つが並び、フォームが選択されています。右のプレビューには、空のペイロードの欄と送信ボタンのあるフォームのスタイルのウィジェットが表示されています。
    ユーザーがコマンドを送信する方法を、フォーム、ボタン、各種コントロール(トグル、スライダーなど)から選択します。
  • 4
    送信先のデバイスエンドポイントを選択します。MQTTとWebSocketのエンドポイントを選べます。HTTPSのエンドポイントは非対応として表示され、選べません。
    送信先デバイスエンドポイントのメニュー。Plant WS、Plant MQTT、Cold Storage Gatewayは選択可能で、Plant HTTPはHTTPS非対応と表示されて選べません。
    MQTTまたはWebSocketの送信先を選択します。
  • 5
    選んだスタイルを設定します。フォームとボタンにはボタンラベルの設定が必要ですが、その他のコントロールでは不要です。
    • フォーム:必要に応じてデフォルトペイロードを入力します。これはダッシュボードの欄にあらかじめ入る値で、ウィジェットを使う人は送信のたびに編集できます。
    • ボタン:保存するコマンドのペイロードを入力します。ボタンには少なくとも1つのコマンドの枠があり、最大4つまで設定できます。+でコマンドを追加し、複数ある場合は削除ボタンで1つを削除します。
    • トグル:オンのときの値とオフのときの値を入力します(デフォルトはtrueとfalseで、2つは別の値にする必要があります)。トグルのスタイルとして、スイッチ、オン | オフ ボタン、オンの間点灯するプッシュボタンのいずれかを選びます。コントロールの横に表示する状態テキストとして、オン / オフ、開 / 閉、有効 / 無効、はい / いいえを選ぶか、カスタムを選んで自分で文言を入力します。
    • スライダー:最小値、最大値、刻み幅を入力します。最小値は最大値より小さく、刻み幅は0より大きくする必要があります。向きを横または縦から選び、必要に応じて数値の後ろに表示する%などの単位を入力します。
    • ラジオボタンとチェックボックス:選択肢で、選択肢ごとにユーザーに見える表示名と、送信される値を入力します。選択肢を追加で追加します。選択肢は2〜10個必要で、それぞれ別の値にする必要があります。

    トグル、スライダー、ラジオボタン、チェックボックスでは、ペイロードテンプレートも入力します。送信するコマンドで、コントロールの値が入る位置に{{value}}を書きます。ペイロードテンプレートを書くを参照してください。

    フォームのスタイルのデータプッシュのウィジェットの設定。送信先デバイスエンドポイントはPlant MQTT、ボタンラベルは送信で、デフォルトペイロードにはfan_speedを2にするJSONのペイロードが入っています。プレビューには、同じ編集可能なペイロードとその下の送信ボタンが表示されています。
    フォームのスタイルでは、任意のデフォルトペイロードを最初から入れておけます。
    ボタンのスタイルのデータプッシュのウィジェットの設定。スタイルはボタンで、送信先デバイスエンドポイントのPlant MQTTとボタンラベルの送信が入力され、バッチコマンドのコマンド1にJSONの再起動コマンドが入っています。プレビューには大きな送信ボタンが1つ表示されています。
    ボタンのスタイルでは、最大4つのコマンドのペイロードを保存できます。
  • 6
    保存をクリックします。ウィジェットがダッシュボードに追加されます。
    設定を終えたボタンのスタイルのデータプッシュのウィジェット。ダイアログの右下にある保存ボタンが赤枠で強調されています。
    設定したウィジェットを保存します。
    Office Climateのダッシュボードに保存された、ボタンのスタイルのRestartと、フォームのスタイルのFan speedの2つのデータプッシュのウィジェット。Fan speedにはデフォルトペイロードと送信ボタンが表示されています。
    保存したウィジェットは、ダッシュボードからすぐに使えます。
送信前に確認する:このオプションはデータプッシュのすべてのスタイルで使え、選択すると送信のたびに「このコマンドを送信しますか?」のダイアログが表示されます。送信をクリックすると送信されます。キャンセルでは何も送信されず、コントロールは元の状態に戻ります。このオプションは初期状態ではオフです。
エディターのプレビューからはデータは送信されません:プレビューのコントロールは保存後のウィジェットと同じ見た目と動作ですが、そのボタンをクリックしてもプッシュのリクエストは送られません。ボタンにポインターを合わせると、「プレビューのみ — データは送信されません」というヒントが表示されます。

ペイロードテンプレートを書く

トグル、スライダー、ラジオボタン、チェックボックスのウィジェットは、{{value}}をコントロールの値に置き換えたペイロードテンプレートを送信します。値は引用符を付けずに、そのまま挿入されます。

  • ONやecoなどのテキストは、書いたとおりに挿入されます。JSONでは、引用符を自分で付けてください:{"mode": "{{value}}"}。
  • 数値とtrue / falseは、引用符なしで挿入されます。{"relay": {{value}}}は{"relay": true}を送信します。
  • チェックボックスは、チェックしたすべての値の一覧を挿入します。たとえば["fan","pump"]、何もチェックしていなければ[]です。引用符で囲まないでください。

選択肢やオン/オフの値では、true、false、ただの数値はtrue/falseと数値のまま扱われ、それ以外はテキストになります。テンプレートの下のペイロードの例には、例の値を入れたコマンドが表示されます。テンプレートが有効なJSONでない場合は、{{value}}を囲む引用符を確認するようメッセージが表示されます。保存時にNEQTO.aiがコントロールの取り得るすべての値を用いてテンプレートを検証するため、引用符の付け忘れなどのミスは、ウィジェットが実際に使われる前に検出されます。

タグとデバイスの値:ペイロードテンプレートとボタンのコマンドには、{{tag.key}}と{{device.name.attribute}}も含められます。NEQTO.aiは、コマンドを送信するときに現在の値で置き換えます。JSONでは引用符の中に入れてください。値が見つからない場合は何も送信されず、見つからない項目を示すエラーが表示されます。フォームのテキストは入力したとおりに送信され、これらの値は置き換えられません。

保存したウィジェットから送信する

  • フォーム:ペイロードを確認または編集し、送信ボタンをクリックします。その時点の欄の値が1回送信されます。
  • ボタン:ボタンを1回クリックすると、設定したすべてのコマンドが表示されている順に1つずつ送信されます。途中でリクエストが1つ失敗すると、残りのコマンドは送信されません。
  • トグル:切り替えるか、オンまたはオフの側をクリックすると、対応する値が送信されます。
  • スライダー:目的のレベルまでドラッグします。ドラッグ中は数値が更新され、スライダーを離したときに値が1回送信されます。
  • ラジオボタン:選択肢を選ぶと、その値が送信されます。
  • チェックボックス:必要な選択肢をチェックしてから、適用をクリックします。チェックするだけでは何も送信されません。
確認は任意です:送信前に確認するを選択していない限り、保存したウィジェットは操作するとすぐに送信されます。リクエストやコマンドの送信が続いている間、コントロールは無効になります。ボタンのコマンドは、それぞれ別の履歴として記録されます。そのため、4つのコマンドを持つボタンは、1回クリックするだけで最大4回のプッシュを行うことがあります。

フォームは、プッシュのリクエストが受け付けられると成功のトーストを表示します。ボタンおよびその他のコントロールは、プラットフォームが送信を終えるまで数秒待つため、成功は送信が完了したことを意味します。それより時間がかかる場合は、デバイスからの応答をまだ待っていることを示す「送信中…」のメッセージが表示されます。特にエンドポイントの接続状況が変わった可能性があるときは、最終的な処理のステータスをエンドポイントのデータプッシュの履歴で確認してください。

フォームのスタイルとボタンのスタイルのデータプッシュのウィジェットがあるダッシュボード。Restartの送信ボタンを押したあとに、コマンドが送信されたことを示す成功のトーストが表示されています。
保存したフォームやボタンのウィジェットは、ダッシュボードから送信します。

最後に送信した値を確認する

トグル、スライダー、ラジオボタン、チェックボックスのウィジェットには、そのウィジェットから最後に送信した値が表示されます。ダッシュボードを開いた全員に同じ値が表示され、ページを再読み込みしても残ります。すでに開いているダッシュボードには、ほかの人が加えた変更が次に読み込んだときに表示されます。

  • 送信に失敗した場合、コントロールの表示は直前の値に戻り、エラーのメッセージが表示されます。ウィジェットからのコマンドは自動では再試行されません。
  • 数秒たってもデバイスが応答しない場合、コントロールは新しい値のままになります。その後送信に失敗した場合、デバイスの状態がわからないため、次にダッシュボードを読み込んだときにはコントロールに値が表示されません。
  • ウィジェットの設定が変わった場合、たとえば選択肢が削除されて、最後に送信した値が選択肢になくなった場合は、何も選択されていない状態になります。トグルはオンでもオフでもない状態になり、状態テキストにはダッシュが表示されます。
表示される値は最後に送信した値で、デバイスからの測定値ではありません。現地のスイッチやスケジュールなど、ほかの理由でデバイスの状態が変わっても、ウィジェットはそれに追従しません。デバイスが報告する内容を表示するには、シングルステータスまたはマルチステータスのウィジェットを使います。
送信の権限:どのデータプッシュのウィジェットから送信する場合も、「デバイスエンドポイントを編集」の権限が必要です。この権限がない場合、ウィジェットは表示されますが無効になり、ポインターを合わせると「コマンドを送信するには、「デバイスエンドポイントを編集」権限が必要です。」と表示されます。