本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 了解 AWS Ground Station 如何使用 ephemeride
[暫時性](https://en.wikipedia.org/wiki/Ephemeris)的複數暫時性的是一種檔案或資料結構，可提供天文物件的軌跡。從歷史上來看，此檔案只參考表格式資料，但逐漸導向到表示太空船軌跡的各種資料檔案。
Ephemeris API 允許將自訂暫時性化上傳到 AWS Ground Station ，以便與衛星搭配使用。這些暫時性物質會覆寫來自 [Space-Track](https://www.space-track.org/) 的預設暫時性物質 （請參閱：[預設暫時性資料](default-ephemeris-data.md))。我們支援以 Orbit Ephemeris Message (OEM)、雙行元素 (TLE) 和方位提升格式接收暫時性資料。
AWS Ground Station 使用 ephemeris 資料，根據 AWS Ground Station 網路中提供的 ephemeris 和正確命令天線來判斷聯絡人何時可用。根據預設，如果您的衛星有指派的 [NORAD ID](https://en.wikipedia.org/wiki/Satellite_Catalog_Number)，則不需要採取任何動作來 AWS Ground Station 提供 ephemeride。
上傳自訂暫時化可以改善追蹤品質、處理沒有可用 [Space-Track](https://www.space-track.org/) 暫時化的早期操作 AWS Ground Station，以及考慮操作。
或者， AWS Ground Station 支援方位提升格式，可讓您直接指定天線指向方向，而無需提供衛星軌道資訊。這適用於因為衛星軌跡資訊不精確或未知而需要精確天線指向的情況。
**Topics**
+ [預設暫時性資料](default-ephemeris-data.md)
+ [提供自訂暫時性資料](providing-custom-ephemeris-data.md)
+ [使用自訂 ephemeris 預留聯絡人](reserving-contacts-with-custom-ephemeris.md)
+ [了解使用哪些 ephemeris](which-ephemeris-is-used.md)
+ [取得衛星的目前暫時性變化](getting-current-ephemeris.md)
+ [還原至預設 ephemeris 資料](reverting-to-default-ephemeris-data.md)
# 預設暫時性資料
根據預設， AWS Ground Station 會使用來自 [Space-Track](https://www.space-track.org/) 的公開可用資料，而且不需要採取任何動作來提供 AWS Ground Station 這些預設的短暫性資料。這些暫時性元素是與衛星 [NORAD ID](https://en.wikipedia.org/wiki/Satellite_Catalog_Number) 相關聯的[雙行元素集 (TLEs)](https://en.wikipedia.org/wiki/Two-line_element_set)。所有預設 ephemeride 的優先順序為 `0`。因此，透過 ephemeris API 上傳的任何未過期自訂 ephemeride 一律會予以覆寫，其優先順序必須為 `1`或更高。
沒有 NORAD ID 的衛星必須將自訂 ephemeris 資料上傳至其中 AWS Ground Station。例如，剛啟動或刻意從 [Space-Track](https://www.space-track.org/) 目錄省略的衛星不會有 NORAD ID，而且需要上傳自訂的短暫性。如需提供自訂暫時性資料的詳細資訊，請參閱：[提供自訂暫時性資料](providing-custom-ephemeris-data.md)。
# 提供自訂暫時性資料
**重要**
ephemeris API 目前處於預覽狀態
僅在需要時提供對 Ephemeris API 的存取。如果您需要上傳自訂暫時性資料的功能，請透過 開立 AWS 支援 票證[AWS Support Center Console](https://console.aws.amazon.com/support)。您的團隊將與您合作，為您的特定需求啟用此功能。
## 概觀
Ephemeris API 允許將自訂暫時性化上傳到 AWS Ground Station ，以便與衛星搭配使用。這些暫時性物質會覆寫來自 [Space-Track](https://www.space-track.org/) 的預設暫時性物質 （請參閱：[預設暫時性資料](default-ephemeris-data.md))。我們支援以 Orbit Ephemeris Message (OEM)、雙行元素 (TLE) 和方位提升格式接收暫時性資料。
AWS Ground Station 將 ephemerides 視為[個人化用量資料](https://aws.amazon.com/service-terms)。如果您使用此選用功能，AWS 將使用 ephemeris 資料來提供故障診斷支援。
上傳自訂暫時性資料可以改善追蹤品質、處理沒有可用 [Space-Track](https://www.space-track.org/) 暫時性資料的操作 AWS Ground Station，以及考慮操作。
若要對無效的暫時性事件進行故障診斷，請參閱： [故障診斷無效的短暫性事件](troubleshooting-invalid-ephemerides.md)
## 範例：搭配 使用客戶提供的 ephemeride AWS Ground Station
如需搭配 使用客戶提供的暫時性資料的詳細指示 AWS Ground Station，請參閱[搭配 使用客戶提供的暫時性資料 AWS Ground Station](https://aws.amazon.com/blogs/publicsector/using-customer-provided-ephemerides-with-aws-ground-station/)，以及其相關聯的 GitHub 儲存庫 [aws-samples/aws-groundstation-cpe](https://github.com/aws-samples/aws-groundstation-cpe)。
# 提供 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，以及處理操作。
**注意**
在為衛星指派衛星目錄號碼之前提供自訂 ephemeris 時，您可以將 `00000` 用於 TLE 的衛星目錄號碼欄位，以及 `000` TLE 國際指標欄位的啟動號碼部分 （例如， `24000A` 用於 2024 年啟動的車輛）。
如需 TLEs 格式的詳細資訊，請參閱[雙行元素集](https://en.wikipedia.org/wiki/Two-line_element_set)。
## 建立 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']}")
```
# 提供 OEM ephemeris 資料
**重要**
ephemeris API 目前處於預覽狀態
僅在需要時提供對 Ephemeris API 的存取。如果您需要上傳自訂暫時性資料的功能，請透過 開立 AWS 支援 票證[AWS Support Center Console](https://console.aws.amazon.com/support)。您的團隊將與您合作，為您的特定需求啟用此功能。
## 概觀
Orbit Ephemeris Message (OEM) 是一種標準化格式，用於表示太空船軌跡資料。Ephemeris API 可讓 OEM 暫時性資料上傳到 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 資料來提供故障診斷支援。
上傳自訂 OEM 暫時化可以改善追蹤品質、處理沒有可用 [Space-Track](https://www.space-track.org/) 暫時化的早期操作 AWS Ground Station，以及計算操作。
**注意**
在為衛星指派衛星目錄號碼之前提供自訂 ephemeris 時，您可以將 `satelliteId`用於 OEM `OBJECT_ID`的部分。
如需 OEMs 格式的詳細資訊，請參閱 [OEM ephemeris 格式](#oem-ephemeris-format)。
## OEM ephemeris 格式
AWS Ground Station 根據 [CCSDS 標準](https://ccsds.org/Pubs/502x0b3e1.pdf)處理 OEM 客戶提供的 Ephemerides，但有一些額外的限制。OEM 檔案應為 KVN 格式。下表概述 OEM 中的不同欄位，以及 與 CCSDS 標準 AWS Ground Station 的差異。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/ground-station/latest/ug/providing-oem-ephemeris-data.html)
\$1 如果提供 OEM 中 AWS Ground Station 包含 不支援的任何資料列，OEM 將驗證失敗。
與 的 CCSDS 標準的重要偏差 AWS Ground Station 為：
+ `CCSDS_OEM_VERS` 必須是 `2.0`。
+ `REF_FRAME` 必須是 `EME2000`或 ` ITRF2000`。
+ `REF_FRAME_EPOCH` 不支援 AWS Ground Station。
+ `CENTER_NAME` 必須是 `Earth`。
+ `TIME_SYSTEM` 必須是 `UTC`。
+ `INTERPOLATION` 和 `INTERPOLATION_DEGREE` 都是 AWS Ground Station 客戶提供的 ephemeris 的必要項目。
## KVN 格式的範例 OEM ephemeris
以下是 JPSS-1 公有廣播者衛星的 KVN 格式 OEM ephemeris 截斷範例。
```
CCSDS_OEM_VERS = 2.0
COMMENT Orbit data are consistent with planetary ephemeris DE-430
CREATION_DATE = 2024-07-22T05:20:59
ORIGINATOR = Raytheon-JPSS/CGS
META_START
OBJECT_NAME = J1
OBJECT_ID = 2017-073A
CENTER_NAME = Earth
REF_FRAME = EME2000
TIME_SYSTEM = UTC
START_TIME = 2024-07-22T00:00:00.000000
STOP_TIME = 2024-07-22T00:06:00.000000
INTERPOLATION = Lagrange
INTERPOLATION_DEGREE = 5
META_STOP
2024-07-22T00:00:00.000000 5.905147360000000e+02 -1.860082793999999e+03 -6.944807075000000e+03 -5.784245796000000e+00 4.347501391999999e+00 -1.657256863000000e+00
2024-07-22T00:01:00.000000 2.425572045154201e+02 -1.595860765983339e+03 -7.030938457373539e+03 -5.810660250794190e+00 4.457103652219009e+00 -1.212889340333023e+00
2024-07-22T00:02:00.000000 -1.063224256538050e+02 -1.325569732497146e+03 -7.090262617183503e+03 -5.814973972202444e+00 4.549739160042560e+00 -7.639633689161465e-01
2024-07-22T00:03:00.000000 -4.547973959231161e+02 -1.050238305712201e+03 -7.122556683227951e+03 -5.797176562437553e+00 4.625064829516728e+00 -3.121687831090774e-01
2024-07-22T00:04:00.000000 -8.015427368657785e+02 -7.709137891269565e+02 -7.127699477194810e+03 -5.757338007808417e+00 4.682800822515077e+00 1.407953645161997e-01
2024-07-22T00:05:00.000000 -1.145240083085062e+03 -4.886583601179489e+02 -7.105671911254255e+03 -5.695608435738609e+00 4.722731329786999e+00 5.932259682105052e-01
2024-07-22T00:06:00.000000 -1.484582479061495e+03 -2.045451985605701e+02 -7.056557069672793e+03 -5.612218005854990e+00 4.744705579872771e+00 1.043421397392599e+00
```
## 建立 OEM ephemeris
OEM ephemeris 可以使用 API 中的 AWS Ground Station [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 動作建立。此動作將使用請求內文中的資料或從指定的 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)
## 範例：從 S3 儲存貯體上傳 OEM ephemeris 資料
您也可以透過指向儲存貯體和物件金鑰，直接從 S3 儲存貯體上傳 OEM ephemeris 檔案。 AWS Ground Station 將代表您擷取物件。有關 中靜態資料加密的詳細資訊 AWS Ground Station ，請參閱：[的靜態資料加密 AWS Ground Station](security.encryption-at-rest.md)。
以下是從 S3 儲存貯體上傳 OEM ephemeris 檔案的範例
```
import boto3
from datetime import datetime, timedelta, timezone
# 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.oem"
# Create sample OEM data in KVN format
oem_data = """CCSDS_OEM_VERS = 2.0
COMMENT Orbit data are consistent with planetary ephemeris DE-430
CREATION_DATE = 2024-07-22T05:20:59
ORIGINATOR = Raytheon-JPSS/CGS
META_START
OBJECT_NAME = J1
OBJECT_ID = 2017-073A
CENTER_NAME = Earth
REF_FRAME = EME2000
TIME_SYSTEM = UTC
START_TIME = 2024-07-22T00:00:00.000000
STOP_TIME = 2024-07-22T00:06:00.000000
INTERPOLATION = Lagrange
INTERPOLATION_DEGREE = 5
META_STOP
2024-07-22T00:00:00.000000 5.905147360000000e+02 -1.860082793999999e+03 -6.944807075000000e+03 -5.784245796000000e+00 4.347501391999999e+00 -1.657256863000000e+00
2024-07-22T00:01:00.000000 2.425572045154201e+02 -1.595860765983339e+03 -7.030938457373539e+03 -5.810660250794190e+00 4.457103652219009e+00 -1.212889340333023e+00
2024-07-22T00:02:00.000000 -1.063224256538050e+02 -1.325569732497146e+03 -7.090262617183503e+03 -5.814973972202444e+00 4.549739160042560e+00 -7.639633689161465e-01
2024-07-22T00:03:00.000000 -4.547973959231161e+02 -1.050238305712201e+03 -7.122556683227951e+03 -5.797176562437553e+00 4.625064829516728e+00 -3.121687831090774e-01
2024-07-22T00:04:00.000000 -8.015427368657785e+02 -7.709137891269565e+02 -7.127699477194810e+03 -5.757338007808417e+00 4.682800822515077e+00 1.407953645161997e-01
2024-07-22T00:05:00.000000 -1.145240083085062e+03 -4.886583601179489e+02 -7.105671911254255e+03 -5.695608435738609e+00 4.722731329786999e+00 5.932259682105052e-01
2024-07-22T00:06:00.000000 -1.484582479061495e+03 -2.045451985605701e+02 -7.056557069672793e+03 -5.612218005854990e+00 4.744705579872771e+00 1.043421397392599e+00
"""
# Upload sample OEM data to S3
print(f"Uploading OEM data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=oem_data, ContentType="text/plain"
)
print("OEM data uploaded successfully to S3")
# Create OEM ephemeris from S3
print("Creating OEM ephemeris from S3...")
s3_oem_ephemeris = ground_station_client.create_ephemeris(
name="2024-07-22 S3 OEM Upload",
satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=5),
priority=2,
ephemeris={"oem": {"s3Object": {"bucket": bucket_name, "key": object_key}}},
)
print(f"Created OEM ephemeris with ID: {s3_oem_ephemeris['ephemerisId']}")
```
以下是從 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 動作傳回的資料範例，該動作會針對上一個範例程式碼區塊中上傳的 OEM ephemeris 呼叫。
```
{
"creationTime": 1620254718.765,
"enabled": true,
"name": "Example Ephemeris",
"ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE02",
"priority": 2,
"status": "VALIDATING",
"suppliedData": {
"oem": {
"sourceS3Object": {
"bucket": "ephemeris-bucket-for-testing",
"key": "test_data.oem"
}
}
}
}
```
# 提供方位提升暫時性資料
**重要**
方位提升暫時性特徵目前處於預覽狀態，需要明確加入。
對於有限數量的預先確定、專門的使用案例，方位提升暫時性功能受到嚴格的存取控制。存取比標準客戶提供的暫時性功能更嚴格。如需已核准使用案例和存取請求程序的詳細資訊，請透過 開立 AWS 支援 票證[AWS Support Center Console](https://console.aws.amazon.com/support)。您的團隊將引導您完成特殊使用案例的核准程序。
## 概觀
方位角抬高暫時性提供一個直接指定天線指向方向的方法，而無需提供衛星軌道資訊。您不用上傳描述衛星軌道的暫時性資料，而是提供標記時間的方位角和高度角度，告訴天線在聯絡過程中的確切位置。
AWS Ground Station 將 ephemerides 視為[個人化用量資料](https://aws.amazon.com/service-terms)。如果您使用此選用功能，AWS 將使用 ephemeris 資料來提供故障診斷支援。
此方法在下列案例中特別有用：
+ *早期操作支援：*在啟動和早期軌道階段 (LEOP) 期間，當無法使用精確的軌道資料，或軌道參數快速變更時。
+ *自訂指標模式：*實作特定指標序列進行天線測試或非標準操作。
**注意**
使用方位提升暫時性時，可能會從聯絡人保留請求中省略衛星 ARN。如果未省略衛星 ARN，它仍會包含在聯絡資料中，但方位角抬高暫時符號將用於天線指向，而不是執行暫時優先順序解析。方位角海拔高度與特定地面站相關聯，並定義該位置的天線指向方向。
## 方位浮水印資料格式
方位海拔暫時性資料由時間標記方位和海拔值組成，組織成區段。每個區段都包含涵蓋特定時間範圍的一系列方位角和高度角。
方位海拔暫時性資料的關鍵元件為：
+ *Ground Station：*將使用此方位角海拔碎片的特定地面工作站。
+ *角度單位：*角度的測量單位 (`DEGREE_ANGLE` 或 `RADIAN`)。
+ *區段：*一個或多個時間限制的方位角和高度角度集合。
+ *時間標記角度：*具有相關聯時間戳記的個別方位和高度值。
每個區段都需要：
+ 參考 epoch （區段的基本時間）
+ 有效的時間範圍 （區段的開始和結束時間）
+ 至少 5 個時間標記方位/上升對
方位提升限制條件：
+ 方位度：-180° 到 360°
+ 弧度的方位：-π 到 2π
+ 上升度數：-90° 到 90°
+ 弧度的上升：-π/2 到 π/2
+ 時間值必須在每個區段內以遞增順序排列
+ 區段不得在時間上重疊
如需詳細資訊，請參閱 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API 文件和 [TimeAzEl](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_TimeAzEl.html) 資料類型。
## 建立方位提升暫時性
方位浮水印是使用相同的 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API 動作建立，但使用 ephemeris `azEl` 類型。與 TLE 和 OEM 暫時性差異的主要差異為：
+ 您必須指定`groundStation`參數
+ 必須從請求中省略 `satelliteId` 參數
+ 優先順序設定不適用 （每個方位方位海拔暫時性都專屬於地面站）
+ 每個區段必須至少包含 5 個方位/上升點，以支援第 4 個順序的延遲插補
+ [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API 文件中詳細說明了其他限制和要求
請務必注意，上傳 ephemeris 會將 ephemeris 設定為 ，`VALIDATING`並啟動非同步工作流程，以驗證和產生來自 ephemeris 的潛在聯絡人。只有在聯絡人通過此工作流程且其狀態變為 後，才會使用暫時性聯絡人`ENABLED`。您應該輪詢 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 以取得暫時性狀態，或使用 CloudWatch 事件來追蹤暫時性狀態變更。
若要對無效的暫時性事件進行故障診斷，請參閱： [故障診斷無效的短暫性事件](troubleshooting-invalid-ephemerides.md)
## 範例：透過 API 建立方位角海拔暫時性
下列範例示範如何使用適用於 Python 的 AWS SDK (Boto3) 建立方位方位海拔假影：
```
import boto3
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Ohio Ground Station",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
print(f"Created ephemeris with ID: {azimuth_elevation_ephemeris['ephemerisId']}")
```
在此範例中：
+ 方位海拔資料與「俄亥俄 1」地面站相關聯
+ 角度以度為單位指定
+ 此區段涵蓋 15 分鐘的期間
+ 這些`dt`值是與參考 epoch 的原子秒位移
+ 提供六個方位/上升對 （最小值為 5)
## 範例：從 S3 上傳方位提升資料
對於較大的資料集，您可以從 S3 儲存貯體上傳方位提升資料：
```
import boto3
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "azimuth-elevation-bucket"
object_key = "singapore-azimuth-elevation.json"
# Create sample azimuth elevation data
azimuth_elevation_data = {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
},
{
"referenceEpoch": "2024-03-15T10:15:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:15:00Z",
"endTime": "2024-03-15T10:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 70.0, "el": 35.0},
{"dt": 180.0, "az": 75.0, "el": 40.0},
{"dt": 360.0, "az": 80.0, "el": 45.0},
{"dt": 540.0, "az": 85.0, "el": 50.0},
{"dt": 720.0, "az": 90.0, "el": 55.0},
{"dt": 900.0, "az": 95.0, "el": 50.0},
],
},
],
}
# Upload sample data to S3
print(f"Uploading azimuth elevation data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name,
Key=object_key,
Body=json.dumps(azimuth_elevation_data, indent=2),
ContentType="application/json",
)
print("Sample data uploaded successfully to S3")
# Create azimuth elevation ephemeris from S3
print("Creating azimuth elevation ephemeris from S3...")
s3_azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Large Azimuth Elevation Dataset",
ephemeris={
"azEl": {
"groundStation": "Singapore 1",
"data": {"s3Object": {"bucket": bucket_name, "key": object_key}},
}
},
)
print(f"Created ephemeris with ID: {s3_azimuth_elevation_ephemeris['ephemerisId']}")
```
S3 物件應該包含 JSON 結構，其中包含與直接上傳範例中所示相同格式的方位角海拔資料。
## 保留具有方位海拔暫時性的聯絡人
使用方位角海拔高度來保留聯絡人時，程序會與 TLE 和 OEM ephemeris 不同：
1. 使用 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 建立方位角海拔高度
1. 等待 ephemeris 達到`ENABLED`狀態
1. 使用 [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) 搭配追蹤覆寫來預留聯絡人
預留與方位海拔暫時性接觸的範例：
```
import boto3
from datetime import datetime
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create an azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
create_ephemeris_response = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Contact Reservation",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = create_ephemeris_response["ephemerisId"]
print(f"Created ephemeris with ID: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Reserve contact with azimuth elevation ephemeris
print("Reserving contact...")
contact = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-mission-profile",
groundStation="Ohio 1",
startTime=datetime(2024, 3, 15, 10, 0, 0),
endTime=datetime(2024, 3, 15, 10, 15, 0),
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact with ID: {contact['contactId']}")
```
**注意**
保留與方位角海拔暫時性的聯絡人時，可能會省略 `satelliteArn` 參數。天線會在聯絡期間遵循指定的方位角和高度角度。
## 列出可用的聯絡人
使用方位提升暫時性時，[ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) API 需要特定參數：
+ 請求可能會省略 `satelliteArn` 參數
+ 您必須提供具有方位角海拔 ephemeris ID 的 `ephemeris` 參數，以指定要使用的 ephemeris
+ 可用的聯絡時段會顯示提供的方位角和高度角度何時高於所請求地面站的[站點遮罩](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html)
+ 您仍然必須提供 `groundStation`和 `missionProfileArn`
建立方位角海拔暫時性並列出可用聯絡人的範例：
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Step 1: Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Stockholm AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Stockholm 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-04-01T12:00:00Z",
"validTimeRange": {
"startTime": "2024-04-01T12:00:00Z",
"endTime": "2024-04-01T12:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 30.0, "el": 15.0},
{"dt": 360.0, "az": 45.0, "el": 30.0},
{"dt": 720.0, "az": 60.0, "el": 45.0},
{"dt": 1080.0, "az": 75.0, "el": 35.0},
{"dt": 1440.0, "az": 90.0, "el": 20.0},
{"dt": 1800.0, "az": 105.0, "el": 10.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Step 2: Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
describe_response = ground_station_client.describe_ephemeris(
ephemerisId=ephemeris_id
)
status = describe_response["status"]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
# Check for validation errors
if "invalidReason" in describe_response:
print(f"Ephemeris validation failed: {describe_response['invalidReason']}")
raise RuntimeError(f"Ephemeris failed with status: {status}")
print(f"Current status: {status}, waiting...")
time.sleep(5)
# Step 3: List available contacts using the azimuth elevation ephemeris
print("Listing available contacts with azimuth elevation ephemeris...")
# Convert epoch timestamps to datetime objects
start_time = datetime.fromtimestamp(1760710513, tz=timezone.utc)
end_time = datetime.fromtimestamp(1760883313, tz=timezone.utc)
contacts_response = ground_station_client.list_contacts(
startTime=start_time,
endTime=end_time,
groundStation="Stockholm 1",
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
# satelliteArn is optional
satelliteArn="arn:aws:groundstation::111122223333:satellite/a88611b0-f755-404e-b60d-57d8aEXAMPLE",
missionProfileArn="arn:aws:groundstation:eu-north-1:111122223333:mission-profile/966b72f6-6d82-4e7e-b072-f8240EXAMPLE",
)
# Process the results
if contacts_response["contactList"]:
print(f"Found {len(contacts_response['contactList'])} available contacts:")
for contact in contacts_response["contactList"]:
print(f" - Contact from {contact['startTime']} to {contact['endTime']}")
print(
f" Max elevation: {contact.get('maximumElevation', {}).get('value', 'N/A')}°"
)
else:
print("No available contacts found for the specified azimuth elevation ephemeris")
```
**注意**
列出聯絡人時，必須提供具有方位提升 ID 的 `ephemeris` 參數，以指定應使用哪個方位提升暫時性來判斷聯絡時段。如果`satelliteArn`包含 ，則會與聯絡人資料建立關聯，但方位海拔暫時性符號將用於天線指向，而不是執行暫時性優先順序解析。
# 使用自訂 ephemeris 預留聯絡人
## 概觀
使用自訂 ephemeris (TLE、OEM 或方位提升） 時，您可以使用 [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) API 保留聯絡人。本節說明兩種保留聯絡人的常見工作流程，以及確保成功安排聯絡人的重要考量事項。
AWS Ground Station 天線是多個客戶的共用資源。這表示即使聯絡人時段在您列出聯絡人時出現，其他客戶仍可能會在您之前保留該時段。因此，請務必確認您的聯絡人在保留後達到 `SCHEDULED` 狀態，並針對聯絡狀態變更實作適當的監控。
**重要**
對於方位提升暫時性，可能會從`ReserveContact`請求中省略 `satelliteArn` 參數，而且您必須`trackingOverrides`提供暫時性 ID。對於 TLE 和 OEM ephemeris，您仍然需要提供 `satelliteArn`。
## 聯絡預留工作流程
使用自訂 ephemeris 預留聯絡人有兩個主要工作流程：
1. *List-then-reserve 工作流程：*先使用 [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) 列出可用的聯絡時段，然後選取並預留特定時段。當您想要在選擇之前查看所有可用的機會時，此方法非常有用。
1. *直接保留工作流程：*直接保留特定時段的聯絡人，而不先列出可用的聯絡人。當您已經知道所需的聯絡時間或正在使用預先決定的排程時，此方法很有用。
這兩個工作流程都是有效的，選擇取決於您的操作需求。下列各節提供每種方法的範例。
## 工作流程 1：列出可用的聯絡人，然後保留
此工作流程會先查詢可用的聯絡時段，然後保留特定的時段。當您想要在選擇之前查看所有可用的機會時，此功能非常有用。
### 範例：列出並預留方位角海拔高度
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="AzEl Ephemeris for Contact",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
contacts = ground_station_client.list_contacts(
# Note: satelliteArn is omitted for azimuth elevation ephemeris
groundStation="Ohio 1",
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
startTime=datetime(2024, 3, 15, 10, 0, 0, tzinfo=timezone.utc),
endTime=datetime(2024, 3, 15, 10, 15, 0, tzinfo=timezone.utc),
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
trackingOverrides={
"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}
},
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
### 範例：使用 TLE ephemeris 列出和保留
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="TLE Ephemeris for Contact",
satelliteId=satellite_id,
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=7),
priority=1, # Higher priority than default ephemeris
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24075.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 = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
start_time = datetime.now(timezone.utc) + timedelta(hours=1)
end_time = start_time + timedelta(days=1)
contacts = ground_station_client.list_contacts(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
groundStation="Hawaii 1",
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
startTime=start_time,
endTime=end_time,
statusList=["AVAILABLE"],
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
# Note: trackingOverrides is optional for TLE/OEM
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
## 工作流程 2：直接聯絡預留
此工作流程會直接保留聯絡人，而不會先列出可用的時段。當您已經知道所需的聯絡時間或正在實作自動化排程時，此方法很有用。
### 範例：使用方位角海拔凹凸直接保留
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Define contact window
contact_start = datetime(2024, 3, 20, 14, 0, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 20, 14, 15, 0, tzinfo=timezone.utc)
# Create azimuth elevation ephemeris for the specific contact time
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": contact_start.isoformat(),
"validTimeRange": {
"startTime": contact_start.isoformat(),
"endTime": contact_end.isoformat(),
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted for azimuth elevation
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact_start,
endTime=contact_end,
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact: {reservation['contactId']}")
```
### 範例：使用 TLE ephemeris 直接保留
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Define contact window (based on predicted pass)
contact_start = datetime(2024, 3, 21, 10, 30, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 21, 10, 42, 0, tzinfo=timezone.utc)
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact TLE Ephemeris",
satelliteId=satellite_id,
enabled=True,
expirationTime=contact_end + timedelta(days=1),
priority=1,
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24080.50000000 .00000075 00000-0 26688-4 0 9999",
"tleLine2": "2 25994 98.2007 35.6589 0001234 89.2782 18.9934 14.57114995112000",
"validTimeRange": {
"startTime": (contact_start - timedelta(hours=1)).isoformat(),
"endTime": (contact_end + timedelta(hours=1)).isoformat(),
},
}
]
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact_start,
endTime=contact_end,
# Note: trackingOverrides is optional for TLE
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
```
## 監控聯絡狀態變更
保留聯絡人之後，請務必監控其狀態，以確保其成功轉換為 ，`SCHEDULED`並在發生任何問題時收到通知。 會向 Amazon EventBridge AWS Ground Station 發出所有聯絡人狀態變更的事件。
聯絡狀態遵循此生命週期：
+ `SCHEDULING` - 正在處理聯絡人以進行排程
+ `SCHEDULED` - 已成功排程聯絡人並將執行
+ `FAILED_TO_SCHEDULE` - 無法排程聯絡人 （終端狀態）
如需聯絡狀態和生命週期的詳細資訊，請參閱 [了解聯絡生命週期](contacts.lifecycle.md)。
### 使用 EventBridge 實作聯絡狀態監控
若要即時監控聯絡狀態變更，您可以設定每當 Ground Station 聯絡狀態變更時觸發 Lambda 函數的 Amazon EventBridge 規則。相較於輪詢聯絡狀態，此方法更有效率且可擴展。
#### 實作步驟
1. 建立 Lambda 函數來處理聯絡狀態變更事件
1. 建立符合 Ground Station 聯絡狀態變更事件的 EventBridge 規則
1. 新增 Lambda 函數做為規則的目標
#### Lambda 函數處理常式範例
如需處理聯絡狀態變更事件的 Lambda 函數完整範例，請參閱 `AquaSnppJpssTerraDigIF.yml` CloudFormation 範本中的 `GroundStationCloudWatchEventHandlerLambda` 資源。此範本可在 AWS Ground Station 客戶加入 Amazon S3 儲存貯體中取得。如需存取此範本的指示，請參閱資料流程端點範例的 [將它放在一起](examples.pbs-data-dataflow-endpoint.md#examples.pbs-dataflow-endpoint.putting-it-together)一節。
#### EventBridge 規則組態
EventBridge 規則應使用下列事件模式，以符合所有 Ground Station 聯絡狀態變更：
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"]
}
```
若要篩選特定狀態 （例如失敗），您可以新增詳細資訊篩選條件：
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"],
"detail": {
"contactStatus": [
"FAILED_TO_SCHEDULE",
"FAILED",
"AWS_FAILED",
"AWS_CANCELLED"
]
}
}
```
如需使用 Lambda 目標建立 EventBridge 規則的詳細說明，請參閱《Amazon EventBridge 使用者指南》中的[建立對事件做出反應的規則](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html)。
### 設定用於自動化的 EventBridge 規則
您可以建立 EventBridge 規則，以自動回應聯絡狀態變更。例如：
+ 當聯絡人無法排程時傳送通知
+ 觸發 Lambda 函數，以在聯絡進入時準備資源 `PREPASS`
+ 記錄聯絡完成以進行稽核
如需設定 AWS Ground Station 事件的 EventBridge 規則的詳細資訊，請參閱 [AWS Ground Station 使用 事件自動化](monitoring.automating-events.md)。
## 最佳實務和考量
### 處理排程衝突
由於 AWS Ground Station 天線是共用資源，因此在 中出現的聯絡時段`ListContacts`可能由其他客戶保留，然後才能進行保留。若要處理此問題：
1. 保留後一律檢查聯絡狀態
1. 使用替代時段實作重試邏輯
1. 可能的話，請考慮提前預留聯絡人
1. 使用 EventBridge 事件來監控`FAILED_TO_SCHEDULE`狀態
### Ephemeris 驗證時間
請記住，ephemeris 必須處於 `ENABLED` 狀態，才能使用它來保留聯絡人。根據暫時性的類型和大小，驗證程序通常需要幾秒鐘到幾分鐘的時間。在嘗試保留聯絡人之前，請務必驗證暫時性狀態。
### 聯絡時間考量事項
使用自訂 ephemeris 時：
+ 確保您的暫時性接觸涵蓋整個聯絡持續時間
+ 對於方位角升高暫時性，請確認在整個接觸過程中，角度將天線保持在[站點遮罩](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html)上方
+ 安排未來聯絡時，請考慮暫時性過期時間
### 依暫時性差異類型的 API 差異
`ReserveContact` API 的行為會因 ephemeris 類型而有所不同：
| Ephemeris 類型 | satelliteArn 必要 | trackingOverrides 必要 |
| --- | --- | --- |
| TLE | 是 | 否 （選用） |
| OEM | 是 | 否 （選用） |
| 方位上升 | 否 （選用） | 是 |
# 了解使用哪些 ephemeris
Ephemerides 具有*優先順序*、*過期時間和**啟用*的旗標。這些共同決定了在聯絡期間用於追蹤的暫時性事件。
## TLE 和 OEM 暫時化
對於 OEM 和 TLE 暫時性資料，每個衛星只能有一個暫時性資料處於作用中狀態。將使用的暫時性資料是啟用最高優先順序的暫時性資料，其過期時間是未來的時間。優先順序值越大表示優先順序越高。[ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) 傳回的可用聯絡時間是以此暫時性為基礎。如果多個 `ENABLED` ephemeride 具有相同的優先順序，則會使用最近建立或更新的 ephemeris。
**注意**
AWS Ground Station 對每個衛星`ENABLED`客戶提供的短暫性數量具有服務配額 （請參閱：[Service Quotas](https://docs.aws.amazon.com/general/latest/gr/gs.html))。若要在達到此配額後上傳暫時性資料，請刪除 （使用 [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html)) 或停用 （使用 [UpdateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateEphemeris.html)) 最低優先順序/最早建立的客戶提供暫時性資料。
如果未建立暫時性資料，或者如果沒有暫時性資料具有`ENABLED`狀態，則如果可用， AWS Ground Station 將使用衛星的預設暫時性資料 （來自 [Space-Track](https://www.space-track.org/))。此預設 ephemeris 的優先順序為 0。
## 方位海拔半合子
方位角升高環冪化物的運作方式與 OEM 和 TLE 環冪化物不同。每個方位方位海拔碎片都與特定地面站相關聯，並且沒有優先順序。當您保留與方位角升高暫時性的接觸時，您會明確指定要透過 `trackingOverrides` 參數使用的方位角升高暫時性。
方位角海拔翅目的主要差異：
+ 無優先順序系統 - 您明確選取每個聯絡人的暫時性
+ 特定地面站 - 每個臨時工都與特定地面站相關聯
+ 無自動備用 - 如果指定的短暫性不可用，聯絡人將會失敗
**注意**
方位角海拔半合子不會與 OEM 和 TLE 半合子競爭。它們會在保留聯絡人時明確選取，並且僅在指定追蹤覆寫時使用。
## 新暫時性差異對先前排程聯絡人的影響
使用 [DescribeContact API](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html) 透過傳回作用中的可見性時間，來檢視新短暫性對先前排程聯絡人的影響。
對於 OEM 和 TLE 暫時性資料，上傳新暫時性資料之前排程的聯絡案例將保留最初排程的聯絡時間，而天線追蹤將使用作用中暫時性資料。如果太空船的位置根據作用中的暫時性差異很大，則由於太空船在傳輸/接收站點遮罩之外操作，這可能會導致與天線的衛星接觸時間縮短。因此，我們建議您在上傳與先前 ephemeris 有很大差異的新 ephemeris 之後，取消和重新排程未來的聯絡人。
使用 [DescribeContact API](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html)，您可以比較您的排程聯絡人`endTime`和傳回的 `visibilityStartTime` `startTime`和 ，以判斷因傳輸/接收網站遮罩外操作的太空船而無法使用的未來聯絡人部分`visibilityEndTime`。如果您選擇取消和重新排定未來的聯絡時間，則聯絡時間範圍不得超出可見性時間範圍超過 30 秒。取消太接近聯絡時間時，取消聯絡可能會產生費用。如需取消聯絡人的詳細資訊，請參閱：[Ground Station FAQs](https://aws.amazon.com/ground-station/faqs/)。
對於方位角海拔半合子，排程聯絡人將使用保留聯絡人時選取的特定半合子。如果您需要更新排程聯絡人的方位提升資料，您可以取消和重新排程具有新暫時性的聯絡人。
# 取得衛星的目前暫時性變化
呼叫 [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) 或 [ListSatellites](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListSatellites.html) 動作，即可擷取目前由 AWS Ground Station 用於特定衛星的短暫性。這兩種方法都會傳回目前使用中 ephemeris 的中繼資料。此暫時性中繼資料對於上傳至 的自訂暫時性中繼資料 AWS Ground Station 和預設暫時性中繼資料不同。
**注意**
方位浮水印不會與衛星相關聯，因此 [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) 或 [ListSatellites](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListSatellites.html) 不會傳回。若要擷取方位角海拔半合子的相關資訊，請使用 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) API 搭配特定半合子 ID，或使用 [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) 查看您帳戶的所有可用半合子。
預設對等詞只會包含 `source`和 `epoch` 欄位。`epoch` 是從 [Space-Track](https://www.space-track.org/) 提取的[雙行元素集](https://en.wikipedia.org/wiki/Two-line_element_set)的 [epoch](https://en.wikipedia.org/wiki/Epoch_(astronomy))，目前正在用於運算衛星的軌跡。
自訂 ephemeris `source`的值為 ，`CUSTOMER_PROVIDED`並在 `ephemerisId` 欄位中包含唯一識別符。此唯一識別符可用於透過 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 動作查詢 ephemeris。如果在 AWS Ground Station 透過 [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 動作上傳至 期間為 ephemeris 指派名稱，則會傳回選用`name`欄位。
請務必注意，暫時性資料是由 動態更新， AWS Ground Station 因此傳回的資料只是呼叫 API 時正在使用暫時性資料的快照。
## 使用預設 ephemeris 的衛星 [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) 傳回範例
```
{
"satelliteId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"satelliteArn": "arn:aws:groundstation::111122223333:satellite/e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"noradSatelliteID": 25994,
"groundStations": [
"Ohio 1",
"Oregon 1"
],
"currentEphemeris": {
"source": "SPACE_TRACK",
"epoch": 1528245583.619
}
}
```
## 使用自訂 ephemeris 的衛星 [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) 範例
```
{
"satelliteId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"satelliteArn": "arn:aws:groundstation::111122223333:satellite/e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"noradSatelliteID": 25994,
"groundStations": [
"Ohio 1",
"Oregon 1"
],
"currentEphemeris": {
"source": "CUSTOMER_PROVIDED",
"ephemerisId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"name": "My Ephemeris"
}
}
```
## 列出方位角海拔環冪化物
由於方位角海拔半合子與衛星無關，您需要使用不同的 APIs 來探索和擷取有關它們的資訊：
1. 使用 [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) 列出您 帳戶中的所有環數，包括方位角海拔環數。您可以依狀態和暫時性類型進行篩選。
1. 使用 [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 搭配特定 ephemeris ID 來取得方位海拔 ephemeris 的詳細資訊。
1. 使用 [DescribeContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html) 搭配特定聯絡人 ID，以取得用於聯絡人的暫時性詳細資訊。
[ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) 回應範例，包括方位角海拔暫時性：
```
{
"ephemerides": [
{
"ephemerisId": "abc12345-6789-def0-1234-5678EXAMPLE",
"ephemerisType": "AZ_EL",
"name": "Azimuth Elevation for Ohio Ground Station",
"status": "ENABLED",
"creationTime": 1620254718.765
},
{
"ephemerisId": "def45678-9012-abc3-4567-8901EXAMPLE",
"ephemerisType": "TLE",
"name": "TLE for Satellite 12345",
"status": "ENABLED",
"creationTime": 1620254700.123
}
]
}
```
**注意**
在 [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) 回應中，方位角海拔半合子將具有 `groundStation` 欄位，而不是 `satelliteId` 欄位，使其易於識別。
# 還原至預設 ephemeris 資料
當您上傳自訂 ephemeris 資料時，它會覆寫該特定衛星 AWS Ground Station 使用的預設 ephemeride。 AWS Ground Station 不會再次使用預設 ephemeride，直到目前沒有啟用、未過期的客戶所提供 ephemeride 可供使用為止。 AWS Ground Station 也不會列出超過目前客戶所提供 ephemeris 過期時間的聯絡人，即使該過期時間後仍有預設 ephemeris 可用。
**注意**
方位角海拔半合子沒有預設值，也不會覆寫衛星半合子。使用 `trackingOverrides` 參數保留聯絡人時，系統會明確選取這些項目。如果您不想再使用方位浮水印，只需保留聯絡人而不指定追蹤覆寫，系統會改用作用中的衛星浮水印。
## 還原 TLE 和 OEM 暫時化
若要還原至衛星的預設 [Space-Track](https://www.space-track.org/) 暫時化，您需要執行下列其中一項操作：
+ 刪除 （使用 [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html)) 或停用 （使用 [UpdateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateEphemeris.html)) 所有已啟用客戶提供的暫時性資料。您可以使用 [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) 列出客戶提供的衛星短暫性。
+ 等待所有現有客戶提供的暫時性資料過期。
您可以呼叫 [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) 並驗證衛星目前 ephemeris `source`的 為 ，以確認正在使用預設 ephemeris`SPACE_TRACK`。如需預設暫時性化的詳細資訊[預設暫時性資料](default-ephemeris-data.md)，請參閱 。
## 管理方位角升高環冪化物
由於每個聯絡人都明確選取方位角海拔短暫性，並且與衛星沒有關聯，因此沒有「還原」為預設值的概念。反之，您可以管理方位角海拔環冪化物，如下所示：
+ *若要停止使用方位提升暫時性：*只需保留新的聯絡人，而不指定 `trackingOverrides` 。 `satelliteArn`聯絡人將改為為指定的衛星使用作用中的 ephemeris。
+ *若要移除未使用的方位角海拔半合子：*使用 [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html) 刪除不再需要的方位角海拔半合子。請注意，您無法刪除排程聯絡人目前正在使用的 ephemeris。
若要列出您帳戶中的所有方位方位海拔半合子，請使用 [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html)。方位海拔半合子可以透過 `ephemerisType` 欄位識別，或是透過`groundStation`回應`satelliteId`中欄位的存在來識別。