HTTP API で計測値を送信する

JSON 本文付きの HTTP リクエストを送信できるシステムであれば、どれでも FreeMaint Connect にデータを送れます。Node-RED、Home Assistant、Modbus を読み取るゲートウェイ、PLC、独自のスクリプトなどです。種類が「HTTP API（Node-RED、スクリプト…）」の接続を作成すると、URL とアクセスキーが発行されます。

リクエスト

メソッド：POST。送信先は接続の作成時に表示される URL です（末尾は /connect/ingest/generic）。
ヘッダー Authorization: Bearer の後にアクセスキーを続けます。
ヘッダー Content-Type: application/json。
データが受け付けられると FreeMaint は 202 を返し、数秒以内に保存されます。

本文

本文では items の下にデバイスを列挙します。各デバイスには識別子（device）、任意の表示名、任意の時刻（ts、ISO 8601）、およびポイントがあります。各ポイントは key と value を持ち、できれば unit と quantity も指定します。作成画面には、そのままコピーできる完全な例が表示されます。

ポイントのフィールド

key

このデバイス上のチャネル名です（例：power、energy_total）。同じ key は常に同じチャネルに記録されます。

value

数値。

unit

例：W、kWh、°C、mm/s。Wh や MWh の電力量は kWh に、温度は °C に、振動速度は mm/s に換算されます。 Pa、hPa、kPa、mbar、psi、inH2O、inWC、mmH2O の圧力は bar に換算されます。チャネルを別の単位で読むには、FreeMaint で表示単位を選択してください。チャネルページの「受信した単位」に最新の値の単位が表示されます。ミリとメガは大文字・小文字で区別されます。mW と mWh はミリ、MW と MWh はメガです。 BACnet の単位名も大文字・小文字を問わず使えます：「PASCALS」、「inches-of-water」、「kilowatt-hours」など。

quantity

計測対象です（例：power、energy、temperature、vibration_velocity）。FreeMaint が適切な単位とグラフを選ぶために使います。

kind

増加のみするカウンター（電力量の累計、稼働時間）には CUMULATIVE を指定します。FreeMaint は読み取り値の間の消費量を計算します。単純な計測値の場合は省略してください。

制限

1 リクエストあたり最大 500 デバイス、5,000 ポイントまで。
1 接続あたり毎分最大 120 リクエストまで。超過すると FreeMaint は 429 を返すため、送信側はしばらくしてから再試行してください。
形式が正しくないリクエストには問題箇所を示す 400 レスポンスが返されるため、設定ミスのあるゲートウェイも簡単に修正できます。
新しいチャネルはそれぞれ、プランの有効チャネル数の上限に数えられます。

ヒント

代表的な構成例：Modbus 電力量計を毎分読み取って値を送信する Node-RED フロー、センサーの値を転送する Home Assistant のオートメーション、Data to Server 機能で読み取り値を送信する Teltonika ルーターなど。

警告

アクセスキーは秘密にしてください。キーを知っている人は誰でもこの接続にデータを送信できます。漏えいした可能性がある場合は、新しいキーを生成し、「今すぐ失効」を選択してください。