Introducción a los dispositivos gemelos (CLI de Azure)

Artículo
03/17/2023

Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. IoT Hub conserva un dispositivo gemelo por cada dispositivo que se conecta a él.

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Use los dispositivos gemelos para:

Almacenar metadatos del dispositivo desde el back-end de la solución.
Notificar la información sobre el estado actual, como las funcionalidades y las condiciones disponibles (por ejemplo, el método de conectividad usado) de la aplicación del dispositivo.
Sincronizar el estado de flujos de trabajo de larga duración (como las actualizaciones del firmware y de la configuración) entre la aplicación del dispositivo y la del back-end.
Consultar los metadatos, la configuración o el estado del dispositivo.

Los dispositivos gemelos están diseñados para la sincronización y para consultar las condiciones y configuraciones del dispositivo. Para obtener más información sobre los dispositivos gemelos, incluyendo cuándo usarlos, consulte Comprenda los dispositivos gemelos.

Los centros de IoT almacenan dispositivos gemelos, que contienen los siguientes elementos:

Etiquetas. Metadatos de dispositivo a los que solo puede acceder el back-end de la solución.
Propiedades deseadas. Objetos JSON que puede modificar el back-end de la solución y puede observar la aplicación del dispositivo.
Propiedades notificadas. Objetos JSON que puede modificar la aplicación del dispositivo y que puede leer el back-end de la solución.

Las etiquetas y las propiedades no pueden contener matrices, pero pueden contener objetos anidados.

En la ilustración siguiente se muestra la organización del dispositivo gemelo:

Captura de pantalla de un diagrama de concepto de dispositivo gemelo.

Además, el back-end de la solución puede consultar los dispositivos gemelos en función de todos los datos descritos anteriormente. Para obtener más información acerca de los dispositivos gemelos, consulte Introducción a los dispositivos gemelos. Para más información sobre la consulta, consulte Lenguaje de consulta de IoT Hub.

En este artículo aprenderá a:

Usa un dispositivo simulado para notificar su canal de conectividad como propiedad notificada en el dispositivo gemelo.
Consultar dispositivos mediante filtros en las etiquetas y propiedades que se han creado anteriormente.

Para obtener más información sobre el uso de propiedades notificadas de dispositivos gemelos, consulta Guía de comunicación de dispositivo a nube.

En este artículo se muestra cómo crear dos sesiones de la CLI de Azure:

Una sesión que crea un dispositivo simulado. El dispositivo simulado notifica su canal de conectividad como propiedad notificada en el dispositivo gemelo correspondiente cuando se inicializa.
Una sesión que actualiza las etiquetas del dispositivo gemelo para el dispositivo simulado y, luego, consulta los dispositivos desde el centro de IoT. Las consultas usan filtros basados en las etiquetas y propiedades actualizadas anteriormente en ambas sesiones.

Prerrequisitos

CLI de Azure. También puede ejecutar todos los comandos de este artículo mediante Azure Cloud Shell, un shell interactivo de la CLI que se ejecuta en el explorador o en una aplicación como el terminal de Windows. Si usa el Cloud Shell, no necesita instalar nada. Si prefiere usar la CLI en un entorno local, para este artículo se requiere la versión 2.36 o posterior de la CLI de Azure. Ejecute az --version para encontrar la versión. Para instalar localmente o actualizar la CLI de Azure, vea Instalación de la CLI de Azure.
Una instancia de IoT Hub. Cree uno con la CLI o el Azure Portal.
Asegúrese de que está abierto el puerto 8883 del firewall. Los ejemplos de este artículo usan el protocolo MQTT, que se comunica a través del puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

Preparar el Cloud Shell

Si desea usar Azure Cloud Shell, primero debe iniciarlo y configurarlo. Si usa la CLI localmente, vaya a la sección Preparar dos sesiones de la CLI.

Seleccione el icono Cloud Shell en el encabezado de página del Azure Portal.

Nota

Si es la primera vez que usa el Cloud Shell, le pedirá que cree el almacenamiento, que es necesario para usar el Cloud Shell. Seleccione una suscripción para crear una cuenta de almacenamiento y un recurso compartido de Microsoft Azure Files.
Use el selector de entorno en la barra de herramientas de Cloud Shell para seleccionar el entorno de la CLI preferido. En este artículo se usa el entorno de Bash. También puede usar el entorno de PowerShell.

Nota:

Algunos comandos requieren una sintaxis o formato diferentes en los entornos de Bash y PowerShell. Para obtener más información, consulte Sugerencias para usar correctamente la CLI de Azure.

Preparación de dos sesiones de la CLI

A continuación, debe preparar dos sesiones de la CLI de Azure. Si utiliza Cloud Shell, ejecutará estas sesiones en pestañas independientes de Cloud Shell. Si usa un cliente de la CLI local, ejecutará instancias independientes de la CLI. Use las sesiones independientes de la CLI para las siguientes tareas:

La primera sesión simula un dispositivo IoT que se comunica con su centro de IoT.
La segunda sesión actualiza el dispositivo simulado y consulta el centro de IoT.

Si usa Cloud Shell, vaya al paso siguiente. De lo contrario, ejecute el comando az login en la primera sesión de la CLI para iniciar sesión en su cuenta de Azure.

Si usa Cloud Shell, iniciará sesión automáticamente en la cuenta de Azure. Todas las comunicaciones entre la sesión de la CLI de Azure y el centro de IoT se autentican y cifran. Como resultado, este artículo no necesita autenticación adicional que se usaría con un dispositivo real, como una cadena de conexión. Para más información sobre la autenticación con la CLI de Azure, vea Inicio de sesión con la CLI de Azure.
```
az login
```
En la primera sesión de la CLI, ejecute el comando az extension add. El comando agrega la extensión de Microsoft Azure IoT para la CLI de Azure al shell de la CLI. La extensión agrega comandos específicos de IoT Hub, IoT Edge e IoT Device Provisioning Service (DPS) a la CLI de Azure. Después de instalar la extensión de Azure IOT, no es necesario volver a instalarla en ninguna sesión de Cloud Shell.
```
az extension add --name azure-iot
```
Nota

En este artículo se usa la versión más reciente de la extensión de Azure IoT, denominada azure-iot. La versión heredada se denomina azure-cli-iot-ext. Solo debe tener instalada una versión a la vez. Puede usar el comando az extension list para validar las extensiones instaladas actualmente.

Use az extension remove --name azure-cli-iot-ext para eliminar la versión heredada de la extensión.

Use az extension add --name azure-iot para agregar la nueva versión de la extensión.

Para ver las extensiones que ha instalado, use az extension list.
Abra la segunda sesión de la CLI. Si usa el Cloud Shell en un explorador, seleccione el icono Abrir nueva sesión en la barra de herramientas de la primera sesión de la CLI. Si usa la CLI localmente, abra una segunda instancia de la CLI.

Creación y simulación de un dispositivo

En esta sección, creará una identidad de dispositivo para el centro de IoT en la primera sesión de la CLI y, a continuación, simulará un dispositivo con esa identidad del dispositivo. El dispositivo simulado responde a los trabajos que programa en la segunda sesión de la CLI.

Para crear e iniciar un dispositivo simulado:

En la primera sesión de la CLI, ejecute el comando az iot hub device-identity create, reemplazando los siguientes marcadores de posición por sus valores correspondientes. Este comando crea la identidad del dispositivo para el dispositivo simulado.

{DeviceName}. Nombre del dispositivo simulado.

{HubName}. El nombre del centro de IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
En la primera sesión de la CLI, ejecute el comando az iot device simulate, reemplazando los siguientes marcadores de posición por sus valores correspondientes. Este comando simula el dispositivo que creó en el paso anterior. El comando también configura el dispositivo simulado para que notifique su canal de conectividad como propiedad notificada en el dispositivo gemelo correspondiente cuando se inicializa.

{DeviceName}. Nombre del dispositivo simulado.

{HubName}. El nombre del centro de IoT.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
Sugerencia

De forma predeterminada, el comando az iot device simulate envía 100 mensajes del dispositivo a la nube con un intervalo de 3 segundos entre mensajes. La simulación finaliza después de que se hayan enviado todos los mensajes. Si desea que la simulación se ejecute más tiempo, puede usar el parámetro --msg-count para especificar más mensajes o el parámetro --msg-interval para especificar un intervalo más largo entre los mensajes. También puede volver a ejecutar el comando para reiniciar el dispositivo simulado.

Actualizar el dispositivo gemelo

Al crearse la identidad del dispositivo, se crea también un dispositivo gemelo en IoT Hub de manera implícita. En esta sección, usará la segunda sesión de la CLI para actualizar un conjunto de etiquetas en el dispositivo gemelo asociado a la identidad del dispositivo que creó en la sección anterior. Puede usar etiquetas de dispositivo gemelo para organizar y administrar dispositivos en las soluciones de IoT. Para más información sobre cómo administrar dispositivos mediante etiquetas, consulte Administración de dispositivos mediante etiquetas de dispositivo gemelo en Azure IoT Hub.

En la primera sesión de la CLI, confirme que el dispositivo simulado se está ejecutando. Si no es así, vuelva a ejecutar el comando az iot device simulate desde Crear y simular un dispositivo.
En la primera sesión de la CLI, ejecute el comando az iot hub device-twin update reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, actualizaremos varias etiquetas en el dispositivo gemelo para la identidad del dispositivo que hemos creado en la sección anterior.

{DeviceName}. El nombre del dispositivo.

{HubName}. El nombre del centro de IoT.
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

En la segunda sesión de la CLI, confirme que la respuesta JSON muestra los resultados de la operación de actualización. En el siguiente ejemplo de respuesta JSON, se usa SampleDevice para el marcador de posición {DeviceName} del comando az iot hub device-twin update de la CLI.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Consulta del centro de IoT para dispositivos gemelos

IoT Hub expone los dispositivos gemelos para el centro de IoT como una colección de documentos denominada devices. En esta sección, usará la segunda sesión de la CLI para ejecutar dos consultas en el conjunto de dispositivos gemelos del centro de IoT: la primera selecciona solo los dispositivos gemelos de los dispositivos que se encuentran en la planta Redmond43 y la segunda mejora la consulta para seleccionar solo los dispositivos que están también conectados a través de la red de telefonía móvil. Ambas consultas devuelven solo los 100 primeros dispositivos del conjunto de resultados. Para más información sobre las consultas de dispositivos gemelos, vea Consultas para dispositivos y módulos gemelos de IoT Hub.

En la primera sesión de la CLI, confirme que el dispositivo simulado se está ejecutando. Si no es así, vuelva a ejecutar el comando az iot device simulate desde Crear y simular un dispositivo.
En la primera sesión de la CLI, ejecute el comando az iot hub query reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, filtramos la consulta para devolver solo los dispositivos gemelos de los dispositivos que se encuentran en la planta Redmond43.

{HubName}. El nombre del centro de IoT.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

En la segunda sesión de la CLI, confirme que la respuesta JSON muestra los resultados de la consulta.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

En la primera sesión de la CLI, ejecute el comando az iot hub query reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, filtramos la consulta para devolver solo los dispositivos gemelos de los dispositivos que se encuentran en la planta Redmond43 que están también conectados a través de la red de telefonía móvil.

{HubName}. El nombre del centro de IoT.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
En la segunda sesión de la CLI, confirme que la respuesta JSON muestra los resultados de la consulta. Los resultados de esta consulta deben coincidir con los resultados de la consulta anterior de esta sección.

En este artículo:

Ha agregado metadatos de dispositivo como etiquetas desde una sesión de la CLI de Azure.
Ha simulado un dispositivo que ha notificado la información de conectividad del dispositivo en el dispositivo gemelo.
Ha consultado la información del dispositivo gemelo mediante el lenguaje de consulta de IoT Hub de tipo SQL en una sesión de la CLI de Azure.

Pasos siguientes

Para saber cómo:

Enviar datos de telemetría desde dispositivos, consulte Inicio rápido: Envío de telemetría desde un dispositivo IoT Plug and Play a Azure IoT Hub.
Configurar dispositivos mediante las propiedades deseadas del dispositivo gemelo, consulte Tutorial: Configuración de dispositivos desde un servicio back-end.
Controlar los dispositivos de forma interactiva, por ejemplo, encender un ventilador desde una aplicación controlada por el usuario, consulte Inicio rápido: Control de un dispositivo conectado a IoT Hub.

Compartir a través de