本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 更新聯絡人和聯絡人版本控制
AWS Ground Station 支援更新具有 `SCHEDULED`、 `PREPASS`或 聯絡人狀態的`PASS`聯絡人。 [AWS Ground Station 聯絡狀態](contacts.lifecycle.md#contact-statuses)您可以使用 [UpdateContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateContact.html) API 來指定聯絡人的暫時性覆寫，包括方位/提升、OEM 或 TLE 追蹤資料，而無需取消和重新排程。這適用於需要在聯絡期間將天線重新任務到不同衛星的地理同步 (GEO) 衛星操作，或需要調整方向的啟動和早期操作 (LEOPs)。
每次您預留或更新聯絡人時， AWS Ground Station 都會建立新的聯絡人版本。聯絡版本提供對聯絡所做的變更歷史記錄，並可讓您追蹤每次更新的狀態。
## 聯絡版本控制的運作方式
當您呼叫 [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) 時， 會 AWS Ground Station 建立第一個版本的聯絡人 （第 1 版），並在回應`versionId`中傳回 。每次後續呼叫 [UpdateContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateContact.html) 時，都會以遞增的版本編號建立新的版本。
[DescribeContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html) API 會傳回目前的`ACTIVE`[聯絡版本](#contacts.versioning.version-statuses)，包括回應 `version` 欄位中的版本資訊。[ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) API 也包含每個聯絡人的版本資訊。
若要檢視特定版本的聯絡人，請使用 [DescribeContactVersion](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContactVersion.html) API。若要列出聯絡人的所有版本，請使用 [ListContactVersions](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContactVersions.html) API。
## 更新聯絡人
當聯絡人處於排程、 PREPASS 或 PASS 狀態時，您可以呼叫 [UpdateContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateContact.html)。API 接受下列參數：
+ **contactId** — 要更新的聯絡人識別符。
+ **clientToken** — 冪等字符，可確保僅處理請求一次。如果您使用相同的用戶端字符重試請求， 會 AWS Ground Station 傳回原始回應，而不會再次執行更新。如果未提供用戶端字符，則 AWS SDKs會自動為您產生用戶端字符。
+ **trackingOverrides** — 聯絡人的新追蹤組態。這包括程式追蹤設定 （方位/上升、TLE 或 OEM ephemeris)。
+ **satelliteArn** — 聯絡人的衛星 ARN。變更目標衛星與程式軌跡設定時，請提供新衛星的 ARN。只有核准方位角/上升指向角的客戶，才能將此值設定為 null。所有其他客戶必須包含聯絡人的衛星 ARN。
**重要**
`UpdateContact` API 會套用請求中的所有參數。省略或明確設定為 null 的任何參數都會視為清除該值的請求，而不會將其保持不變。例如，如果您提供 `trackingOverrides`但省略 `satelliteArn`，則會清除衛星 ARN。請務必在每個更新請求中包含所有所需的值。
您可以在聯絡期間透過提供新的 `satelliteArn`以及對應的 來變更目標衛星`trackingOverrides`。新的衛星必須在聯絡期間從地面工作站可見，因為聯絡開始和結束時間不會因此 API 而變更。新衛星也必須加入地面站點，並擁有任務設定檔所需的授權。聯絡人的任務描述檔無法變更，因此只有在兩個衛星都使用相同的任務描述檔時，切換衛星才適用。
**重要**
`UpdateContact` API 不支援變更聯絡人的開始時間、結束時間或任務設定檔。若要變更這些值，請取消聯絡人並保留新的聯絡人。`UpdateContact` API 旨在重新排序天線指向組態，例如在衛星之間切換或更新暫時性資料。
**重要**
`UpdateContact` API 不支援具有使用 [天線下行解調解碼組態](how-it-works.config.md#how-it-works.config-antenna-downlink-demod-decode) 組態之任務描述檔的聯絡人。若要變更這些聯絡人的組態，請取消聯絡人並保留新的聯絡人。
`UpdateContact` API 會傳回 `contactId`和新的 `versionId`。更新會以非同步方式處理。使用 [DescribeContactVersion](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContactVersion.html) 檢查更新的狀態。 AWS SDKs和 AWS Command Line Interface 提供輪詢的`ContactUpdated`等待程式，直到版本達到 ACTIVE 或 FAILED\_TO\_UPDATE 狀態為止。
**注意**
一次只能進行一個更新。如果最新的聯絡版本處於 UPDATING 狀態，API 會傳回 `ConflictException`。等待目前的更新達到 ACTIVE 或 FAILED\_TO\_UPDATE 狀態，再提交另一個更新。
## 聯絡版本狀態
每個聯絡版本都有下列其中一種狀態：
| 狀態 | Description |
| --- | --- |
| UPDATING | 正在將 版本套用至聯絡人。更新已提交並由 處理 AWS Ground Station。 |
| ACTIVE | 版本是聯絡人目前作用中的組態。地面工作站正在使用此版本的設定。 |
| SUPERSEDED (已取代) | 版本先前已啟用，但已被較新版本取代。 |
| FAILED\_TO\_UPDATE | 無法套用更新。聯絡人會還原至先前作用中的版本。如需詳細資訊，請參閱 failureCodes和 failureMessage 欄位。 |
## 程式碼範例
下列範例示範如何搭配適用於 Python APIs。 AWS
### 範例：更新聯絡人
下列範例會使用新的追蹤覆寫更新聯絡人，並等待使用 Boto3 `ContactUpdated`等待程式完成更新。
```
import boto3
import uuid
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# The contact ID of an existing scheduled contact to update
contact_id = "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
# Generate a unique client token for idempotency.
# If you retry the same request with the same client token,
# the API returns the same response without creating a duplicate version.
client_token = str(uuid.uuid4())
# Update the contact to use a different TLE ephemeris for tracking.
# The UpdateContact API applies all parameters in the request.
# Any parameter set to null is treated as a request to clear that value,
# not to leave it unchanged. Include all desired values in each request.
print(f"Updating contact {contact_id}...")
update_response = ground_station_client.update_contact(
contactId=contact_id,
clientToken=client_token,
satelliteArn="arn:aws:groundstation::111122223333:satellite/a88611b0-f755-404e-b60d-57d8aEXAMPLE",
trackingOverrides={
"programTrackSettings": {
"tle": {"ephemerisId": "b2c3d4e5-6789-01ab-cdef-EXAMPLE22222"}
}
},
)
contact_id = update_response["contactId"]
version_id = update_response["versionId"]
print(f"Update submitted. Contact: {contact_id}, Version: {version_id}")
# Wait for the update to complete using the ContactUpdated waiter.
# The waiter polls DescribeContactVersion until the version reaches
# ACTIVE (success) or FAILED_TO_UPDATE (failure) status.
# The waiter raises WaiterError if the version reaches FAILED_TO_UPDATE
# or if MaxAttempts is exceeded, so we use try/except to handle both cases.
print("Waiting for update to complete...")
from botocore.exceptions import WaiterError
waiter = ground_station_client.get_waiter("contact_updated")
try:
waiter.wait(
contactId=contact_id,
versionId=version_id,
WaiterConfig={
"Delay": 5,
"MaxAttempts": 180,
},
)
print(f"Contact updated successfully. Version {version_id} is now active.")
except WaiterError as e:
# WaiterError is raised when the version reaches FAILED_TO_UPDATE
# or when MaxAttempts is exceeded. Retrieve the current version to inspect.
version_response = ground_station_client.describe_contact_version(
contactId=contact_id,
versionId=version_id,
)
version_status = version_response["version"]["status"]
if version_status == "FAILED_TO_UPDATE":
failure_codes = version_response["version"].get("failureCodes", [])
failure_message = version_response["version"].get("failureMessage", "")
print(f"Update failed. Codes: {failure_codes}, Message: {failure_message}")
else:
print(f"Waiter timed out. Current version status: {version_status}. Error: {e}")
```
### 範例：描述聯絡版本
下列範例會擷取特定聯絡版本的詳細資訊，包括其狀態、組態和任何失敗資訊。
```
import boto3
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
contact_id = "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
version_id = 2
# Describe a specific version of a contact.
# Use this API to check the status of an update or to view the
# configuration that was active at a specific point in time.
print(f"Describing version {version_id} of contact {contact_id}...")
response = ground_station_client.describe_contact_version(
contactId=contact_id,
versionId=version_id,
)
# Display version details
version = response["version"]
print(f"Version ID: {version['versionId']}")
print(f"Status: {version['status']}")
print(f"Created: {version.get('created', 'N/A')}")
if version.get("activated"):
print(f"Activated: {version['activated']}")
if version.get("superseded"):
print(f"Superseded: {version['superseded']}")
# Display contact details for this version
print(f"\nContact ID: {response['contactId']}")
print(f"Contact Status: {response['contactStatus']}")
print(f"Ground Station: {response['groundStation']}")
print(f"Start Time: {response['startTime']}")
print(f"End Time: {response['endTime']}")
if response.get("satelliteArn"):
print(f"Satellite ARN: {response['satelliteArn']}")
if response.get("trackingOverrides"):
print(f"Tracking Overrides: {response['trackingOverrides']}")
# Check for failure details if the version failed to update
if version["status"] == "FAILED_TO_UPDATE":
failure_codes = version.get("failureCodes", [])
failure_message = version.get("failureMessage", "")
print(f"\nFailure Codes: {failure_codes}")
print(f"Failure Message: {failure_message}")
```
### 範例：列出聯絡人版本
下列範例列出聯絡人的所有版本，以檢視變更的完整歷史記錄，使用分頁處理大型結果集。
```
import boto3
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
contact_id = "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
# List all versions of a contact to view the full history of changes.
# Results are paginated. Use the nextToken to retrieve additional pages.
print(f"Listing versions for contact {contact_id}...")
paginator = ground_station_client.get_paginator("list_contact_versions")
page_iterator = paginator.paginate(
contactId=contact_id,
PaginationConfig={
"MaxItems": 100,
"PageSize": 20,
},
)
for page in page_iterator:
for version in page["contactVersionsList"]:
version_id = version["versionId"]
status = version["status"]
created = version.get("created", "N/A")
print(f" Version {version_id}: status={status}, created={created}")
if version.get("activated"):
print(f" Activated: {version['activated']}")
if version.get("superseded"):
print(f" Superseded: {version['superseded']}")
if status == "FAILED_TO_UPDATE":
failure_codes = version.get("failureCodes", [])
failure_message = version.get("failureMessage", "")
print(f" Failure Codes: {failure_codes}")
print(f" Failure Message: {failure_message}")
if status == "UPDATING":
print(f" Update is currently in progress.")
```
## 考量事項
+ 在引入聯絡版本控制功能之前建立的聯絡沒有版本資訊。為這些聯絡人呼叫 [DescribeContactVersion](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContactVersion.html) 或 [ListContactVersions](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContactVersions.html) 會傳回 `ResourceNotFoundException`。
+ 當您更新進行中聯絡的追蹤覆寫時，天線會調整為新的指向組態時，會有短暫的轉換期間。在此期間，訊號接收或傳輸可能會中斷。
+ 無法刪除聯絡版本。使用 [ListContactVersions](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContactVersions.html) 來檢視聯絡人變更的完整歷史記錄。
+ `UpdateContact` API 只能從聯絡人的排程區域呼叫。