TRANXACT.AI ヘルプ

IoTメーター：デバイスの登録方法と読み取り値の署名方法

IoT デバイス: AMI または IoT エンドポイントを登録し、その秘密鍵 (一度だけ表示されます) をコピーし、新しい秘密鍵でローテーションし、デバイスが /api/public/utilities/iot/reads への各リクエストに署名する方法 (リクエストの例、制限、および取得できるすべての応答を含む)。

AMIまたはIoTメーターは、HTTPS経由でTRANXACTに自身の読み取り値を送信します。各デバイスには、サーバーによって生成されたキー（utd_に続く24文字の英数字）と秘密鍵があります。デバイスはすべてのリクエストで自身の身元を証明するため、他の誰もそのメーターの読み取り値を送信することはできません。

デバイスの登録

  1. CRMを開き、[ユーティリティ] › [ユーティリティメーターと読み取り値] › [IoTデバイス] を選択して、[新規] をクリックします。
  2. ラベルを入力し、読み取るメーターを選択し、署名方法として、hmac（各リクエストのHMAC-SHA256署名 - 推奨）、bearer（トークンとして送信される鍵と秘密鍵）、またはその両方を選択します。
  3. このデバイスの1分あたりの最大読み取り回数を設定してください。ファームウェアがわかっている場合は、ファームウェアも設定してください。
  4. 保存してください。回答には鍵と秘密鍵が表示されます。「秘密鍵は今すぐコピーしてください。二度と表示されません。」両方をデバイスの設定に入力してください。

秘密情報は一度だけ公開されます。その後は管理者にも表示されず、リストには最後の4文字（秘密情報の末尾）のみが表示されます。紛失した場合は、新しい秘密情報を発行してください。

秘密を回転させる

デバイスの行で「新しいシークレット」を押して確認します。新しいシークレットは一度表示され、古いシークレットはその瞬間から機能しなくなるため、すぐにデバイスに新しいシークレットを入力してください。デバイスを回転させずに停止するには「ステータス」を「無効」に設定し、使用停止にする場合は「廃止」に設定してください。

デバイスが読み取り値に署名する方法

  1. JSONボディを作成します。これは読み取り回数のリストで、各読み取り回数にはread_at（ISO 8601時間）と読み取り値が含まれます。バッテリー、信号、ファームウェア、アラームはオプションです。
  2. タイムスタンプとして、現在のUnix時刻（秒単位）を使用します。
  3. タイムスタンプ、ピリオド、および本文の正確なバイト列「<timestamp>.<body>」を用いて、デバイスシークレットの下でHMAC-SHA256を計算します。結果を64文字の小文字の16進数で書き出します。
  4. ヘッダー X-Utility-Device (キー)、X-Utility-Timestamp、および X-Utility-Signature (16 進数、オプションで sha256= をプレフィックスとして) を付けて、ボディを /api/public/utilities/iot/reads に POST します。
POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

同じ署名をシェル上で実行し、デバイスをインストールする前にテストしました。

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

送信するバイト列に正確に署名してください。署名後にJSONのフォーマットを変更したり、異なる改行コードで送信したりすると、バイト列が変更され、署名が一致しなくなります。

ベアラー（または両方）に設定されたデバイスは、代わりにAuthorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET>を送信し、署名ヘッダーは送信しない場合があります。HMACの方が安全な選択肢です。秘密鍵が送信されることはなく、傍受されたリクエストをリプレイすることはできません。

制限

  • タイムスタンプはサーバーの時計から5分以内である必要があります。デバイスの時計はNTPで設定してください。
  • 同じ署名付きリクエストが2回送信された場合、リプレイとして拒否されます。既にファイルに存在する読み取りは重複としてカウントされ、1回のみ保存されます。
  • 1回のリクエストにつき最大64KB、最大500回の読み取り、デバイス自身の1分あたりの最大読み取り回数、および1つのアドレスからの1分あたりの最大600回のリクエスト。
  • 装置は作動状態であり、メーターに接続されている必要があります。

デバイスが受け取る情報

答え意味
201 または 200 で、承認済み、重複、例外、拒否、アラーム、問題がありますリクエストは受け付けられました。各読み取りがカウントされ、問題にはインデックスによって無効と判断された読み取りが示されます。
401 デバイス認証不明または無効なキー、モードの間違い、または署名の不一致。デバイスの拒否回数が増加します。
401 stale_timestampタイムスタンプが5分以上ずれています。
409 リプレイこの署名済みの依頼書は既に受領済みです。
413 読みすぎ1回のリクエストで500回以上閲覧されました。
422 メーターなしこの装置はメーターに接続されていません。
429 レート制限送信速度が制限を超えています。しばらく待ってから再度送信してください。
400 bad_json本文はJSONではありません。
403 ユーティリティオフその会社への電気やガスなどの供給は停止された。

健康状態とアラーム

  • 各リクエストにより、デバイスの最終接続日時、バッテリー残量（％）、信号強度（dBm）が更新されます。バッテリー残量が15％を下回ると、バッテリー残量低下アラームが作動します。
  • デバイスが送信する可能性のあるアラームの種類：バッテリー残量低下、改ざん、漏水、逆流、流量停止、オフライン、その他。デバイスごとに、各種類のアラームが1つずつ発生します。
  • デバイスアラーム一覧が表示され、クリアするとメモ付きでアラームが閉じられます。漏洩が発生すると、自動的に優先度の高い漏洩調査サービスオーダーが生成されます。改ざんアラームや逆流アラームもサービスオーダーを生成します。
  • ダッシュボードのIoTメーター報告（24時間）の数値は、過去24時間で通信が行われたアクティブなデバイスの数をカウントします。