サブジェクトの命名

目次

サブジェクト階層の設計

サブジェクトの命名は、メッセージングシステムのAPIそのものです。適切に設計された階層は、開発者にとって直感的でありながら、効率的なルーティング、フィルタリング、アクセス制御を可能にします。


設計原則

原則理由
階層的任意のレベルでワイルドカードサブスクリプションを可能にする
予測可能開発者が調べることなくサブジェクトを組み立てられる
環境を意識本番環境とステージング/開発環境を分離する
フィルタリング可能1台の機体、グループ、またはフリート全体をサブスクライブできる
拡張可能構造を変更せずに新しいメッセージタイプを追加できる

コアとなるサブジェクトパターン

すべてのフリートサブジェクトは次のパターンに従います:

fleet.<env>.veh.<vid>.<category>.<type>
セグメント説明例
fleetルート名前空間常に「fleet」
<env>環境prod、staging、dev
vehリソースタイプ機体(将来: 地上管制用のgcs)
<vid>機体IDVID-001、drone-alpha-7
<category>メッセージカテゴリstate、evt、cmd、cmdack
<type>具体的なタイプposition、battery、takeoff

メッセージカテゴリ

状態: fleet.<env>.veh.<vid>.state.*

機体の現在の状態。継続的にパブリッシュされます:

サブジェクト説明レート
state.position緯度/経度/高度、速度10 Hz
state.attitudeロール/ピッチ/ヨー10 Hz
state.battery電圧、電流、残量1 Hz
state.modeフライトモード(AUTO、MANUAL、RTL)変更時
state.healthシステムヘルスの概要1 Hz

パブリッシュの例:

subject := fmt.Sprintf("fleet.prod.veh.%s.state.position", vehicleID)
nc.Publish(subject, positionJSON)

イベント: fleet.<env>.veh.<vid>.evt.*

個別の出来事。発生時にパブリッシュされます:

サブジェクト説明
evt.armed機体がアームされた
evt.disarmed機体がディスアームされた
evt.takeoff離陸を開始した
evt.landed着陸が完了した
evt.waypointウェイポイントに到達した
evt.failsafeフェイルセーフが作動した
evt.geofenceジオフェンス違反
evt.battery.lowバッテリー残量低下の警告

イベントは状態遷移であり、継続的なデータではありません。イベントは永続化され、監査証跡としてJetStreamに保存されます。

コマンド: fleet.<env>.veh.<vid>.cmd.*

機体に送信される指示:

サブジェクト説明
cmd.armモーターをアームする
cmd.disarmモーターをディスアームする
cmd.takeoff離陸を開始する
cmd.land着陸を開始する
cmd.rtl離陸地点に帰還する
cmd.goto指定位置へ移動する
cmd.mission.uploadミッションをアップロードする
cmd.mission.startミッションを開始する
cmd.param.setパラメータを設定する

コマンドはダウンストリームに流れます。つまり、フリート管理から機体へと送られます。

コマンド確認応答: fleet.<env>.veh.<vid>.cmdack.*

コマンドへの応答:

サブジェクト説明
cmdack.armアームコマンドの結果
cmdack.takeoff離陸コマンドの結果
cmdack.gotoGotoコマンドの結果

Ackペイロードには以下が含まれます:

{
  "cmd_id": "cmd-123456",
  "status": "accepted|rejected|completed|failed",
  "error": "optional error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

ワイルドカードサブスクリプション

NATSのワイルドカードにより、柔軟なサブスクリプションが可能になります:

ワイルドカード意味例
*単一トークンfleet.prod.veh.*.state.position
>1つ以上のトークンfleet.prod.veh.VID-001.>

一般的なサブスクリプションパターン

パターンユースケース
fleet.prod.veh.*.state.positionすべての機体の位置
fleet.prod.veh.VID-001.>1台の機体からのすべてのメッセージ
fleet.prod.veh.*.evt.>すべての機体からのすべてのイベント
fleet.prod.veh.*.state.batteryすべてのバッテリー状態
fleet.*.veh.VID-001.>すべての環境にわたる1台の機体

KVストア: デジタルツインのシャドウ

JetStream KVストアは、**desired(期待)状態とreported(報告)**状態を保持します:

サブジェクトパターン(KV)

fleet/<env>/veh/<vid>/desired
fleet/<env>/veh/<vid>/reported

注: KVは/区切り(バケットパス)を使用し、pub/subは.区切りを使用します。

Desired状態

フリート管理システムが機体にさせたいこと:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "geofence_enabled": true,
  "max_altitude": 120,
  "home_position": {
    "lat": 37.7749,
    "lon": -122.4194
  }
}

Reported状態

機体が実際に報告する内容:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "mission_progress": 0.45,
  "geofence_enabled": true,
  "armed": true,
  "in_flight": true,
  "battery_remaining": 0.72
}

シャドウの調整

Vehicle Gatewayは継続的に以下を行います:

  1. KVからdesired状態を読み取る
  2. 実際の機体の状態と比較する
  3. 現実をdesired状態に合わせるためのコマンドを発行する
  4. reported状態を更新する

これにより宣言的なフリート管理が可能になります。desired状態を設定すれば、機体がその状態に収束します。


アクセス制御

NATSの認可は、ユーザーを許可されたサブジェクトにマッピングします:

# Vehicle can publish its own state/events
publish: fleet.prod.veh.VID-001.state.>
publish: fleet.prod.veh.VID-001.evt.>
publish: fleet.prod.veh.VID-001.cmdack.>

# Vehicle can subscribe to commands for itself
subscribe: fleet.prod.veh.VID-001.cmd.>

# Vehicle can read/write its own shadow
kv: fleet/prod/veh/VID-001/*
# Fleet operator can subscribe to all state/events
subscribe: fleet.prod.veh.*.state.>
subscribe: fleet.prod.veh.*.evt.>
subscribe: fleet.prod.veh.*.cmdack.>

# Fleet operator can publish commands
publish: fleet.prod.veh.*.cmd.>

# Fleet operator can manage shadows
kv: fleet/prod/veh/*/desired

これにより、機体が他の機体になりすましたり、許可されていないコマンドをパブリッシュしたりできないことが保証されます。

サードパーティへのグラントや認証情報の管理を含む認可モデルの詳細については、認可とグラントを参照してください。


サブジェクト設計のトレードオフ

フラットなサブジェクトを使わない理由

vehicle-001-positionのようなフラットなサブジェクトは、以下をサポートしません:

  • ワイルドカードサブスクリプション
  • 階層的なアクセス制御
  • 論理的なグループ化

より深い階層を使わない理由

fleet.prod.region.us-west.site.warehouse-a.veh.VID-001.state.positionのようなサブジェクトには、次の問題があります:

  • プログラムで組み立てるのが難しい
  • ワイルドカードが複雑になる
  • 変更がシステム全体に波及する

4レベルの階層は、柔軟性とシンプルさのバランスを取っています。


メッセージフォーマット

すべてのメッセージは、一貫した構造を持つJSONを使用します:

{
  "vid": "VID-001",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "seq": 12345,
  "data": {
    // message-specific payload
  }
}
フィールド説明
vid機体ID(サブジェクトと重複するが、コンシューマーにとって有用)
timestampミリ秒精度のISO 8601
seq順序付けのための単調増加シーケンス番号
dataメッセージ固有のペイロード

まとめ

カテゴリサブジェクトパターン方向
状態fleet.<env>.veh.<vid>.state.<type>機体 → ハブ
イベントfleet.<env>.veh.<vid>.evt.<type>機体 → ハブ
コマンドfleet.<env>.veh.<vid>.cmd.<type>ハブ → 機体
Ackfleet.<env>.veh.<vid>.cmdack.<type>機体 → ハブ
Desiredfleet/<env>/veh/<vid>/desired (KV)ハブ → 機体
Reportedfleet/<env>/veh/<vid>/reported (KV)機体 → ハブ

次へ

ストリーム設定 →