As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Configuração guiada pelo usuário para integrar e operar dispositivos
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

Configure seus dispositivos para serem integrados ao seu hub de integrações gerenciadas criando uma coisa gerenciada e conectando-a ao seu hub. Esta seção descreve as etapas para concluir o processo de integração do dispositivo usando a configuração guiada pelo usuário.

## Pré-requisitos
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

Conclua estas etapas antes de tentar integrar um dispositivo:
+ Integre um dispositivo de hub ao hub de integrações gerenciadas.
+ Instale a versão mais recente do a AWS CLI partir da Referência de [AWS CLI Comandos de Integrações Gerenciadas](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Inscreva-se para receber notificações de [eventos DEVICE\$1DISCOVERY-STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup).

**Topics**
+ [Pré-requisitos](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Pré-requisito: ativar o modo de emparelhamento em seu dispositivo Z Wave](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Etapa 1: iniciar a descoberta do dispositivo](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Etapa 2: consultar o ID do trabalho de descoberta](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Etapa 3: criar uma coisa gerenciada para seu dispositivo](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Etapa 4: consultar a coisa gerenciada](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Etapa 5: Obtenha recursos de gerenciamento de coisas](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Etapa 6: enviar um comando para a coisa gerenciada](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Etapa 7: verificar o estado da coisa gerenciada](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Etapa 8: remover o item gerenciado do seu hub](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Pré-requisito: ativar o modo de emparelhamento em seu dispositivo Z Wave
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

Ative o modo de emparelhamento no dispositivo Z-wave. O modo de emparelhamento pode variar para cada dispositivo Z-Wave, portanto, consulte as instruções do dispositivo para configurar corretamente o modo de emparelhamento. Geralmente é um botão que o usuário deve pressionar. 

## Etapa 1: iniciar a descoberta do dispositivo
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

Inicie a descoberta de dispositivos em seu hub para obter um ID de trabalho de descoberta que é usado para integrar seu dispositivo.

**Para iniciar a descoberta de dispositivos**
+ Use o [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html)comando para obter o ID do trabalho de descoberta.

  **start-device-discovery exemplo**

  ```
  #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 \
  ```

  **Resposta:**

  ```
  {
        "Id": DISCOVERY_JOB_ID,
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**nota**  
Existem comandos separados para dispositivos Z-wave e Zigbee.

  Para obter mais informações, consulte a [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html)API na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 2: consultar o ID do trabalho de descoberta
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

Use o `list-discovered-devices` comando para obter o material de autenticação do seu dispositivo.

**Para consultar seu ID de trabalho de descoberta**
+ Use o ID do trabalho de descoberta com o list-discovered-devices comando para obter o material de autenticação do seu dispositivo.

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

**Resposta:**

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

## Etapa 3: criar uma coisa gerenciada para seu dispositivo
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

Use o `create-managed-thing` comando para criar uma coisa gerenciada para o seu dispositivo. Cada dispositivo requer sua própria coisa gerenciada. 

**Para criar uma coisa gerenciada**
+ Use o `create-managed-thing` comando para criar uma coisa gerenciada para o seu dispositivo.

  **create-managed-thing exemplo**

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

  **Resposta:**

  ```
  {    
      "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"
    }
  ```

  Para obter mais informações, consulte o [create-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 4: consultar a coisa gerenciada
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

Você pode verificar se uma coisa gerenciada está ativada usando o `get-managed-thing` comando. 

**Para consultar uma coisa gerenciada**
+ Use o `get-managed-thing` comando para verificar se o status de provisionamento do item gerenciado está definido como. `ACTIVATED` Para obter mais informações sobre o status do provisionamento, consulte Provisionamento de [dispositivos](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **get-managed-thing exemplo**

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

  **Resposta:**

  ```
  {
        "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": {}
    }
  ```

  Para obter mais informações, consulte o [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 5: Obtenha recursos de gerenciamento de coisas
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

Você pode ver uma lista das ações disponíveis de uma coisa gerenciada usando `get-managed-thing-capabiltiies` o. 

**Para obter os recursos de um dispositivo**
+ Use o `get-managed-thing-capabilities` comando para obter o ID do endpoint. Observe também a lista de ações possíveis.

  **get-managed-thing-capabilities exemplo**

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

  **Resposta:**

  ```
  {
        "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"
                            ],
                            ...
    }
  ```

  Para obter mais informações, consulte o [get-managed-thing-capabilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 6: enviar um comando para a coisa gerenciada
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

Você pode usar o send-managed-thing-command comando para enviar um comando de ação de alternância para sua coisa gerenciada. 

**Envie um comando para a coisa gerenciada usando uma ação de alternância.**
+ Use o `send-managed-thing-command` comando para enviar um comando de ação de alternância.

  **send-managed-thing-command exemplo**

  ```
  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
  ```
**nota**  
Este exemplo usa jq cli para, mas você também pode passar a string inteira `endpointId`

  **Resposta:**

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

  Para obter mais informações, consulte o [send-managed-thing-command](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 7: verificar o estado da coisa gerenciada
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

Verifique o estado da coisa gerenciada para validar se a ação de alternância foi bem-sucedida.

**Para verificar o estado do dispositivo de uma coisa gerenciada**
+ Use o `get-managed-thing-state` comando para validar se a ação de alternância foi bem-sucedida.

  **get-managed-thing-state exemplo**

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

  **Resposta:**

  ```
  {
        "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"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ```

  Para obter mais informações, consulte o [get-managed-thing-state](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.

## Etapa 8: remover o item gerenciado do seu hub
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

Limpe seu hub removendo a coisa gerenciada.

**Para excluir uma coisa gerenciada**
+ Use o [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html)comando para remover uma coisa gerenciada. 

  **delete-managed-thing exemplo**

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

  Para obter mais informações, consulte o [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html)comando na *Referência de AWS CLI comandos* de integrações gerenciadas.
**nota**  
Se o dispositivo estiver preso em um `DELETE_IN_PROGRESS` estado, anexe o `--force` sinalizador ao `delete-managed-thing` comando.
**nota**  
Para dispositivos Z-wave, você precisa colocar o dispositivo no modo de emparelhamento após executar o comando.