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

# 功能重新探索
<a name="managedintegrations-sdk-v2-onboarding-capability-rediscovery"></a>

本節說明使用功能重新探索為中樞連線裝置重新學習裝置功能資訊的步驟。

## 先決條件
<a name="capability-rediscovery-prereq"></a>

在嘗試重新探索功能之前，請先完成以下步驟：
+ 將中樞裝置加入受管整合中樞。
+ 將一或多個終端裝置加入中樞。
+  AWS CLI 從 [Managed Integrations AWS CLI 命令參考](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)安裝最新版本的
+ （選用） 訂閱 [DEVICE\_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`參數，則會重新探索與所選通訊協定中樞相關聯的所有裝置。

  如需詳細資訊，請參閱 Managed Integrations AWS CLI *Command Reference* 中的 [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 命令。

若要確認裝置功能已更新，請參閱[取得受管物件功能](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 分鐘，讓探索自動逾時
+ 在確認中樞和裝置可運作之後，重試功能重新探索