シェアサイクル ポート共有 MQTT接続仕様書

0.インターフェース全体像(最初に読む)

本インターフェースは、1種類のイベント(JSON)を一方向に流すだけの構成。

• 各事業者は「自社ポートの状態」を自社トピックへ publish する
• 各受信者は「全事業者のポートの状態」を subscribe で受け取る
• 送信と受信でデータ構造は完全に同一(§4の station.status_updated イベント1種類)。違いは「トピック」と「立場」だけ

送信と受信の対比

0.1 役割・目的と適用範囲(標準原本の定義)

本IFの目的は、標準原本(002-07-02 info.description)で次のとおり定義されている:

1.接続情報

• まずステージングで結合し、動作確認後に本番の資格情報を発行する
• ブローカーは Eclipse Mosquitto 2.x。トピック/ペイロードは標準準拠のため、将来のブローカー変更(AWS IoT Core等)があっても接続先・資格情報の変更のみでクライアント実装に影響しない

2.認証・認可

partner_id 採番(仮・要合意)

3.トピック設計(標準準拠)

jp/events/{source_partner_id}/stations/{station_id}/status

• source_partner_id: 発生源の事業者コード(§2の採番)
• station_id: 発生源事業者システムにおけるポートID(m_station.station_id)
• 例: jp/events/emobi/stations/1234/status

QoS・Retain 規約(本事業の取り決め。標準は未規定)

4.ペイロード(標準スキーマ準拠・JSON UTF-8)

{
  "event_id": "emobi-017f22e2-79b0-8cc3-98c4-dc0c0c07398f",
  "event_type": "station.status_updated",
  "source_partner_id": "emobi",
  "timestamp": "2026-08-10T10:30:00Z",
  "payload": {
    "station_id": "1234",
    "num_vehicles_available": 5,
    "num_docks_available": 10,
    "reason_code": "VEHICLE_RETURNED"
  }
}

4.1 event_type の種類(原本定義の日本語説明)

4.2 reason_code の種類

reason_code は任意項目で、台数が変化した理由を表します。台数の正は num_vehicles_available / num_docks_available であり、reason_code は分析用の付加情報です。

標準の値(原本定義の日本語説明)

本事業の拡張値(標準原本には無い。v1.5で追加)

なぜ拡張するか: 標準の4値では「台数が減った理由」のうちユーザーの貸出だけが表現できません(VEHICLE_RETURNED の対になる値が無い)。貸出を担うはずの ride.started は event_type に宣言があるだけで payload が未定義のため、実証の OD 分析や在庫変動の原因分析で貸出と再配置・回収を区別できません。国土交通省へは標準仕様への改善提案として申し送りますが、標準改訂を待たずに本事業では拡張値として先行運用します(標準は「準拠したうえでの拡張」を妨げません)。

4.3 event_id の採番規約(v1.4で追加)

{自社partner_id}-{UUID v8}
例: emobi-017f22e2-79b0-8cc3-98c4-dc0c0c07398f

5.受信(subscribe)側仕様

在庫イベントを受信・利用する側(gogoshare の在庫保持サーバー、および他事業者の在庫を参照する各社システム)の実装規約。

5.1 購読

5.2 初期同期(retained メッセージ)

• 接続・購読直後に、各ステーションの最新状態が retained メッセージとして即時に届く(§3の retain=true 規約による)。これが初期同期を兼ねる
• retained かライブ配信かは MQTT の retain フラグで判別できるが、両者を同一ロジックで処理してよい(ポート状態は「最新値が正」のステートであるため)
• 初期同期の完了検知が必要な場合は、購読応答(SUBACK)後の一定時間(目安1〜2秒)受信が途切れた時点を同期完了とみなす

5.3 重複排除・新旧判定

5.4 受信データの取り扱い

• 未知の event_type は無視する(前方互換。初版で処理必須なのは station.status_updated のみ)
• 未知のフィールドは無視する(スキーマ拡張に備える)
• 未知の reason_code は無視し、台数の値でそのまま状態を更新する。reason_code は分析用の付加情報であり、状態更新の条件にしてはならない(§4.2。将来値が追加されても在庫の同期が止まらないようにするため)
• JSON として解釈できない、または必須フィールドが欠落したメッセージは破棄してログに記録し、処理は継続する(1件の不正データで購読を止めない)
• 自社が publish したイベントも購読条件に合致すれば届く(エコーバック)。不要な場合は source_partner_id が自社のものを読み飛ばす

5.5 再接続・鮮度

• 自動再接続を必須とする(推奨: 5秒間隔)。clean session のため再接続後は再 subscribe が必要。再接続すれば retained により状態は自動回復する
• 本仕様は「状態変化時のみ送信」(§3)のため、受信が無いこと自体は異常ではない。ただし長時間(目安: 24時間)更新のないステーションは、表示上「最終更新時刻」を併記するなど鮮度が分かる形で扱うことを推奨
• ブローカー側の障害・メンテナンスによる切断があり得る前提で、切断中に UI 等へ表示する場合は「最終受信時刻時点の情報」であることを明示する

6.接続確認手順(mosquitto クライアント例)

# subscribe(発行された資格情報で置き換え)
mosquitto_sub -h gogo-cycle-mqtt-stg.fly.dev -p 8883 \
  --capath /etc/ssl/certs -u <username> -P <password> \
  -i emobi-stg-test -t 'jp/events/#' -v

# publish(在庫更新イベント)
mosquitto_pub -h gogo-cycle-mqtt-stg.fly.dev -p 8883 \
  --capath /etc/ssl/certs -u <username> -P <password> \
  -i emobi-stg-pub -q 1 -r \
  -t 'jp/events/emobi/stations/1234/status' \
  -m '{"event_id":"emobi-017f22e2-79b0-8cc3-98c4-dc0c0c073001","event_type":"station.status_updated","source_partner_id":"emobi","timestamp":"2026-08-10T10:30:00Z","payload":{"station_id":"1234","num_vehicles_available":5,"num_docks_available":10,"reason_code":"VEHICLE_RETURNED"}}'

7.運用

• 稼働監視: ブローカーは常時稼働(自動停止なし)。障害時の連絡先は別途共有
• 資格情報のローテーション: 漏えい時は即時再発行(接続断→新パスワードで再接続)
• メッセージ上限: 64KB / メッセージ(在庫イベントは通常1KB未満)
• 切断時の復旧: retain により再接続後すぐ最新状態を受信可能。publisher 側は QoS 1 + 自動再接続を推奨

8.今後(参考)

• gogoshare 側は本ブローカーを subscribe して在庫を保持し、アプリへは REST で配信する(在庫保持サーバー。8月後半〜)
• Lovedrive / Jテック の接続は準備が整い次第、同一仕様で資格情報を発行