翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# テレメトリデータを理解する
テレメトリデータは BaseBase64-encodedされた JSON レコードとして Kinesis Data Streams ストリームに配信されます。各レコードには、コンタクトに関するメタデータやサンプリングされたテレメトリ測定値など、衛星コンタクト中に収集された情報が含まれます。
## データ形式の概要
各テレメトリレコードには、次のコンポーネントが含まれています。
テレメトリのタイプとバージョン
テレメトリデータの特定のタイプとそのスキーマバージョンを識別します。これにより、さまざまなテレメトリタイプを適切に解析できます。スキーマのバージョニングの詳細については、「」を参照してください[スキーマのバージョニングと進化](#telemetry.understanding-data.schema-evolution)。
スコープ ID
テレメトリの範囲の一意の識別子。これにより、テレメトリデータを特定の連絡先に関連付けることができます。
メタデータ
テレメトリに関するコンテキスト情報。
データ
テレメトリタイプに固有のサンプリングされたテレメトリ測定値。
**パーティションキー**
テレメトリレコードは、 形式のパーティションキーを使用して Kinesis Data Streams ストリームに配信されます。
```
SCOPE#{{scopeId}}#TELEMETRY_ID#{{telemetryId}}#TELEMETRY_VERSION#{{telemetryVersion}}
```
このパーティションキーにより、1 つのコンタクトに対する特定のタイプのすべてのテレメトリが Kinesis Data Streams ストリーム内の同じシャードに配信され、そのコンタクトのテレメトリストリームの最適な順序付けが可能になります。
## ポイントテレメトリ
ポインティングテレメトリは、衛星コンタクト中のアンテナのポインティング方向に関する情報を提供します。このテレメトリタイプは、常に問い合わせ中に送信されます。
**データフィールド**
sampleTimestamp
テレメトリデータがサンプリングされた時刻。ISO-8601 形式では UTC、ミリ秒精度。
方位
アンテナの実際の方位角度を度数で表します。
標高
アンテナの実際の高度角度。
commandedAzimuth
角度単位のコマンドされた方位角。これは、アンテナが達成しようとしているターゲット方位角です。
commandedElevation
角度単位のコマンドされた標高角度。これは、アンテナが達成しようとしているターゲットの標高角度です。
**注記**
実際のアンテナ位置は、物理的な制限や接触中の機械的な遅延により、コマンドされた位置とは異なる場合があります。
**メタデータフィールド**
groundStation
地上局の名前 (「オハイオ 1」など）。
satelliteId
の衛星リソースの識別子 AWS Ground Station。
contactId
問い合わせの識別子。
**JSON の例**
```
{
"telemetryTypeAndVersion": "POINTING#1.0.0",
"telemetryType": "POINTING",
"telemetryVersion": "1.0.0",
"scopeId": "12345678-1234-1234-1234-123456789012",
"metadata": {
"groundStation": "Ohio 1",
"satelliteId": "87654321-4321-4321-4321-210987654321",
"contactId": "12345678-1234-1234-1234-123456789012"
},
"data": {
"sampleTimestamp": "2025-12-08T12:00:00.123Z",
"azimuth": 180.5,
"elevation": 45.2,
"commandedAzimuth": 180.0,
"commandedElevation": 45.0
}
}
```
## テレメトリの追跡
追跡テレメトリは、アンテナ追跡ステータスと追跡エラーに関する情報を提供します。このテレメトリタイプは、追跡設定で自動追跡が有効になっているとき、およびアンテナが自動追跡をアクティブに使用しているときに送信されます。
**注記**
TrackingConfig の `autotrack`パラメータが に設定されている場合`REMOVED`、追跡テレメトリは配信されません。設定の追跡の詳細については、「」を参照してください[追跡設定](how-it-works.config.md#how-it-works.config-tracking)。
**データフィールド**
sampleTimestamp
テレメトリデータがサンプリングされた時刻。ISO-8601 形式では UTC、ミリ秒精度。
trackingStatus
アンテナの現在の追跡ステータス。可能な値は以下のとおりです。
+ `TRACKING` — アンテナはミッションプロファイルに一致する信号に正常にロックされ、空を横断してアクティブにフォローしています。これは、コンタクト中のわずかな運用状態です。
+ `ACQUIRING` — アンテナは信号を見つけてロック中です。システムは現在、エフェメリスデータに基づいてポイントするプログラムによる追跡を使用しています。
+ `MASKED` — 衛星の予測位置は自動トラックマスクの背後にあります。つまり、アンテナはその特定の方向で自動トラックを確実に利用することはできません。これは通常、低標高などの RF 干渉が高い領域で発生します。
trackingErrorAzimuth
方位軸の追跡エラー。度数で測定されます。
trackingErrorElevation
高度軸の追跡エラー。度数で測定されます。
**注記**
追跡エラー値は、信号強度を最大化するために自動追跡中 AWS Ground Station に適用されるエフェメリスベースのプログラムトラックの調整を表します。
**メタデータフィールド**
追跡テレメトリには、ポイントテレメトリと同じメタデータフィールド `groundStation`、`satelliteId`、および が含まれます`contactId`。
**JSON の例**
```
{
"telemetryTypeAndVersion": "TRACKING#1.0.0",
"telemetryType": "TRACKING",
"telemetryVersion": "1.0.0",
"scopeId": "12345678-1234-1234-1234-123456789012",
"metadata": {
"groundStation": "Ohio 1",
"satelliteId": "87654321-4321-4321-4321-210987654321",
"contactId": "12345678-1234-1234-1234-123456789012"
},
"data": {
"sampleTimestamp": "2025-12-08T12:00:00.123Z",
"trackingStatus": "TRACKING",
"trackingErrorAzimuth": 0.2,
"trackingErrorElevation": 0.1
}
}
```
## Kinesis Data Streams ストリームからのデータの読み取り
テレメトリデータは Kinesis Data Streams ストリームに配信され、標準のストリーム消費パターンを使用して消費できます。ストリームからデータを読み取るときは、次の考慮事項に留意してください。
**Base64 デコード**
Kinesis Data Streams ストリームのデータは Base64-encodedされています。データを JSON として解析する前に、データをデコードする必要があります。詳細については、[Amazon Kinesis Data Streams の使用](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html)」を参照してください。
**Kinesis Data Viewer の使用**
テレメトリデータにすばやくアクセスするために、Kinesis Data Streams ストリームコンソールにはデータビューワー機能が用意されています。この機能を使用する場合:
+ テレメトリ配信は、ストリーム内の任意のシャードに発生する可能性があります。
+ デフォルトの開始位置は、シャード内の最新のレコードから読み取られます。
+ 選択したシャードを調整し、「タイムスタンプ時」の開始位置を使用して、受信したレコードを表示する必要がある場合があります。
**Kinesis Client Library の使用**
Kinesis Client Library (KCL) は、シャード管理、チェックポイント、ロードバランシングなど、Kinesis Data Streams ストリームからのデータの消費に関連する多くの複雑さを管理します。本番テレメトリ消費アプリケーションには KCL を使用することをお勧めします。
詳細については、[「Kinesis Client Library を使用したコンシューマーの開発](https://docs.aws.amazon.com/streams/latest/dev/kcl.html)」を参照してください。
**消費のベストプラクティス**
+ **レイテンシーの最小化** - 拡張ファンアウトを使用して Kinesis Data Streams ストリームから読み取ると、ポーリングに比べて専用のスループットとレイテンシーが低くなります。詳細については、[「拡張ファンアウトコンシューマーの開発](https://docs.aws.amazon.com/streams/latest/dev/enhanced-consumers.html)」を参照してください。
+ **専用ストリーム** - AWS Ground Station テレメトリ統合に専用の Kinesis Data Streams ストリームを使用します。ストリームを他のアプリケーションと共有すると、書き込みスループットの飽和やテレメトリ配信の失敗が発生する可能性があります。
+ **オンデマンドキャパシティ** - Kinesis Data Streams ストリームをオンデマンドプロビジョニングモードでデプロイして、スループットに基づいてシャードを自動的にスケーリングできるようにします。
+ **スループットのモニタリング** - CloudWatch メトリクスを使用してストリームのスロットリングをモニタリングします。詳細については、[Amazon Kinesis Data Streams のモニタリング](https://docs.aws.amazon.com/streams/latest/dev/monitoring-with-cloudwatch.html)」を参照してください。
## スキーマのバージョニングと進化
テレメトリスキーマは、時間の経過に伴う進化をサポートするようにバージョン管理されています。各レコードの `telemetryVersion`フィールドはスキーマバージョンを示します。
**スキーマの変更の処理**
+ 今後、新しいテレメトリタイプが導入される可能性があります。
+ 既存のテレメトリタイプは、重大な変更を含む新しいバージョンを受け取る場合があります。
+ アプリケーションは、不明なテレメトリタイプとバージョンに対して寛容である必要があります。
+ `telemetryTypeAndVersion`、、および `telemetryVersion`フィールドを解析して`telemetryType`、各レコードの処理方法を決定します。
複数のスキーマバージョンを適切に処理できるバージョン対応ペイロードのシリアル化を実装し、新しいバージョンが導入されてもアプリケーションが引き続き機能できるようにすることをお勧めします。