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

# 能力重新发现
<a name="managedintegrations-sdk-v2-onboarding-capability-rediscovery"></a>

本节介绍使用功能重新发现功能重新学习与集线器连接的设备的设备功能信息的步骤。

## 先决条件
<a name="capability-rediscovery-prereq"></a>

在尝试重新发现功能之前，请完成以下步骤：
+ 将集线器设备加载到托管集成中心。
+ 将一台或多台终端设备载入集线器。
+ 安装《[托管集成 AWS CLI 命令 AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)参考》中的最新版本的
+ （可选）订阅 DEV [ICE\_DISCOVERY\_STATUS 事件通知](managedintegrations-notifications.md#managedintegrations-notification-setup)。

## 何时使用功能重新发现
<a name="capability-rediscovery-use-cases"></a>

在以下场景中使用功能重新发现：
+ 在对终端设备进行固件更新以添加或修改设备功能之后
+ 在集线器软件更新后，启用了对新设备功能的支持
+ 当设备功能未在托管集成中准确反映时
+ 刷新连接到集线器的单个设备或所有设备的功能信息

## 开始重新发现能力
<a name="capability-rediscovery-start-discovery"></a>

开始重新发现集线器的功能以更新设备功能。

**开始重新发现能力**
+ 使用带有发现类型的 [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 命令。`CONTROLLER_CAPABILITY_REDISCOVERY`

  **start-device-discovery 示例**

  ```
  # For a single device
  aws iot-managed-integrations start-device-discovery \
    --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
    --controller-identifier {{HUB_MANAGED_THING_ID}} \
    --protocol {{PROTOCOL}} \
    --end-device-identifier {{DEVICE_MANAGED_THING_ID}}
  
  # For all devices on a protocol
  aws iot-managed-integrations start-device-discovery \
    --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
    --controller-identifier {{HUB_MANAGED_THING_ID}} \
    --protocol {{PROTOCOL}}
  ```

  **响应：**

  ```
  {
      "Id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "StartedAt": "2026-01-12T23:07:49.275Z"
  }
  ```
**注意**  
`--protocol`参数接受`ZIGBEE``ZWAVE`、或`CUSTOM`。  
如果未提供可选`--end-device-identifier`参数，则会重新发现与所选协议的集线器关联的所有设备。

  *有关更多信息，请参阅《托管集成命令参考》中的 [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 命令。 AWS CLI *

要验证设备功能是否已更新，请参阅[获取托管事物功能](managedintegrations-sdk-v2-cookbook-ugs.md#managedintegrations-sdk-v2-cookbook-check-device-capabilties)。

## 问题排查
<a name="capability-rediscovery-troubleshooting"></a>

使用以下指南对功能重新发现的常见问题进行故障排除。在重新发现功能时，托管集成会通过 Kinesis 或 EventBridge 以 JSON 消息的形式发送通知。

### 成功通知
<a name="capability-rediscovery-notifications-success"></a>

**每台正在处理的设备：**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/xyz789uvw012"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1
    }
}
```

**完成：**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "SUCCEEDED",
        "deviceCount": 0
    }
}
```

### 失败通知
<a name="capability-rediscovery-notifications-failure"></a>

**设备故障：**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/ghi345jkl678"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1,
        "error": {
            "code": "500",
            "message": "Device unreachable",
            "managedThingId": "ghi345jkl678"
        }
    }
}
```

**完全失败：**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "FAILED",
        "deviceCount": 0,
        "error": {
            "code": "404",
            "message": "Specified controller does not exist"
        }
    }
}
```

### 未收到任何通知
<a name="capability-rediscovery-no-notifications"></a>

如果您没有收到有关发现状态的通知，请确认您已订阅`DEVICE_DISCOVERY_STATUS`事件通知。有关设置通知的更多信息，请参阅[设置托管集成通知](managedintegrations-notifications.md#managedintegrations-notification-setup)。

### 有些设备未更新
<a name="capability-rediscovery-partial-failure"></a>

如果某些设备在功能重新发现期间无法更新，请查看`DEVICE_DISCOVERY_STATUS`通知中的错误消息。常见错误消息包括：
+ `Device unreachable`-设备离线或无响应
+ `Timeout querying device`-设备未在预期的时间范围内响应
+ `Invalid capability report`-设备固件可能有问题

要解决这些问题，请确保受影响的设备已开机且可访问，然后使用参数分别重试重新发现故障设备的功能。`--end-device-identifier`

### 发现永远不会完成
<a name="capability-rediscovery-stuck"></a>

如果功能重新发现过程未完成，请使用从`start-device-discovery`命令返回的发现任务 ID 检查发现状态：

```
aws iot-managed-integrations get-device-discovery \
  --identifier {{DISCOVERY_JOB_ID}}
```

如果发现卡住了：
+ 确认集线器已联机并已连接到托管集成
+ 最多等待 15 分钟，发现会自动超时
+ 确认集线器和设备运行后，重试功能重新发现