GeoSpatialService 業務ロジック仕様
本ドキュメントは、GeoSpatial機能の業務ロジック仕様を定義する。
10月デモ向けに制限した機能については「forDemo」を記載する。
OASの設計判断の根拠(データモデルとのマッピング、旧USS GeoServer APIのCQLフィルタとの対応)は
geospatial-api-design.mdにあり、本ドキュメントは処理フローを定義する。
API契約のSource of Truthはdocs/openapi/frontend/geospatial.yamlである。
2. 機能概要
Section titled “2. 機能概要”GeoSpatial機能は、地図上への重畳表示に必要な地理情報(飛行計画領域・空域制限・飛行軌跡・現在位置)を
GeoJSON(application/geo+json)で提供する機能である。
提供APIはfrontend/geospatial.yaml・frontend/geospatial-sse.yamlが定義しており、
現時点で処理フロー(5章)を記載しているのは次のAPIである(2.2参照)。
- 自組織の飛行計画領域検索
- POST /api/v1/geo/flight-plan-area/search
- 近傍の他Operatorの飛行計画領域検索
- POST /api/v1/geo/flight-plan-area/others/search
- 空域制限検索(制限分類ごとにエンドポイントが分かれるが、検索条件・応答スキーマは共通)
- POST /api/v1/geo/airspace-restriction/{airport|red-zone|yellow-zone|ordinance|manned-airport|emergency|other1|other2}/search
- 飛行軌跡取得
- GET /api/v1/geo/telemetry/{flightPlanId}
- 現在位置一覧検索
- POST /api/v1/geo/telemetry/position/search
- 現在位置のリアルタイム購読(SSE)
- GET /api/v1/geo/events/telemetry
2.1. ユースケースとの対応
Section titled “2.1. ユースケースとの対応”上流のユースケース定義はutm-design-docs/docs/usecase/flight-plan/flight-plan-usecase.mdにある。
1つのAPIが複数のユースケースから呼ばれるため、処理フロー(5章)はユースケース単位ではなくAPI単位に構成する
(ユースケース単位にすると同じ処理フローを複数箇所へ書くことになり、追随漏れの原因になる)。
| API | 呼び出し元のユースケース |
|---|---|
| 自組織の飛行計画領域検索 | UC-PLAN-06「付近の空域の状況を確認する」手順5(飛行計画の重畳表示のうち「自分のもの」)、UC-PLAN-01「飛行計画を作成する」・UC-PLAN-03「飛行計画を確認・更新する」(編集中の自計画の重畳表示) |
| 他Operatorの飛行計画領域検索 | UC-PLAN-01-9「他の飛行計画を確認する」、UC-PLAN-06 手順5(同「他社のもの」) |
| 空域制限検索 | UC-PLAN-01-7「飛行禁止エリアを確認する」(飛行計画の作成・更新中の重畳表示)、UC-PLAN-06 手順6(飛行禁止エリアの重畳表示) |
| 飛行軌跡取得 | UC-MON-03「飛行状況を監視する」手順3(飛行計画の経路/エリアと実際の飛行軌跡の重畳表示) |
| 現在位置一覧検索 | UC-MON-03 手順2・4(飛行中ドローンの現在位置の表示と更新。継続的なライブ追跡はリアルタイム購読(SSE)が担う) |
| 現在位置のリアルタイム購読 | UC-MON-03 手順2・4(同上のうち継続的なライブ追跡) |
UC-PLAN-06の補足「飛行計画の表示は、自分のもの、他社のものをON/OFFできる」がエンドポイントを
自組織向け・他Operator向けに分割している根拠であり、同「飛行計画の表示は、指定した時刻丁度だけでなく、
前後のものも含む」がcurrentTimeFrom/currentTimeTo(区間の重なり判定)を設けている根拠である。
2.2. 本ドキュメントの記載範囲
Section titled “2.2. 本ドキュメントの記載範囲”本ドキュメントはGeoSpatial機能全体の業務仕様であり、APIを実装した順に5章へ節を追加する (ドメインごとに1ファイルとし、API単位・ユースケース単位のファイル分割はしない)。 2章に挙げたAPIのほか、次のAPIは未実装のため5章に節を持たない。
- 空域制限(DID)のPMTilesアーカイブ取得
3. 用語定義
Section titled “3. 用語定義”飛行計画機能と共通の用語(UTM・DIPS・飛行計画・Operator等)は 飛行計画の業務ロジック仕様3章を参照する。 本ドキュメント固有の用語のみを次に示す(全体はgeospatial-api-design.md4章)。
| 用語 | 意味 |
|---|---|
| bbox | 検索範囲を表すバウンディングボックス(minLon,minLat,maxLon,maxLat、WGS84)。 |
| FeatureCollection / Feature | GeoJSON(RFC 7946)に準拠した地物集合/地物の表現。 |
| 自組織 / 他Operator | 自組織=自組織のOperatorがUTMに登録した飛行計画。他Operator=DIPSへ通報された自組織以外の飛行計画(他社UTM管理下のものと、自社UTM内の他組織のものの両方を含む。5.2の1-1参照)。 |
| dataType | 同一の飛行計画に対して返却する複数のFeatureが、元の形状(FLIGHT_PLAN)・バッファ適用後の形状(OPERATIONAL_INTENT)・上面下面の3D形状(TOP_BOTTOM_3D)のどれを表すかの区分。 |
| altitudeReference | FeatureのgeometryのZ値(高度)が準拠する高度基準(AGL=対地高度/WGS84=WGS84楕円体高)。 |
| 制限分類 | 空域制限の種別。ソースを横断して正規化した軸で、検索エンドポイントの切り分けキーになる(OASのAirspaceRestrictionType。飛行計画ドメインと共有する)。 |
| 天面 / 床面 | 3D形状の上面(ceiling)と下面(floor)。飛行計画領域はdataType=TOP_BOTTOM_3DのFeatureで両方を返し(coordinates[0]が上面、coordinates[1]が下面)、空域制限は天面のみを返す。 |
| currentTime | 「指定時刻時点で有効な」計画を取得するための検索条件。 |
| currentTimeFrom / currentTimeTo | 「指定期間内のいずれかの時点で有効な」計画を取得するための検索条件(区間の重なり判定)。currentTimeとは併用しない。 |
| 観測 | 機体が報告したテレメトリ1件(TELEMETRYの1行)。位置・速度・方位と観測時刻を持つ。 |
| 飛行軌跡 | 直近一定時間の観測を観測時刻順に並べた線(LineString)。監視用途であり、飛行終了後に全期間の記録を参照する飛行実績とは別物である。 |
| テレメトリの鮮度 | 動態として扱う観測の遡り幅。これより古い観測は返さない(5.4の1-1-2)。4.4が空域制限について述べる「取得日時(鮮度)」とは別の概念である。 |
4. forDemo制約事項
Section titled “4. forDemo制約事項”4.1. 認証未導入に伴う自組織の判定
Section titled “4.1. 認証未導入に伴う自組織の判定”forDemoでは認証(auth-service連携)を導入せず、Row Level Security(RLS)も入れていないため、
「自組織」はアプリ側の固定値(NoAuthActor.ORGANIZATION_ID)で判定する
(AuthenticationSpecification_Flightplanning_forDemo.md2節、docs/implementation-guide.md
「RLS / マルチテナント対応(拡張ポイント)」)。
geospatial-api-design.md6.1は、旧USSのis_managedフラグを
新APIではRLSによる透過的なフィルタで置き換えると記述しているが、RLSが入るまでは検索条件として
明示的に絞り込む。認証連携の実装後にRLSへ寄せる。
4.2. ページング・ソート機能の非対応
Section titled “4.2. ページング・ソート機能の非対応”ページング・ソートは提供しない。limitによる件数上限と、上限で切り詰めたことを示す
totalCount/truncatedのみを提供する(5.1の1-3)。返却順は規定しない。
4.3. 未通報の自組織計画はdipsFlightPlanIdで検索できない
Section titled “4.3. 未通報の自組織計画はdipsFlightPlanIdで検索できない”dipsFlightPlanIdはDIPSへの通報後にDIPS側で払い出される識別子であり、reportStatus=REPORTEDの
計画のみが値を持つ。通報義務の有無(reportRequired)は問わない(reportFlightPlanは通報義務が
ない計画の通報も受け付ける)。未通報の計画は本条件では検索できない。
4.4. 収集未実装に伴う空域制限データの直接投入
Section titled “4.4. 収集未実装に伴う空域制限データの直接投入”forDemoではDIPSからの空域制限の収集(UC-USP-03)を実装しない。アプリケーションが
AIRSPACE_RESTRICTIONの行を作る経路がないため、データはDBへ直接投入して用意する
(docs/data-model/airspace-er.mdの「スコープ」)。次の制約が生じる。
statusをDISAPPEAREDへ遷移させる主体がいないため、実データはACTIVEに限られる。status=DISAPPEAREDを指定した検索は常に0件になる(5.3の1-2-2)- 取得日時(鮮度)は提供しない。UC-PLAN-01-7は種別ごとに情報の鮮度を表示する補足を持つが、 同補足は10月デモ実装対象外(飛行禁止エリアを収集せず取得日時が存在しないため)であり、 OASにも対応するプロパティがない
- 手動登録(
sourceKind=MANUAL)の行は取得元の識別子を持たないため、externalIdが未設定になる
4.5. 表示用の値をIAM未導入のまま解決する
Section titled “4.5. 表示用の値をIAM未導入のまま解決する”本節が、業務仕様の中でテレメトリのoperatorId・operatorName・statusの解決を定める唯一の場所である。
5.4・5.5は本節を参照し、APIごとに違うところだけを書く。OASは契約として「解決できない機体では
未設定になる」ことだけを書き、条件は本節を正とする。
複写元の1つであるUSER.display_nameは、IAMドメインの実体がutm-backendに無いため解決できない
(他社の機体だけでなく自組織の機体でも解決できない)。代わりに機体ごとの既定値表
TELEMETRY_DISPLAY_DEFAULTを置き、取り込みが複写列へ書く。docs/data-model/telemetry-er.mdが正で、
表の役割は「表示用の値は機体ごとの既定値で埋める」、各列のNULL可否は「図1 カラム補足」にある。
本サービスは同表を読まない。 3項目ともTELEMETRY・CURRENT_TELEMETRYの複写列から返すため、
未設定かどうかは取り込みが何を書けたかで決まる。
| 項目 | 複写元 | 未設定になる場合 |
|---|---|---|
operatorName | 飛行計画の有無によらず既定値表 | 既定値表に行が無い |
operatorId | 飛行計画。解決できなければ既定値表 | 飛行計画を解決できず、かつ既定値表に行が無いか、行のoperator_idがNULL(USERの実体を持たない運航者) |
status | 飛行計画。解決できなければ既定値表 | 飛行計画を解決できず、かつ既定値表に行が無い(同表のstatusはNOT NULL) |
operatorNameが未設定のときはOperator name unavailableを入れて返し、ログに残す。識別子でも状態でも
なく表示のためのラベルで、実在の値と混同しないためである。他の2項目に代替値を作ると実在の値と
区別できなくなるため入れない。
残る2項目を未設定のまま返すか失敗にするかはAPIごとに決める。 飛行軌跡取得は表の条件が 原理的に起きないため、空なら取り込みの不具合として500にする(5.4の1-5)。現在位置一覧検索は 未設定のまま200で返す(5.5の1-2-3)。
既定値表は投入手段を持たず(db/seed/に該当のSQLがない)、動態を表示する機体の行は人手で用意する
前提である。また取り込みが同表から複写しているかは未確認で(別リポジトリtelemetry-service-proto。
docs/followups/telemetry.mdの307-03)、未実装なら行があっても3項目とも未設定で届く。
5. ユースケース毎の処理フロー
Section titled “5. ユースケース毎の処理フロー”5.1. 自組織の飛行計画領域検索(POST /api/v1/geo/flight-plan-area/search)
Section titled “5.1. 自組織の飛行計画領域検索(POST /api/v1/geo/flight-plan-area/search)”-
- 自組織の飛行計画領域検索
- 1-1. 検索条件
- 以下の内容をAND条件で絞り込んだ飛行計画を対象とする。
- 自組織のOperatorが登録した飛行計画であること(forDemoでは固定値で判定。4.1参照)
bboxが指定された場合、飛行領域FLIGHT_PLAN_AREA.plan_geometryが指定範囲と重なること(未指定の場合は条件なし)currentTimeが指定された場合、planned_start_at <= currentTime AND planned_end_at >= currentTimeであることcurrentTimeFrom/currentTimeToが指定された場合、planned_start_at <= currentTimeTo AND planned_end_at >= currentTimeFromであることstatusが指定された場合、FLIGHT_PLAN.statusが指定値のいずれかであること(未指定の場合は条件なし)flightPlanIdが指定された場合、FLIGHT_PLAN.idが一致することdipsFlightPlanIdが指定された場合、当該飛行計画のDIPS_REPORT.dips_receipt_noが一致すること (同一計画の通報履歴が複数行あってもdips_receipt_noは不変で同一値になる。db/schema/flight_planning.sqlの列コメント「計画内では不変で再通報でも同一値のため、単独UNIQUE制約は置かない」)
- 1-1-1. 空間条件の判定対象
bboxとの重なりはFLIGHT_PLAN_AREA.plan_geometryで判定する。geometryはarea_type=CIRCLEのとき 中心点のPointであり、「円の一部はbboxに重なるが中心は範囲外」の計画を取りこぼすためである (db/schema/flight_planning.sqlのidx_flight_plan_area_plan_geometryのコメント)。
- 1-1-2. 検索条件の必須要件
bbox・flightPlanId・dipsFlightPlanIdのうち少なくとも1つの指定を必須とする。 すべて省略した組織内全件検索は許可しない。
- 1-1-3.
DRAFTを指定した場合は常に0件になる- 一時保存中の飛行計画は飛行領域を正規化して保持せず(内容は
FLIGHT_PLAN_DRAFT.draft_fieldsの jsonbにまとまっている)、検索対象となるFLIGHT_PLAN_AREAの行が存在しないためである。 エラーとはしない。 DRAFT以外の値はいずれもFLIGHT_PLAN.statusに格納されうる。OASのFlightPlanStatusとflight_planning.flight_plan_status_typeはともに5値(DRAFT/ACCEPTED/ACTIVATED/CANCELLED/ENDED)で一致しており、値域の差による該当0件は生じない。
- 一時保存中の飛行計画は飛行領域を正規化して保持せず(内容は
- 以下の内容をAND条件で絞り込んだ飛行計画を対象とする。
- 1-2. 返却するFeatureへの展開
-
該当した飛行計画1件を、
dataTypeとaltitudeReferenceの組み合わせごとに1件のFeatureへ展開する。areaType=ROUTEは6件(dataType3種 ×altitudeReference2種)、POLYGON/CIRCLEは4件 (OPERATIONAL_INTENTが存在しないため2種 × 2種)となる。 -
1-2-1.
dataTypeと元の列の対応dataTypealtitudeReference=AGLの元の列altitudeReference=WGS84の元の列返却条件 FLIGHT_PLANplan_geometryplan_geometry_wgs84常に返却する OPERATIONAL_INTENToperational_intent_geometryoperational_intent_geometry_wgs84area_type=ROUTEの場合のみ(他は列がNULL)TOP_BOTTOM_3Dtop_bottom_3d_geometrytop_bottom_3d_geometry_wgs84常に返却する -
1-2-2. WGS84基準の形状の前提
*_wgs84列は登録・収集の時点で充填済みであることを前提とする。本APIは応答のたびに標高(DEM)・ ジオイド高を参照せず、実体化列をそのまま返す。充填処理は本APIの責務ではない (docs/data-model/followups.mdの「WGS84基準の形状(*_geometry_wgs84列)へ換算値を充填する処理」の行)。
-
1-2-3. Featureのプロパティ
- パラメータとデータベースカラムの項目単位の対応関係は geospatial-api-design.md5.1のマッピング表を参照。
reportExemptionReason(通報義務なしの根拠)はreportRequired=falseの場合のみ返す。FLIGHT_PLAN_DIPS_ATTRSは両列を縛るCHECK制約を持たず、通報要否がfalse→trueへ変わった 計画に古い根拠が残りうるため、OASの契約に合わせて応答側で落とす。- 空白のみの根拠は未設定として返す。同じくCHECK制約がなく保存されうるが、根拠として情報を 持たないためである。1件の不整合で該当した他の計画まで返せなくなることを避ける。
-
- 1-3. 件数の上限と切り詰めの通知
limit(既定1000・最大10000)は飛行計画の件数を数える。1件が複数のFeatureへ展開されるため、features配列の要素数はlimitを上回りうる。totalCountにはlimit適用前の該当件数を、truncatedにはtotalCountがlimitを超えたかどうかを設定する。
- 1-4. エラーケースに合わせてステータスコードを返却する。
- 400: リクエストボディのパース失敗(不正なJSON・型不一致など)
- 401: 未認証(forDemoでは認証を導入しないため発生しない。4.1参照)
- 422:
bboxが上限(幅50km・高さ50km・面積2500km²のいずれか)を超える、bboxの要素数が4でない、currentTimeとcurrentTimeFrom/currentTimeToの同時指定、currentTimeFrom/currentTimeToの 片方のみの指定、statusの要素にnullを含む、limitが1〜10000の範囲外、bbox・flightPlanId・dipsFlightPlanIdのすべてが未指定
5.2. 他Operatorの飛行計画領域検索(POST /api/v1/geo/flight-plan-area/others/search)
Section titled “5.2. 他Operatorの飛行計画領域検索(POST /api/v1/geo/flight-plan-area/others/search)”-
- 他Operatorの飛行計画領域検索
- 1-1. 取得対象
- DIPSから収集した飛行計画(
DIPS_FLIGHT_PLAN)のみを対象とする。自社UTM内の他組織の飛行計画も、 DIPSへ通報されたものはDIPS収集経路で本テーブルに格納されるため、取得元は本テーブル1つに閉じる。 DIPSへ通報されていない他組織の飛行計画は対象外である。 - 自組織がDIPSへ通報した飛行計画もDIPSからの収集結果に含まれうるため、
DIPS_FLIGHT_PLAN.dips_flight_plan_idが自組織のDIPS_REPORT.dips_receipt_noのいずれかと 一致する行は結果から除外する(自組織の計画が「他Operator」として二重に表示されることを防ぐ)。
- DIPSから収集した飛行計画(
- 1-2. 検索条件
- 5.1の1-1と同じ条件をAND結合で適用する。ただし次の差異がある。
statusによる絞り込みは行わない。DIPSの飛行計画参照APIは運航状態を返さず、UTM側で状態を 保持していないためである。指定されても無視し、エラーとはしない(ただし要素のnullは5.1の1-4と同じく422とする。値そのものを無視するという意味である)。flightPlanIdはDIPS_FLIGHT_PLAN.id(UTMが発行し、再収集のUPSERTでも同一値を保つID)と対応する。dipsFlightPlanIdはDIPS_FLIGHT_PLAN.dips_flight_plan_idと対応する。5.1の1-1と異なりDIPS_REPORTを経由しない。bboxとの重なりはDIPS_FLIGHT_PLAN.plan_geometryで判定する(理由は5.1の1-1-1と同じ)。
- 検索条件の必須要件は5.1の1-1-2と同じ。
- 5.1の1-1と同じ条件をAND結合で適用する。ただし次の差異がある。
- 1-3. 返却するFeatureへの展開
- 展開規則は5.1の1-2と同じだが、
DIPS_FLIGHT_PLANはarea_typeがCIRCLE/POLYGONの2値で (flight_planning.dips_flight_plan_area_type)、operational_intent_geometryに相当する列を 持たないため、dataType=OPERATIONAL_INTENTのFeatureは返却しない。1計画あたり常に4件となる。 - 公開するプロパティは
OtherFlightPlanAreaPropertiesに限る。createdBy・uasId等の内部IDと、 通報情報(reportRequired/reportStatus/reportExemptionReason)は含まない。 statusは設定しない(1-2参照)。
- 展開規則は5.1の1-2と同じだが、
- 1-4. 件数の上限と切り詰めの通知
- 5.1の1-3と同じ。
- 1-5. エラーケースに合わせてステータスコードを返却する。
- 5.1の1-4と同じ。
5.3. 空域制限検索(POST /api/v1/geo/airspace-restriction/{category}/search)
Section titled “5.3. 空域制限検索(POST /api/v1/geo/airspace-restriction/{category}/search)”-
- 空域制限検索
- 1-1. 対象エンドポイントと制限分類
-
制限分類(
AirspaceRestrictionType)ごとに独立したエンドポイントを持つ。検索条件・応答スキーマは 全分類で共通で、categoryはリクエストボディに含まない(エンドポイント自体が分類を表す)。 分類ごとに分ける根拠はgeospatial-api-design.md6.3節にある。categoryエンドポイント AIRPORT_VICINITYPOST /api/v1/geo/airspace-restriction/airport/searchSMALL_UAV_PROHIBITION_RED_ZONEPOST /api/v1/geo/airspace-restriction/red-zone/searchSMALL_UAV_PROHIBITION_YELLOW_ZONEPOST /api/v1/geo/airspace-restriction/yellow-zone/searchORDINANCE_DESIGNATED_AREAPOST /api/v1/geo/airspace-restriction/ordinance/searchMANNED_AIRCRAFT_TAKEOFF_LANDING_AREAPOST /api/v1/geo/airspace-restriction/manned-airport/searchEMERGENCY_OPERATIONS_AIRSPACEPOST /api/v1/geo/airspace-restriction/emergency/searchOTHER_1POST /api/v1/geo/airspace-restriction/other1/searchOTHER_2POST /api/v1/geo/airspace-restriction/other2/search -
1-1-1. 人口集中地区は検索エンドポイントを持たない
AirspaceRestrictionTypeは9値だが、DENSELY_INHABITED_DISTRICT(人口集中地区)は静的PMTiles アーカイブで配信するため検索の対象外である。AIRSPACE_RESTRICTIONに行も持たず、db/schema/airspace_restriction.sqlのck_airspace_restriction_no_didが登録自体を禁じている (docs/data-model/airspace-er.mdの決定事項D2)。
-
- 1-2. 検索条件
- 以下の内容をAND条件で絞り込んだ空域制限を対象とする。
AIRSPACE_RESTRICTION.categoryがエンドポイントに対応する値であること- 形状
AIRSPACE_RESTRICTION.geometryがbboxの範囲と重なること AIRSPACE_RESTRICTION.statusがstatusと一致すること(未指定の場合はACTIVE。1-2-2参照)validAtが指定された場合、valid_from <= validAt AND valid_to >= validAtであることvalidFrom/validToが指定された場合、valid_from <= validTo AND valid_to >= validFromであること
- 1-2-1.
bboxは必須である- 飛行計画領域検索(5.1の1-1-2)が
bbox・flightPlanId・dipsFlightPlanIdのいずれか1つ以上を 必須としているのに対し、本APIはbboxを単独で必須とする。ID指定で1件を引く検索経路を持たず、 用途が地図の表示範囲の重畳表示に限られるためである (UC-PLAN-01-7の補足「飛行禁止エリアの情報は、画面の表示の範囲をフィルターする」)。
- 飛行計画領域検索(5.1の1-1-2)が
- 1-2-2.
statusの既定値はACTIVEである- 未指定は「絞り込みなし」ではない。 省略時は
ACTIVEのみを対象とする(OASのdefault)。 地図表示では現存する制限のみを見るのが通常であるためで、status未指定を「全件」と解釈する 5.1の1-1のstatusとは扱いが異なる。取得元から消失した制限を見るにはDISAPPEAREDを明示指定する。 - forDemoでは
DISAPPEAREDの行は現れない(4.4参照)。
- 未指定は「絞り込みなし」ではない。 省略時は
- 1-2-3. 空間条件の判定対象
bboxとの重なりは接尾辞のないAIRSPACE_RESTRICTION.geometryで判定する。GiSTインデックス (idx_airspace_restriction_geometry)が張られているのも本列である。geometry_wgs84は 応答の組み立て専用で、検索条件には用いない。
- 以下の内容をAND条件で絞り込んだ空域制限を対象とする。
- 1-3. 返却するFeatureへの展開
-
該当した空域制限1件を、
altitudeReferenceごとに1件のFeatureへ展開する。 飛行計画領域のようなdataTypeによる分岐は持たない。 -
1-3-1.
altitudeReferenceと元の列の対応altitudeReference天面の元の列 天面を持たない場合の代替 AGLtop_bottom_3d_geometryの上面リング(coordinates[0])geometryWGS84top_bottom_3d_geometry_wgs84の上面リング(coordinates[0])geometry_wgs84 -
1-3-2. 応答の
altitudeReferenceは返却した形状の列で決まるAIRSPACE_RESTRICTION.altitude_referenceは接尾辞のない列のZ値が準拠する基準を示すもので、 現時点では常にAGLである(同列のコメント。飛行計画のFLIGHT_PLAN_AREA.altitude_referenceと 同じ扱い)。応答のFeatureを作り分けるフラグではなく、値をそのまま写してはならない。_wgs84列の基準は列名で自明なため、同列の対象外である。
-
1-3-3. 返却するのは天面のみである
geometryは3D表示補助として天面(ceiling)を表し、水平方向は元の形状のまま返す。 床面(floor)は返却せず、クライアント側で地表面に沿わせて表示する。geometryType=CIRCLEもPolygon近似で返す。元の中心・半径はcircleCenterLng/circleCenterLat/circleRadiusMが保持する。
-
1-3-4. 2件を返すのが前提である
_wgs84列は接尾辞のない列に対応して設定される列であり、1件の空域制限は2件のFeatureへ 展開されるのが前提である。クライアントも両基準が返ることを前提に表示を切り替える。_wgs84列の充填は取得処理側の責務であり、本APIは換算を行わない (airspace-er.mdの 「WGS84基準の形状も実体化列で持つ」)。
-
1-3-5. 過渡期に
_wgs84列がNULLの行はAGLのFeatureのみを返す- DDLが
_wgs84列をNULL可としているのは、収集を実装するまでの過渡的な措置である (db/schema/airspace_restriction.sqlの列コメント。ck_airspace_restriction_geometry_wgs84・ck_airspace_restriction_top_bottom_3d_wgs84も型・SRID・次元のみを保証し、接尾辞のない列との 対応は強制しない)。 - NULLの行に遭遇した場合は
WGS84のFeatureを組み立てられないため、AGLのFeatureのみを返す。 1件の欠落で検索結果全体を落とさないためであり、通常の姿ではない。 - この「全体を落とさない」は
_wgs84列がNULLの場合に限る。 形状そのものを解釈できない行 (面を持たないジオメトリ、geometry_typeと実ジオメトリの不一致など)は行単位で読み出しに失敗し、 検索全体が失敗する。取得元が与えるデータを表示するだけの立場では欠落した1行を落として続ける方が 整合するため(周辺計画収集も同じ軸で1件の除外を選んでいる)、方針を揃えるかは followups.mdに種別実体未作成で登録した。 - また、1件で返った行が「高度を持たない行」(1-3-6)なのか「
_wgs84列がNULLの行」(本項)なのかを、 クライアントが応答から区別する手段はない。信号の追加はOASの変更を伴うため、 同じ論点を持つ他Operator計画検索と一体で決める(同じく台帳へ登録した)。 - OASの
AirspaceRestrictionFeatureも「1件または2件」とし、本節および1-3-6に揃えてある。
- DDLが
-
1-3-6. 高度を持たない行は1件のFeatureのみを返す
- 高度の概念がない分類(レッドゾーン・イエローゾーン等)と、取得元が高度を提供しない行は、
geometryが2次元でmin/maxAltitudeMAglも未設定になる。水平形状は基準によって変わらないため、AGLとWGS84で内容が一致する。この場合は1件のFeatureのみを返し、altitudeReferenceは 設定しない(OASのAirspaceRestrictionProperties.altitudeReferenceが「geometryがZ値を 持たない場合(高度の概念がない種別、および取得元が高度を提供しない場合)は未設定。」と定める)。 - 同一内容のFeatureを2件返しても、クライアントが区別できず情報が増えないためである。
- 空域制限の高度は取得元が提供する値であり、「地表から150mAGLまで」のような固定値は持たない。 高度を持たない行は例外ではなく正規のデータである (airspace-er.mdの決定事項D3)。
- 高度の概念がない分類(レッドゾーン・イエローゾーン等)と、取得元が高度を提供しない行は、
-
1-3-7. Featureのプロパティ
- パラメータとデータベースカラムの項目単位の対応関係は geospatial-api-design.md5.2のマッピング表を参照。
externalIdは取得元の識別子を持つ行のみ返す。手動登録(sourceKind=MANUAL)の行は持たない。externalTypeIdに相当するプロパティは公開しない(airspace-er.mdの決定事項D6)。
-
- 1-4. 件数の上限と切り詰めの通知
limit(既定1000・最大10000)は空域制限の件数を数える。1件が複数のFeatureへ展開されるため、features配列の要素数はlimitを上回りうる。totalCountにはlimit適用前の該当件数を、truncatedにはtotalCountがlimitを超えたかどうかを設定する。
- 1-5. エラーケースに合わせてステータスコードを返却する。
- 400: リクエストボディのパース失敗(不正なJSON・型不一致など)
- 401: 未認証(forDemoでは認証を導入しないため発生しない。4.1参照)
- 422:
bboxが上限(幅50km・高さ50km・面積2500km²のいずれか)を超える、bboxの要素数が4でない、bboxが未指定、validAtとvalidFrom/validToの同時指定、validFrom/validToの片方のみの指定、limitが1〜10000の範囲外
5.4. 飛行軌跡取得(GET /api/v1/geo/telemetry/{flightPlanId})
Section titled “5.4. 飛行軌跡取得(GET /api/v1/geo/telemetry/{flightPlanId})”-
- 飛行軌跡取得
- 1-1. 取得条件
- 以下の内容をAND条件で絞り込んだ観測を対象とする。
TELEMETRY.organization_idが自組織のIDと一致すること(4.1参照)TELEMETRY.flight_plan_idがパスパラメータのflightPlanIdと一致することTELEMETRY.observed_atが「基準時刻 − 60秒」以降であること
- 1-1-1. 条件はパスパラメータのみである
- クエリパラメータ・リクエストボディを持たない。地図の表示範囲ではなく、選択された1機の
軌跡を引く用途に限られるため、飛行計画領域検索・空域制限検索が持つ
bboxに相当する条件はない。 - 旧APIが汎用のCQLフィルタで表現していた60秒ウィンドウを専用エンドポイントへ畳んだものである (geospatial-api-design.md6.5節)。
- クエリパラメータ・リクエストボディを持たない。地図の表示範囲ではなく、選択された1機の
軌跡を引く用途に限られるため、飛行計画領域検索・空域制限検索が持つ
- 1-1-2. 遡る長さは60秒に固定する
- リクエストからは指定できない。旧USSが表示用のViewで
current_timestamp - timestamp < 60(秒)と 絞っていたものを引き継いでいる。 - 基準時刻はSQLの
now()ではなくアプリケーション側の時計から求めて渡す。 同じ取得の中で 基準時刻がぶれないようにするためと、テストで時刻を固定できるようにするためである。 - 現在位置の取得と同じ値を使う。窓の長さが違うと、軌跡は表示されるのに現在位置は消えるといった 食い違いが起きるためである。
- リクエストからは指定できない。旧USSが表示用のViewで
- 1-1-3. 他社UTMが管理する機体は対象にならない
- forDemoでは他社UTMの機体を
ASSETとしてだけ登録し、IX UTM上に飛行計画を作らない (docs/data-model/telemetry-er.mdの「他社UTMの機体はASSETとしてだけ登録する」)。 この機体の観測はflight_plan_idがNULLとなり、本APIの取得条件に一致しない。 - 他社機の動態は現在位置の取得が担う。エラーとはしない。
- forDemoでは他社UTMの機体を
- 以下の内容をAND条件で絞り込んだ観測を対象とする。
- 1-2. 飛行計画の存在確認
- 1-2-1. 該当0件と404を区別する
- 飛行計画が存在しない場合と閲覧権限がない場合はいずれも404、直近60秒の観測が無い場合は
0件の
FeatureCollectionを返す。観測の取得はどちらの場合も0件を返すため、これだけでは 区別できない。飛行計画の存在と、それが自組織のものであることを別途確認する。 - 権限の有無を404に含めるのは、IDの存在有無が漏れることを避けるためである
(
frontend/geospatial.yamlの"404"のdescription)。自組織の判定は固定値で行う(4.1参照)。
- 飛行計画が存在しない場合と閲覧権限がない場合はいずれも404、直近60秒の観測が無い場合は
0件の
- 1-2-1. 該当0件と404を区別する
- 1-3. 返却するFeatureへの展開
-
該当した観測をまとめて1本のLineStringにし、
altitudeReferenceごとに1件のFeatureへ展開する。 飛行計画領域のようなdataTypeによる分岐は持たない。 -
1-3-1. 頂点は観測時刻の古い順に並べる
geometryの頂点順とtelemetryTimesの要素順は1:1で対応し、末尾が最新である (latestTelemetryTimeと同一時刻)。telemetryTimesが狭義単調増加になる根拠は機体単位までである。TELEMETRYの(aircraft_id, observed_at)は一意だが(docs/data-model/telemetry-er.mdの 「受信は順序保証も一意性もない前提で設計する」)、これは機体ごとの一意性であり、 本APIはflight_plan_idを軸に引く。1つの飛行計画に複数の機体が割り当たると、 機体をまたいだ同一観測時刻はこの一意性では防げない。- 同一観測時刻の頂点が並んだ場合は1-5の500になる。正当なリクエストでも起きうる。 時刻が一致しなければ検知できず、2機分が混ざった軌跡が200で返る。
-
1-3-2.
altitudeReferenceと元の値の対応altitudeReferencegeometryのZ値の元AGLTELEMETRY.altitude_agl_m(地表標高からの導出値)WGS84TELEMETRY.positionのZ値(機体が報告した測地高度)- 2件は
geometryのZ値のみが異なり、telemetryTimesを含む他のプロパティは同一である。
- 2件は
-
1-3-3.
AGLのFeatureは全頂点の対地高度が揃ったときだけ返す- 1頂点でも
altitude_agl_mがNULLであればWGS84の1件のみを返す。欠測した頂点を間引くと 軌跡の形状そのものが変わるためである。 - 現在位置は当該Featureのみ
altitudeReference=WGS84として測地高度を返す (geospatial-api-design.md7章「対地高度が得られない場合の応答方針」)。
- 1頂点でも
-
1-3-4. 対地高度は充填しない
altitude_agl_mは取り込みが受信時に導出して書き込む (docs/data-model/telemetry-er.mdの「対地高度は受信時に充填する」)。本APIは読み出し時に 導出も更新も行わない。- 地表標高データが当該地点をカバーしない場合、
altitude_agl_mはNULLのまま固定される。 その機体ではWGS84の1件だけが返り続ける。
-
1-3-5. 観測が1件以下の場合は0件で返す
geometryのLineStringは2点以上を要するため(OASのLineStringGeometry.coordinates・telemetryTimesともminItems: 2)、観測が1件ではFeatureを組み立てられない。 観測が無い場合と同じく0件のFeatureCollectionを返す。エラーとはしない。
-
1-3-6. Featureのプロパティ
- パラメータとデータベースカラムの項目単位の対応関係は geospatial-api-design.md5.3のマッピング表を参照。
latestTelemetryTime・latestSpeed・latestDirectionは最新の観測(頂点列の末尾)から採る。 頂点ごとの配列ではない。- 頂点ごとの配列を持たない残りのプロパティも、同じく最新の観測から採る。
flightPlanId・uasId・uasNickname・uasEntityId・operatorId・operatorName・statusが これにあたる。いずれも軌跡の全頂点で同じ値になる前提だが、どの行から採るかを1つに決めておかないと、 前提が崩れたときに項目ごとに違う観測の値が混ざる。採る行をlatestの3項目と揃える。 speedUnit・directionUnit・altitudeUnitは定数を返す。altitudeUnitに対応する列がTELEMETRYに無く定数にするしかないため、3つの扱いを揃える。OASの列挙もそれぞれ単一値である。operatorId・operatorName・statusの解決は4.5による。本APIは飛行計画IDを検索キーに するため、operatorId・statusは常に飛行計画由来の値が返る(複写元が既定値表になるのは 飛行計画を解決できない機体だけである)。operatorNameが未設定になる場合と固定文言で返す扱いは 4.5の表のとおりで、位置情報が揃っている以上、表示名が無いだけで軌跡は落とさない。operatorId・statusが空の行は取り込みの不具合を意味するため、500とする(1-5)。statusは飛行計画の対応づけを運航状態ではなく観測時刻で行うため、ENDEDのまま返ることがある (docs/data-model/telemetry-er.mdの「飛行計画は時刻で対応づける」)。
-
- 1-4. 件数の上限を持たない
- パスパラメータで単一の飛行計画を指定するため、
limit・totalCount・truncatedのいずれも 持たない。返却するFeatureは最大2件である。
- パスパラメータで単一の飛行計画を指定するため、
- 1-5. エラーケースに合わせてステータスコードを返却する。
- 400:
flightPlanIdがUUIDとして不正 - 401: 未認証(forDemoでは認証を導入しないため発生しない。4.1参照)
- 404: 指定した飛行計画が存在しない、または自組織のものでない(1-2-1参照)
- 500: 次のいずれか。いずれもクライアントからは是正できないため、詳細はサーバ側のログに残し、
応答には一般化したメッセージだけを返す
- DB操作に失敗した
- 取得した行をドメインモデルへ変換できない
- 取得した行が応答の必須項目を満たさない(飛行計画の状態が応答の列挙に無い値である場合を含む)
- 頂点の観測時刻が狭義単調増加でない(1-3-1参照)
- 400:
5.5. 現在位置一覧検索(POST /api/v1/geo/telemetry/position/search)
Section titled “5.5. 現在位置一覧検索(POST /api/v1/geo/telemetry/position/search)”-
- 現在位置一覧検索
- 1-1. 検索条件
- 機体ごとの現在位置(
CURRENT_TELEMETRY)を対象とし、指定された条件だけを和集合で結ぶ。bbox:positionが指定範囲に含まれることflightPlanIds:flight_plan_idがいずれかと一致することuasEntityIds:aircraft_idがいずれかと一致すること- 未指定の条件は和集合の項に加えない。AND条件の検索(5.1・5.3)と異なり、未指定を 「条件なし」と読むと全機体が該当してしまうためである。
- 和集合に対し、次をAND条件で適用する。
observed_atが「基準時刻 − 60秒」以降であることstatusが指定された場合、CURRENT_TELEMETRY.statusが指定値のいずれかであること。 未指定の場合は絞り込みを行わない(既定値を持つ空域制限検索のstatusとは扱いが逆である。5.3の1-2-2参照)
- 1-1-1. 検索条件の必須要件
bbox・flightPlanIds・uasEntityIdsのうち少なくとも1つの指定を必須とする。 すべて省略した全件検索は許可しない。- IDの空配列は「指定なし」と同じ扱いとする。追跡対象が0件になっても同じリクエスト形を
送り続けられるようにするためである。ただし
bboxの指定もなければ422になる。 - 和集合とするのはSSE配信(
GET /api/v1/geo/events/telemetry)と条件の組み立てを揃えるため である。ただしSSEはstatus・limitを持たないため、集合が常に一致するわけではない。
- 1-1-2. 該当しないIDを含めてもエラーとしない
- 存在しないID・飛行中でないIDを指定しても、該当分が結果に現れないだけである。追跡対象の
飛行終了によって検索そのものが失敗しないようにするためである
(
frontend/geospatial.yamlのFlightPlanIdFilter)。 - 自UTMの
ASSETに存在しない機体にuasEntityIdとして何を返すかは未決である (docs/data-model/followups.md)。本APIのデータ源はASSETに登録済みの機体に限られるため (docs/followups/telemetry.mdの307-01)、本APIでは表面化しない。恒久的に他Operator機を 扱う段階の論点である。
- 存在しないID・飛行中でないIDを指定しても、該当分が結果に現れないだけである。追跡対象の
飛行終了によって検索そのものが失敗しないようにするためである
(
- 1-1-3. 自組織の機体だけを返す
- 他の検索(5.1・5.4)と同じく自組織で絞り込む(forDemoでは固定値で判定。4.1参照)。 要件6.3.6.1・6.3.6.2はテナント間のデータ分離を求めており、本APIだけを例外にしない。
- 他社UTMが管理する機体もこの絞り込みで返る。 forDemoでは当該機体を自組織の
ASSETとして 登録する回避策を採っており(docs/data-model/followups.md)、CURRENT_TELEMETRY.organization_idはASSETの所有組織から解決されるためである (docs/data-model/telemetry-er.mdの「飛行計画に紐づかないテレメトリを受け入れる」)。 他組織として見えるのは既定値表が与える運航者名までで(4.5)、データの所属は自組織である。 - 他社UTMの機体はIX UTM上に飛行計画を持たず、飛行軌跡取得には現れない(5.4の1-1-3)。
その動態を返すのは本APIである。ただし他UTM管理の動態情報表示は機能要件が初版の対象外と
しており、10月デモのための例外である(
docs/data-model/telemetry-er.mdの「他社UTMの機体は ASSETとしてだけ登録する」)。
- 1-1-4. 遡る長さは60秒に固定する
- 値も基準時刻の求め方も飛行軌跡取得と同じである(5.4の1-1-2)。
- 1-1-5. 指定時刻の遡及には対応しない
CURRENT_TELEMETRYは機体ごとの最新1件しか保たず、過去の時点は履歴(TELEMETRY)から 機体ごとに1件引く必要があるため、カレントを引く検索では答えられない。時点を指定する条件は リクエストに持たない。遡及が要ると分かった時点で履歴を引く別のPortを足すかを決める (docs/data-model/followups.mdのFlyingDronePositionsSearchRequest.currentTimeの行)。
- 機体ごとの現在位置(
- 1-2. 返却するFeatureへの展開
- 該当した機体1機を1件のPoint Featureへ展開する。飛行計画領域・飛行軌跡と異なり、
dataTypeやaltitudeReferenceによる多重化は行わない。 - 1-2-1.
altitudeReferenceはFeatureごとに決まるaltitude_agl_mがあればAGLとし、geometryのZ値に対地高度を入れる。NULLの場合は当該 FeatureのみWGS84とし、positionのZ値(機体が報告した測地高度)を入れる。位置情報 そのものを落とさないためである。- 軌跡は1頂点でも欠ければ
WGS84の1件のみとするが(5.4の1-3-3)、現在位置は1機1点のため 判定が機体ごとに閉じる。 altitudeMWgs84にはいずれの場合もpositionのZ値を入れる。altitudeReference=WGS84の FeatureではgeometryのZ値と同値になる。
- 1-2-2. 対地高度は充填しない
- 5.4の1-3-4と同じ。本APIは読み出し時に導出も更新も行わない。
- 1-2-3. Featureのプロパティ
- 項目単位の対応関係はgeospatial-api-design.md5.3の
マッピング表を参照。
speedUnit・directionUnit・altitudeUnitは定数を返す(5.4の1-3-6と同じ)。 operatorId・operatorName・statusの解決は4.5による。本APIは5.4と違い、飛行計画を 解決できない機体を含むため、既定値表由来の値と未設定のどちらも現れる。flightPlanIdは飛行計画の対応づけの結果で、解決できた機体にだけ設定する。代替値を作ると 実在の値と区別できなくなるためで、4.5のoperatorId・statusと同じ理由である。対応づけの条件はdocs/data-model/telemetry-er.mdの「飛行計画は時刻で対応づける」が正で、機体への割り当てと、 観測時刻が計画期間に入るか、入らなければ同じ日に開始予定の計画があるかで決まる (予定からずれて飛んだ場合を拾うため。運航状態は条件に使わず、CANCELLEDの計画だけを除外する)。 対応づけられる計画が無い機体で未設定になり、UTM内に計画を持たない 機体(10月デモで他UTMが管理する機体を表示する場合)だけでなく、自組織の機体でも起こりうる。statusは複写元が飛行計画の場合、対応づけを観測時刻で行うためENDEDのまま返ることがある (5.4の1-3-6と同じ)。- 応答の列挙に無い運航状態(
NON_CONFORMING・CONTINGENT)はstatusを未設定にして返す。 ただしこの経路は現在到達しない。 両値はConformance Monitoringの将来実装向けで、DBのflight_planning.flight_plan_status_typeに対応する値が無く読み出されないためである (FlightPlanStatusのjavadoc)。値域が広がったときに一覧全体を落とさないための備えであり、 契約として当てにしない。 - 運航状態が未設定の機体は、
statusを指定した検索では返らない。 絞り込みは複写列に対して SQLで行うためである。既定値表がstatusを持つのはこれを避けるためで (docs/data-model/telemetry-er.mdの「表示用の値は機体ごとの既定値で埋める」)、 消えるのは4.5の表が挙げる未設定の場合に限られる。追跡目的ではstatusを指定しない(1-1-1)。 altitudeMWgs84は常に設定される。「値なし」特殊値の測地高度は取り込み時の入力チェックで 却下され行が保持されないためである(docs/data-model/telemetry-er.mdのTELEMETRY_DEAD_LETTER.reason)。positionはNOT NULLでもある。speed・directionが空の機体は結果から落とす。 同じ入力チェックを通った値しか 書かれないため、空の行は取り込み側の不具合を意味する。表示用の値と違って代わりに 入れられる値が無く、かといって1機の異常で一覧全体を落とすと見張りが成り立たないため、 当該の機体だけを落として残りを返す。落とした機体はログに残す。- 落とした機体は
totalCountには残る。件数は行とは別のSELECTで数えるため、除外を 反映できないからである(1-3参照)。 - 欠損した項目の扱いは飛行軌跡取得と異なる。 軌跡は
operatorId・statusが空であれば 500とするが(5.4の1-5)、本APIは当該の項目を未設定にして200で返す。軌跡は飛行計画を 検索キーにするため両項目は常に複写されており、空なら取り込みの不具合を意味する。対して 本APIは飛行計画を持たない機体を含み、空であることが正常な状態になる。
- 項目単位の対応関係はgeospatial-api-design.md5.3の
マッピング表を参照。
- 該当した機体1機を1件のPoint Featureへ展開する。飛行計画領域・飛行軌跡と異なり、
- 1-3. 件数の上限と切り詰めの通知
limit(既定1000・最大10000)は機体の件数を数える。1機が1件のFeatureになるため、飛行計画 領域検索(5.1の1-3)と違ってfeatures配列の要素数と数える単位が一致する。- 切り詰めは
bbox由来の機体にのみ適用し、IDで名指しした機体は常に返す。 追跡対象がbbox内の 機体数に押し出されて消えないようにするためである。名指し分を切り詰めないため、featuresの 要素数はlimitを上回りうる。 totalCountには和集合の切り詰め前の件数を、truncatedにはbbox由来分が切り詰められたかを 設定する。切り詰められた機体をIDでも名指ししていれば結果には残るため、truncated=trueでも 1機も落ちていないことがある。featuresの要素数とtotalCountは厳密には一致しない。 件数は行とは別のSELECTで数えるため (CurrentTelemetrySearchResultのjavadoc)であり、実測値を欠く機体の除外(1-2-3)も加わる。 件数は目安として扱う。
- 1-4. エラーケースに合わせてステータスコードを返却する。
-
400: リクエストボディのパース失敗(不正なJSON・型不一致など)
-
401: 未認証(forDemoでは認証を導入しないため発生しない。4.1参照)
-
422:
bboxが上限(幅50km・高さ50km・面積2500km²のいずれか)を超える、bboxの要素数が4でない・ 要素にnullを含む・値域外・順序が逆、flightPlanIds・uasEntityIds・statusのいずれかが 要素にnullを含む、flightPlanIds・uasEntityIdsの指定件数が各100件を超える、limitが1〜10000の範囲外、bbox・flightPlanIds・uasEntityIdsのすべてが未指定 -
500: 次のいずれか。いずれもクライアントからは是正できないため、詳細はサーバ側のログに残し、 応答には一般化したメッセージだけを返す
- DB操作に失敗した
- 取得した行をドメインモデルへ変換できない
実測値の欠損と、応答の列挙に無い運航状態は500にしない。前者は当該の機体を落とし、後者は 当該の項目を落として200で返す(いずれも1-2-3)。
-
5.6. 現在位置のリアルタイム購読(GET /api/v1/geo/events/telemetry)
Section titled “5.6. 現在位置のリアルタイム購読(GET /api/v1/geo/events/telemetry)”更新の検知方式を選んだ経緯はtelemetry-sse-change-detection.mdにある。
-
- 接続の確立
- 1-1. 購読条件
- 配信対象は5.5の1-1と同じ条件で決める(
bboxとIDの和集合、観測時刻が基準時刻 − 60秒以降、 自組織の機体に限る)。status・limitは持たない。 - 1-1-1. クエリパラメータの検査
- 5.5の1-1-1・1-4と同じ判定を行い、違反は接続を確立する前に返す。
- IDの空値(
flightPlanIds=)は指定なしと同じ扱いとする。
- 配信対象は5.5の1-1と同じ条件で決める(
- 1-2. 接続の登録
- 接続ごとに、購読条件と「この接続へ送った機体とその観測時刻」を持つ。登録した時点では空である。
- 登録した時点でコメント行を1行送り、応答ヘッダを送り出す。Springは最初の書き込みまでヘッダを 送らないため、送らないと初期状態を送るまで接続が確立しない(コメント行はイベントとしては渡らない)。
- 1-2-1. 初期状態は次の確認で送る
- 登録時にはDBを引かない。次の確認(2-1、最長1秒後)で、配信対象の全機体を
telemetry.snapshotとして送る。 - 登録時に別途検索すると、検索から次の確認までに届いた更新を
telemetry.positionとして 先に送り、あとから届く古い初期状態で上書きさせる順序になりうる。初期状態を確認の結果から 作れば、初期状態とその後の差分が同じ読み出しに基づく。 - 件数では切り詰めない。10月デモの機体数(数機)では問題にならないためである。TODO: FOLLOWUP 315-06
- 初期状態には送出時刻を載せる。クライアントが各機体の古さを端末の時計に頼らず求めるためである(2-2-2)。
- 登録時にはDBを引かない。次の確認(2-1、最長1秒後)で、配信対象の全機体を
- 1-3. 接続の維持と終了
- 初期状態を送った後から、15秒ごとに
pingを送る。初期状態を送る前の接続には、代わりにコメント行を送る。 初期状態より先にイベントを届けずに、接続を保つためである。 - 30〜35分で接続を正常終了する。クライアントは張り直し、初期状態から受け直す。
30分は通知SSE(
notification.sse.emitter-timeout)に揃えた値で、前段の構成から決めた値ではない。 接続ごとに最大5分のばらつきを足す。サーバの再起動直後に張られた接続が一斉に張り直し、 初期状態の送出が重なるのを避けるためである。 TODO: FOLLOWUP 315-02 - 送信に失敗した接続は登録から外す(クライアントが切断した)。
- アプリケーションの停止時は、
pingを止め、接続を閉じてからスレッドを止める。閉じている 最中に送信が走らないようにするためである(通知SSEのSseEmitterRegistryと同じ順序)。
- 初期状態を送った後から、15秒ごとに
-
- 更新の配信
- 2-1. 更新の確認
- 1秒ごとに、自組織の飛行中(
observed_atが基準時刻 − 60秒以降)の全機体の現在位置をCURRENT_TELEMETRYから読む。組織のほかには条件で絞らずに1回だけ読み、接続ごとの振り分けは メモリ上で行う。問い合わせの回数を接続数に比例させないためである。 - 1回の読み出しで足りるのは、forDemoでは組織が1つだからである(4.1)。認証を入れて組織が 複数になると、読み出しは組織ごとに行い、接続は自分の組織を持つ必要がある。 TODO: FOLLOWUP 315-05
- 基準時刻の求め方は5.4の1-1-2と同じである。
- 接続が1本もない間は読まない。
- 前回以降に受信した行だけを読む形にはしない。
received_atは取り込みが処理を始めた時刻で コミットより前になるため、受信時刻で区切るとコミットの遅れた行を取りこぼす。
- 1秒ごとに、自組織の飛行中(
- 2-2. 接続ごとの振り分け
- 読んだ機体のうち購読条件に合うものを、その接続の配信対象とする。
bboxの判定は境界を含む (5.5のSQLの&&と同じ)。 - 初期状態を送っていない接続には、配信対象の全機体を
telemetry.snapshotで送る。 - 初期状態を送った接続には、前回送った状態との差分を送る。
- 配信対象にあり、未送信か、送った観測時刻より新しい機体:
telemetry.position - 送ったことがあり、配信対象から消えた機体:
telemetry.remove(鮮度切れとbboxの外への 移動のどちらもこれで検知する)
- 配信対象にあり、未送信か、送った観測時刻より新しい機体:
- 送った観測時刻と同じ機体は送らない。重複を減らし、観測時刻が後退しないことをこれで保証する。
- 前回の送信が終わっていない接続には、その回を送らない。読まないクライアント(スリープした端末 など)への書き込みは詰まるため、1本の詰まりで他の接続への配信を止めないようにする。差分は 前回送り切った状態から求めるため、飛ばした回の変化は次の回にまとめて届く。
- 2-2-1. Featureの組み立て
- 5.5の1-2と同じである。
speed・directionが空の機体は配信対象から除き、ログに残す (5.5の1-2-3)。送ったことのある機体なら、除いた回にtelemetry.removeで外れる。
- 5.5の1-2と同じである。
- 2-2-2. テレメトリが欠損した機体の扱いと要件との対応
- 欠損から60秒までは
telemetry.removeを送らず、最後の位置が表示に残る。経過時間と「古い」 「不明」の判定はクライアントが行う。端末の時計とtelemetryTimeは比べず、初期状態の機体は 受け取った時点で「送出時刻 −telemetryTime」だけ古いとし、その後のtelemetry.positionは 受け取った時点を観測の時点とみなす(OASに明記)。機体の時計のずれは残る。クライアントがこれを 実装すれば、utm-design-docsの機能要件(docs/functional-requirements/requirements.md)の 4.1.4・9.1.2.3.2・9.1.3.3.1をこの範囲で満たせる。TODO: FOLLOWUP 315-07 - 60秒を超えると
telemetry.removeで表示から外すため、9.1.3.3.1の「最後の既知位置の表示」は 続かない。60秒で外す規則は一覧検索と共通で(5.5の1-1-4)、表示を続ける期間は要件に定めが無い。 TODO: FOLLOWUP 315-03
- 欠損から60秒までは
- 読んだ機体のうち購読条件に合うものを、その接続の配信対象とする。
- 2-3. 読み出しに失敗した場合
- その回の配信を飛ばし、ログに残して次の確認で再試行する。接続は閉じない。DBの一時的な 障害で、全クライアントに再接続を繰り返させないためである。
- 失敗が続く間は
telemetry.removeも送られないため、途絶えた機体が表示に残る。初期状態を 送った接続にはpingは送られ続けるので、クライアントからは区別できない。 - 失敗が続く間に張った接続は、確立する(1-2)が初期状態を送れない。
pingの代わりにコメント行が 届き、OASのストールの判定ではこれも受信に数えるため(1-3)、クライアントは張り直さずに初期状態を待つ。
-
- エラーケースに合わせてステータスコードを返却する。
- 400: クエリパラメータの型が不正(
bboxの要素が数値でない、IDがUUID形式でない) - 401: 未認証(forDemoでは認証を導入しないため発生しない。4.1参照)
- 422: 5.5の1-4と同じ条件(
limitを除く) - 500: 接続を確立する前に予期しないエラーが起きた場合。確立した後の失敗は2-3に従う