本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 更新联系人和联系人版本控制
AWS Ground Station 支持使用`SCHEDULED``PREPASS`、或联系人[状态更新`PASS`联系人](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。
## 更新联系人
[UpdateContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateContact.html)当联系人处于 “已安排”、“预通过” 或 “通过” 状态时，您可以拨打电话。 API 接受以下参数：
+ **联系人 ID** — 要更新的联系人的标识符。
+ **ClientTo** ken — 一种等性令牌，可确保请求仅处理一次。如果您使用相同的客户端令牌重试请求，则 AWS Ground Station 返回原始响应而不再次执行更新。如果没有提供客户令牌，许多用户 AWS SDKs 会自动为您生成客户令牌。
+ **TrackingOverrides** — 联系人的新跟踪配置。这包括节目轨道设置（方位角/仰角、TLE 或 OEM 星历表）。
+ S@@ **atellite** Arn — 联系人卫星的 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 状态，然后再提交其他更新。
## 联系人版本状态
每个联系人版本都有以下状态之一：
| Status | 说明 |
| --- | --- |
| UPDATING | 该版本正在应用于联系人。更新已提交，正在由处理 AWS Ground Station。 |
| ACTIVE | 该版本是联系人的当前活动配置。地面站正在使用此版本的设置。 |
| SUPERSEDED | 该版本以前处于活动状态，但已被较新的版本所取代。 |
| 更新失败 | 无法应用更新。联系人将恢复到之前处于活动状态的版本。有关详细信息，请查看failureCodes和failureMessage字段。 |
## 代码示例
以下示例演示了如何在 Python AWS SDK (Boto3) 中使用联系人版本控制 APIs 。
### 示例：更新联系人
以下示例使用新的追踪覆盖更新联系人，并使用 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.")
```
## 注意事项
+ 在引入联系人版本控制功能之前创建的联系人没有版本信息。致电[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。