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

# 在用户指导下进行设备加载和操作的设置
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

通过创建托管设备并将其连接到集线器，将设备设置为加载到托管集成中心。本节介绍使用用户指导设置完成设备上线流程的步骤。

## 先决条件
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

在尝试加载设备之前，请完成以下步骤：
+ 将集线器设备载入托管集成中心。
+  AWS CLI 从《[托管集成 AWS CLI 命令](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)参考》中安装最新版本的
+ 订阅[设备发现状态事件通知。](managedintegrations-notifications.md#managedintegrations-notification-setup)

**Topics**
+ [先决条件](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [先决条件：在 Z Wave 设备上启用配对模式](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [步骤 1：开始设备发现](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [步骤 2：查询发现任务 ID](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [第 3 步：为您的设备创建托管内容](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [步骤 4：查询托管事物](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [第 5 步：获取托管事物功能](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [步骤 6：向托管事物发送命令](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [第 7 步：检查托管事物的状态](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [第 8 步：从集线器中移除托管内容](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## 先决条件：在 Z Wave 设备上启用配对模式
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

在 Z-Wave 设备上启用配对模式。每台 Z-Wave 设备的配对模式可能有所不同，因此请参阅设备的说明以正确设置配对模式。它通常是用户必须按下的按钮。

## 步骤 1：开始设备发现
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

为您的集线器启动设备发现，以获取用于加载设备的发现任务 ID。

**开始设备发现**
+ 使用[start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html)命令获取发现任务 ID。

  **start-device-discovery 示例**

  ```
  #For Zigbee
    aws iot-managed-integrations start-device-discovery --discovery-type ZIGBEE \
    --controller-identifier HUB_MANAGED_THING_ID
    
    #For Zwave
    aws iot-managed-integrations start-device-discovery --discovery-type ZWAVE \
    --controller-identifier HUB_MANAGED_THING \
    --authentication-material-type ZWAVE_INSTALL_CODE \
    --authentication-material 13333
    
    #For Cloud
    aws iot-managed-integrations start-device-discovery --discovery-type CLOUD \
    --account-association-id C2C_ASSOCIATION_ID \
    
    #For Custom
    aws iot-managed-thing start-device-discovery --discovery-type CUSTOM \
    --controller-identifier HUB_MANAGED_THING_ID \
    --custom-protocol-detail NAME : NON_EMPTY_STRING \
  ```

  **响应：**

  ```
  {
        "Id": DISCOVERY_JOB_ID,
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**注意**  
Z-Wave 和 Zigbee 设备有不同的命令。

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

## 步骤 2：查询发现任务 ID
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

使用`list-discovered-devices`命令获取设备的身份验证材料。

**查询您的发现任务 ID**
+ 使用发现任务 ID 和 list-discovered-devices命令获取设备的身份验证材料。

  ```
  aws iot-managed-integrations list-discovered-devices --identifier DISCOVERY_JOB_ID
  ```

**响应：**

```
"Items": [
    {
        "DeviceTypes": [],
        "DiscoveredAt": "2025-06-03T14:43:37.619000-07:00",
        "AuthenticationMaterial": AUTHENTICATION_MATERIAL
    }
]
```

## 第 3 步：为您的设备创建托管内容
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

使用`create-managed-thing`命令为您的设备创建托管事物。每台设备都需要自己的托管设备。

**创建托管事物**
+ 使用`create-managed-thing`命令为您的设备创建托管事物。

  **create-managed-thing 示例**

  ```
  aws iot-managed-integrations create-managed-thing \
    --role  DEVICE --authentication-material-type DISCOVERED_DEVICE \
    --authentication-material "AUTHENTICATION_MATERIAL"
  ```

  **响应：**

  ```
  {    
      "Id": "DEVICE_MANAGED_THING_ID"
      "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID"
      "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
    }
  ```

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

## 步骤 4：查询托管事物
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

您可以使用`get-managed-thing`命令检查托管事物是否已激活。

**查询托管事物**
+ 使用`get-managed-thing`命令检查托管事物的配置状态是否设置为`ACTIVATED`。有关配置状态的更多信息，请参阅[设备配置](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html)。

  **get-managed-thing 示例**

  ```
  aws iot-managed-integrations get-managed-thing \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **响应：**

  ```
  {
        "Id": "DEVICE_MANAGED_THING_ID",
        "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID,
        "Role": "DEVICE",
        "ProvisioningStatus": "ACTIVATED",
        "MacAddress": "MAC_ADDRESS",
        "ParentControllerId": "PARENT_CONTROLLER_ID",
        "CreatedAt": "2025-06-03T14:46:35.149000-07:00",
        "UpdatedAt": "2025-06-03T14:46:37.500000-07:00",
        "Tags": {}
    }
  ```

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

## 第 5 步：获取托管事物功能
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

您可以使用查看托管事物的可用操作列表`get-managed-thing-capabiltiies`。

**获取设备的功能**
+ 使用`get-managed-thing-capabilities`命令获取端点 ID。另请注意可能的操作列表。

  **get-managed-thing-capabilities 示例**

  ```
  aws iot-managed-integrations get-managed-thing-capabilities \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **响应：**

  ```
  {
        "ManagedThingId": "DEVICE_MANAGED_THING_ID",
        "CapabilityReport": {
            "version": "1.0.0",
            "nodeId": "zb.539D+4A1D",
            "endpoints": [
                {
                    "id": "1",
                    "deviceTypes": [
                        "Unknown Device"
                    ],
                    "capabilities": [
                        {
                            "id": "matter.OnOff@1.4",
                            "name": "On/Off",
                            "version": "6",
                            "properties": [
                                "OnOff",
                                "OnOff",
                                "OnTime",
                                "OffWaitTime"
                            ],
                            "actions": [
                                "Off",
                                "On",
                                "Toggle",
                                "OffWithEffect",
                                "OnWithRecallGlobalScene",
                                "OnWithTimedOff"
                            ],
                            ...
    }
  ```

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

## 步骤 6：向托管事物发送命令
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

您可以使用该 send-managed-thing-command命令向您的托管事物发送切换操作命令。

**使用切换操作向托管事物发送命令。**
+ 使用该`send-managed-thing-command`命令发送切换操作命令。

  **send-managed-thing-command 示例**

  ```
  json=$(jq -cr '.|@json') <<EOF
    [
      {
        "endpointId": "1",
        "capabilities": [
          {
            "id": "matter.OnOff@1.4",
            "name": "On/Off",
            "version": "1",
            "actions": [
              {
                "name": "Toggle",
                "parameters": {}
              }
            ]
          }
        ]
      }
    ]
    EOF
    aws iot-managed-integrations send-managed-thing-command \
    --managed-thing-id ${device_managed_thing_id} --endpoints ENDPOINT_ID
  ```
**注意**  
这个例子使用了 jq cli，但你也可以传递整个字符串 `endpointId`

  **响应：**

  ```
  {    
    "TraceId": TRACE_ID
    }
  ```

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

## 第 7 步：检查托管事物的状态
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

检查托管事物的状态以验证切换操作是否成功。

**检查托管事物的设备状态**
+ 使用`get-managed-thing-state`命令验证切换操作是否成功。

  **get-managed-thing-state 示例**

  ```
    aws iot-managed-integrations get-managed-thing-state --managed-thing-id DEVICE_MANAGED_THING_ID
  ```

  **响应：**

  ```
  {
        "Endpoints": [
            {
                "endpointId": "1",
                "capabilities": [
                    {
                        "id": "matter.OnOff@1.4",
                        "name": "On/Off",
                        "version": "1.4",
                        "properties": [
                            {
                                "name": "OnOff",
                                "value": {
                                    "propertyValue": true,
                                    "lastChangedAt": "2025-06-03T21:50:39.886Z"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ```

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

## 第 8 步：从集线器中移除托管内容
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

通过移除托管的东西来清理集线器。

**删除托管事物**
+ 使用[delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html)命令移除托管事物。

  **delete-managed-thing 示例**

  ```
  aws iot-managed-integrations delete-managed-thing \
    --identifier MANAGED_THING_ID
  ```

  有关更多信息，请参阅《托管集成[delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html)命令*参考》中的 AWS CLI 命令*。
**注意**  
如果设备停滞在`DELETE_IN_PROGRESS`状态，`delete-managed-thing`请在命令后面附加`--force`标志。
**注意**  
对于 Z-Wave 设备，您需要在执行命令后将设备置于配对模式。