本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

更新聯絡人和聯絡人版本控制

AWS Ground Station 支援更新具有 SCHEDULED、 PREPASS或 聯絡人狀態的PASS聯絡人。 AWS Ground Station 聯絡狀態您可以使用 UpdateContact API 來指定聯絡人的暫時性覆寫，包括方位/提升、OEM 或 TLE 追蹤資料，而無需取消和重新排程。這適用於需要在聯絡期間將天線重新任務到不同衛星的地理同步 (GEO) 衛星操作，或需要調整方向的啟動和早期操作 (LEOPs)。

每次您預留或更新聯絡人時， AWS Ground Station 都會建立新的聯絡人版本。聯絡版本提供對聯絡所做的變更歷史記錄，並可讓您追蹤每次更新的狀態。

聯絡版本控制的運作方式

當您呼叫 ReserveContact 時， 會 AWS Ground Station 建立第一個版本的聯絡人 （第 1 版），並在回應versionId中傳回 。每次後續呼叫 UpdateContact 時，都會以遞增的版本編號建立新的版本。

DescribeContact API 會傳回目前的ACTIVE聯絡版本，包括回應 version 欄位中的版本資訊。ListContacts API 也包含每個聯絡人的版本資訊。

若要檢視特定版本的聯絡人，請使用 DescribeContactVersion API。若要列出聯絡人的所有版本，請使用 ListContactVersions API。

更新聯絡人

當聯絡人處於排程、 PREPASS 或 PASS 狀態時，您可以呼叫 UpdateContact。API 接受下列參數：

您可以在聯絡期間透過提供新的 satelliteArn以及對應的 來變更目標衛星trackingOverrides。新的衛星必須在聯絡期間從地面工作站可見，因為聯絡開始和結束時間不會因此 API 而變更。新衛星也必須加入地面站點，並擁有任務設定檔所需的授權。聯絡人的任務描述檔無法變更，因此只有在兩個衛星都使用相同的任務描述檔時，切換衛星才適用。

UpdateContact API 會傳回 contactId和新的 versionId。更新會以非同步方式處理。使用 DescribeContactVersion 檢查更新的狀態。 AWS SDKs和 AWS Command Line Interface 提供輪詢的ContactUpdated等待程式，直到版本達到 ACTIVE 或 FAILED_TO_UPDATE 狀態為止。

聯絡版本狀態

每個聯絡版本都有下列其中一種狀態：

程式碼範例

下列範例示範如何搭配適用於 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.")

考量事項