本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

更新联系人和联系人版本控制

AWS Ground Station 支持以SCHEDULEDPREPASS、或联系人状态更新PASS联系人。您可以使用 UpdateContact API 为联系人（包括 azimuth/elevation OEM 或 TLE 跟踪数据）指定星历表替代，而无需取消和重新安排。这对于在接触期间需要将天线重新分配给另一颗卫星的地球同步（GEO）卫星运行或需要调整指向的发射和早期操作（LEOP）非常有用。

每次预订或更新联系人时，都会 AWS Ground Station 创建一个新的联系人版本。联系人版本提供联系人更改的历史记录，并允许您跟踪每次更新的状态。

联系人版本控制的工作原理

当您呼叫时 ReserveContact， AWS Ground Station 创建联系人的第一个版本（版本 1）并在响应versionId中返回。每次后续调用都会UpdateContact创建一个版本号递增的新版本。

DescribeContactAPI 返回当前的ACTIVE联系版本，包括响应version字段中的版本信息。该 ListContacts API 还包括每个联系人的版本信息。

要查看联系人的特定版本，请使用 DescribeContactVersion API。要列出联系人的所有版本，请使用 ListContactVersions API。

更新联系人

UpdateContact当联系人处于 “已安排”、“预通” 或 “通过” 状态时，您可以拨打电话。 API 接受以下参数：

在接触期间，您可以通过提供新的satelliteArn卫星和相应的卫星来更改目标卫星trackingOverrides。在接触期间，新卫星必须可以从地面站看见，因为使用此 API，接触的开始和结束时间不会改变。新卫星还必须登上地面站，并获得任务概况所要求的许可。接触点的任务配置文件无法更改，因此只有当两颗卫星使用相同的任务配置文件时，切换卫星才适用。

UpdateContactAPI 返回contactId和新的versionId。更新是异步处理的。DescribeContactVersion用于检查更新状态。有些 AWS 软件开发工具包会 AWS Command Line Interface 提供一个ContactUpdated服务员，负责轮询直到版本达到 ACTIVE 或 FAILED_TO_UPDATE 状态。

联系人版本状态

每个联系人版本都具有以下状态之一：

代码示例

以下示例演示了如何将联系人版本控制 API 与 Python AWS 软件开发工具包 (Boto3) 一起使用。

示例：更新联系人

以下示例使用新的追踪替代项更新联系人，并使用 Boto ContactUpdated 3 服务员等待更新完成。

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.")

注意事项