Introducción a las identidades de módulo y los módulos gemelos de IoT Hub usando la CLI de Azure

Artículo
03/18/2023

Las identidades de módulo y los módulos gemelos son similares a las identidades de dispositivo y los dispositivos gemelos de Azure IoT Hub, pero ofrecen granularidad más fina. Al igual que las identidades de dispositivo y los dispositivos gemelos de Azure IoT Hub permiten que una aplicación back-end configure un dispositivo y proporcione visibilidad sobre las condiciones del dispositivo, las identidades de módulo y los módulos gemelos proporcionan estas capacidades para los componentes individuales de un dispositivo. En los dispositivos compatibles con varios componentes, como dispositivos con sistema operativo o firmware, identidades de módulo y módulos gemelos permiten la configuración individual y condiciones específicas por componente.

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.

Este artículo le muestra cómo crear una sesión CLI de Azure en la que:

Creará una identidad de dispositivo y, después, una identidad de módulo para ese dispositivo.
Actualizará un conjunto de propiedades deseadas para el módulo gemelo asociado a la identidad de módulo.

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).

Autenticación de módulos

Puede utilizar claves simétricas o certificados X.509 para autenticar las identidades de los módulos. Para la autenticación de certificados X.509, el certificado del módulo debe tener su nombre común (CN) formateado como CN=<deviceid>/<moduleid>. Por ejemplo:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Preparar el Cloud Shell

Si desea usar Azure Cloud Shell, primero debe iniciarlo y configurarlo. Si usa la CLI localmente, pase a la sección Preparación de una sesión 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 una sesión de la CLI

A continuación, debe preparar una sesión de la CLI de Azure. Si está usando Cloud Shell, ejecute la sesión en una pestaña de Cloud Shell. Si usa un cliente de CLI local, ejecute la sesión en una instancia de la CLI.

Si usa Cloud Shell, vaya al paso siguiente. De lo contrario, ejecute el comando az login en la 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 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.

Creación de una identidad de dispositivo y una identidad de módulo

En esta sección, creará una identidad de dispositivo para su centro de IoT en la sesión de la CLI, y después creará una identidad de módulo usando esa identidad de dispositivo. Puede crear hasta 50 identidades de módulo bajo cada identidad de dispositivo.

Para crear una identidad de dispositivo y una identidad de módulo:

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

{DeviceName}. El nombre del dispositivo.

{HubName}. El nombre del centro de IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
En la sesión de la CLI, ejecute el comando az iot hub module-identity create y reemplace los siguientes marcadores de posición por sus valores correspondientes. Este comando crea la identidad de módulo para su módulo, bajo la identidad de dispositivo que creó en el paso anterior.

{DeviceName}. El nombre del dispositivo.

{HubName}. El nombre del centro de IoT.

{ModuleName}. El nombre del módulo de su dispositivo.
```
az iot hub module-identity create --device-id {DeviceName} --hub-name {HubName} \
                                  --module-id {ModuleName}
```

Actualización del módulo gemelo

Al crearse una identidad de módulo, se crea también un módulo gemelo en IoT Hub de manera implícita. En esta sección, usará la sesión de la CLI para actualizar un conjunto de propiedades deseadas en el módulo gemelo asociado a la identidad de módulo que creó en la sección anterior.

En la sesión de la CLI, ejecute el comando az iot hub module-twin update, reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, estamos actualizando varias propiedades deseadas en el módulo gemelo para la identidad de módulo que creamos en la sección anterior.

{DeviceName}. El nombre del dispositivo.

{HubName}. El nombre del centro de IoT.

{ModuleName}. El nombre del módulo de su dispositivo.
```
az iot hub module-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --module-id {ModuleName} \
                              --desired '{"conditions":{"temperature":{"warning":75, "critical":100}}}'
```

En la 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, usamos SampleDevice y SampleModule para los marcadores de posición {DeviceName} y {ModuleName}, respectivamente, en el comando de la CLI az iot hub module-twin update.

{
  "authenticationType": "sas",
  "capabilities": null,
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Disconnected",
  "deviceEtag": "Mzg0OEN1NzW=",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": "SampleModule",
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
        "$lastUpdatedVersion": 2,
        "conditions": {
          "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
          "$lastUpdatedVersion": 2,
          "temperature": {
            "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
            "$lastUpdatedVersion": 2,
            "critical": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            },
            "warning": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            }
          }
        }
      },
      "$version": 2,
      "conditions": {
        "temperature": {
          "critical": 100,
          "warning": 75
        }
      }
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": null,
  "version": 3,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Pasos siguientes

Para obtener información sobre cómo usar la CLI de Azure para ampliar su solución de IoT y programar actualizaciones en los dispositivos, consulte Programación y difusión de trabajos.

Para continuar con la introducción a IoT Hub y los patrones de administración de dispositivos, como la actualización basada en imágenes de un extremo a otro, vea el artículo Actualización de dispositivos para Azure IoT Hub con la imagen de referencia Raspberry Pi 3 B+.

Compartir a través de