本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 提供 TLE ephemeris 資料
**重要**
ephemeris API 目前處於預覽狀態
僅在需要時提供對 Ephemeris API 的存取。如果您需要上傳自訂暫時性資料的功能，請透過 開立AWS 支援票證[AWS Support Center Console](https://console.aws.amazon.com/support)。您的團隊將與您合作，為您的特定需求啟用此功能。
## 概觀
雙行元素 (TLE) 集是用於描述衛星軌道的標準化格式。Ephemeris API 允許將 TLE 暫時性資料上傳到AWS Ground Station，以便與衛星搭配使用。這些暫時性物質會覆寫來自 [Space-Track](https://www.space-track.org/) 的預設暫時性物質 （請參閱：[預設暫時性資料](default-ephemeris-data.md))。
AWS Ground Station將 ephemerides 視為[個人化用量資料](https://aws.amazon.com/service-terms)。如果您使用此選用功能，AWS 將使用 ephemeris 資料來提供故障診斷支援。
上傳自訂 TLE 暫時化可以改善追蹤品質、處理沒有可用 [Space-Track](https://www.space-track.org/) 暫時化的早期操作AWS Ground Station，以及計算操作。不過，TLE 準確度會受到傳播模型的限制，並隨著時間的推移而降級。如需較長時間範圍內的高保真暫時性資料，請考慮使用 OEM 格式 （請參閱 [提供 OEM ephemeris 資料](providing-oem-ephemeris-data.md))。
**注意**
在為衛星指派衛星目錄號碼之前提供自訂 ephemeris 時，您可以將 `00000`用於 TLE 的衛星目錄號碼欄位，以及 `000` TLE 國際指標欄位的啟動號碼部分 （例如 `24000A`用於 2024 年啟動的車輛）。
如需 TLEs 格式的詳細資訊，請參閱[雙行元素集](https://en.wikipedia.org/wiki/Two-line_element_set)。
## TLEs 中的 Alpha-5 衛星目錄號碼
雙行元素集 (TLEs) 使用固定寬度格式，其中衛星目錄編號欄位 （第 1 行和第 2 行的 3–7 欄） 限制為 5 位數，支援最大值 99，999。為了表示超過此限制的衛星目錄號碼，美國空間力量開發了 [Alpha-5](https://www.space-track.org/documentation#tle-alpha5) 編碼方案。Alpha-5 以字母字元 (A–Z，排除 I 和 O，以避免混淆數字 1 和 0) 取代衛星型號欄位的第一位數。這會將現有固定寬度 TLE 格式內的可表示衛星目錄編號範圍從 100，000 擴展到 339，999。
Alpha-5 純粹是 TLE 文字格式的顯示編碼。基礎數值衛星目錄號碼不會變更。API 中的 `noradSatelliteID`AWS Ground Station欄位會保持整數 — API 回應，例如 `ListSatellites`並繼續`GetSatellite`傳回數值衛星目錄編號，而不是 Alpha-5 編碼形式。Alpha-5 編碼僅與 TLE 文字行本身相關。
AWS Ground Station支援包含 Alpha-5 編碼衛星號碼的 TLE 暫時化。當您透過 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 動作上傳 TLE 時， 會AWS Ground Station正確剖析 Alpha-5 編碼的衛星號碼，並在內部解析為對應的整數衛星目錄號碼。完全支援 Alpha-5 範圍 (100，000–339，999) 中衛星目錄號碼的衛星。
以下是為衛星目錄編號為 100，000 的衛星設定的範例 TLE。Alpha-5 編碼會在每個 TLE 行的資料欄 3–7 `A0000`中表示：
```
[
{
"tleLine1": "1 A0000U 26001A 26120.50000000 .00000072 00000-0 24500-4 0 9991",
"tleLine2": "2 A0000 97.4500 85.2300 0012345 45.6789 314.5678 15.20000000 10013",
"validTimeRange": {
"startTime": 1777680000,
"endTime": 1778284800
}
}
]
```
如需 Alpha-5 編碼方案的詳細資訊，請參閱 [Space-Track Alpha-5 文件](https://www.space-track.org/documentation#tle-alpha5)。
## 建立 TLE ephemeris
您可以使用 API 中的 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 動作來建立 TLE ephemeris。AWS Ground Station此動作將使用請求內文中的資料或從指定的 S3 儲存貯體上傳暫時性資料。
請務必注意，上傳 ephemeris 會將 ephemeris 設定為 ，`VALIDATING`並啟動非同步工作流程，以驗證和產生來自 ephemeris 的潛在聯絡人。只有在 ephemeris 通過此工作流程後，`ENABLED`才會將其用於聯絡人。您應該輪詢 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 以取得暫時性狀態，或使用 CloudWatch 事件來追蹤暫時性狀態變更。
若要對無效的暫時性事件進行故障診斷，請參閱： [故障診斷無效的短暫性事件](troubleshooting-invalid-ephemerides.md)
## 範例：透過 API 建立雙行元素 (TLE) 集合暫時性
AWS SDKs 和 CLI 可用來AWS Ground Station透過 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 呼叫，將雙行元素 (TLE) 集合暫時上傳至 。此暫時性資料將用於取代衛星的預設暫時性資料 （請參閱 [預設暫時性資料](default-ephemeris-data.md))。此範例示範如何使用[AWS適用於 Python 的 SDK (Boto3)](https://docs.aws.amazon.com/pythonsdk) 執行此操作。
TLE 集是 JSON 格式的物件，可將一或多個 TLEs 串連在一起，以建構連續軌跡。TLEs 集合中的 TLE 必須形成連續集合，我們可以用來建構軌跡 （即 TLE 集合中 TLEs之間的時間差距）。範例 TLE 集如下所示：
```
[
{
"tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": 12345,
"endTime": 12346
}
},
{
"tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": 12346,
"endTime": 12347
}
}
]
```
**注意**
TLEs 集合中 TLE 的時間範圍必須完全相符，才能成為有效的連續軌跡。
您可以透過 boto3 AWS Ground Station用戶端上傳 TLE 集，如下所示：
```
import boto3
from datetime import datetime, timedelta, timezone
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create TLE ephemeris
tle_ephemeris = ground_station_client.create_ephemeris(
name="Example Ephemeris",
satelliteId="2e925701-9485-4644-b031-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=3),
priority=2,
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": datetime.now(timezone.utc),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
}
]
}
},
)
print(f"Created TLE ephemeris with ID: {tle_ephemeris['ephemerisId']}")
```
此呼叫將傳回 ephemerisId，可用於在未來參考 ephemeris。例如，我們可以使用上述呼叫中提供的 ephemerisId 來輪詢 ephemeris 狀態：
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create a TLE ephemeris
print("Creating TLE ephemeris...")
tle_ephemeris = ground_station_client.create_ephemeris(
name="Example TLE Ephemeris for Description",
satelliteId="2e925701-9485-4644-b031-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=3),
priority=2,
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": datetime.now(timezone.utc),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
}
]
}
},
)
ephemeris_id = tle_ephemeris["ephemerisId"]
print(f"Created TLE ephemeris with ID: {ephemeris_id}")
# Describe the ephemeris immediately to check initial status
print("Describing ephemeris...")
response = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)
print(f"Ephemeris ID: {response['ephemerisId']}")
print(f"Name: {response['name']}")
print(f"Status: {response['status']}")
```
以下提供 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 動作的範例回應
```
{
"creationTime": 1620254718.765,
"enabled": true,
"name": "Example Ephemeris",
"ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE01",
"priority": 2,
"status": "VALIDATING",
"suppliedData": {
"tle": {
"ephemerisData": "[{\"tleLine1\": \"1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997\",\"tleLine2\": \"2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906\",\"validTimeRange\": {\"startTime\": 1620254712000,\"endTime\": 1620859512000}}]"
}
}
}
```
建議您輪詢 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 路由或使用 CloudWatch 事件來追蹤上傳的暫時性事件的狀態，因為它必須先經過非同步驗證工作流程，才能設定為 `ENABLED` 並可用於排程和執行聯絡人。
請注意，在上述`25994`範例中，TLE 集中所有 TLEs中的 NORAD ID 必須符合您的衛星在 [Space-Track](https://www.space-track.org/) 資料庫中指派的 NORAD ID。
## 範例：從 S3 儲存貯體上傳 TLE ephemeris 資料
您也可以透過指向儲存貯體和物件金鑰，直接從 S3 儲存貯體上傳 TLE ephemeris 檔案。AWS Ground Station將代表您擷取物件。有關 中靜態資料加密的詳細資訊AWS Ground Station，請參閱：[的靜態資料加密 AWS Ground Station](security.encryption-at-rest.md)。
以下是從 S3 儲存貯體上傳 TLE ephemeris 檔案的範例
```
import boto3
from datetime import datetime, timedelta, timezone
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "ephemeris-bucket"
object_key = "test_data.tle"
# Create sample TLE set data
# Note: For actual satellites, use real TLE data from sources like Space-Track
tle_set_data = [
{
"tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": datetime.now(timezone.utc),
"endTime": datetime.now(timezone.utc) + timedelta(days=3),
},
},
{
"tleLine1": "1 25994U 99068A 20321.54719794 .00000075 00000-0 26688-4 0 9998",
"tleLine2": "2 25994 98.2007 33.6589 0001234 89.2782 18.9934 14.57114995112342",
"validTimeRange": {
"startTime": datetime.now(timezone.utc) + timedelta(days=3),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
},
]
# Convert to JSON string for upload
tle_json = json.dumps(tle_set_data, indent=2)
# Upload sample TLE data to S3
print(f"Uploading TLE set data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=tle_json, ContentType="application/json"
)
print("TLE set data uploaded successfully to S3")
print(f"Uploaded {len(tle_set_data)} TLE entries covering 7 days")
# Create TLE ephemeris from S3
print("Creating TLE ephemeris from S3...")
s3_tle_ephemeris = ground_station_client.create_ephemeris(
name="2022-11-05 S3 TLE Upload",
satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=5),
priority=2,
ephemeris={"tle": {"s3Object": {"bucket": bucket_name, "key": object_key}}},
)
print(f"Created TLE ephemeris with ID: {s3_tle_ephemeris['ephemerisId']}")
```