IoT 中心模块标识和模块孪生 (Node.js) 入门Get started with IoT Hub module identity and module twin (Node.js)

备注

模块标识和模块孪生类似于 Azure IoT 中心设备标识和设备孪生,但提供更精细的粒度。Module identities and module twins are similar to Azure IoT Hub device identity and device twin, but provide finer granularity. Azure IoT 中心设备标识和设备孪生允许后端应用程序配置设备并提供设备条件的可见性,而模块标识和模块孪生为设备的各个组件提供这些功能。While Azure IoT Hub device identity and device twin enable the back-end application to configure a device and provides visibility on the device’s conditions, a module identity and module twin provide these capabilities for individual components of a device. 在支持多个组件的设备上(例如基于操作系统的设备或固件设备),它允许每个部件拥有独立的配置和条件。On capable devices with multiple components, such as operating system based devices or firmware devices, it allows for isolated configuration and conditions for each component.

在本教程结束时,会创建两个 Node.js 应用:At the end of this tutorial, you have two Node.js apps:

  • CreateIdentities,用于创建设备标识、模块标识和相关的安全密钥,以连接设备和模块客户端。CreateIdentities, which creates a device identity, a module identity and associated security key to connect your device and module clients.
  • UpdateModuleTwinReportedProperties,用于将更新的模块孪生报告属性发送到 IoT 中心。UpdateModuleTwinReportedProperties, which sends updated module twin reported properties to your IoT Hub.

备注

有关 Azure IoT SDK 的信息(可以使用这些 SDK 构建可在设备和解决方案后端上运行的应用程序),请参阅 Azure IoT SDKFor information about the Azure IoT SDKs that you can use to build both applications to run on devices, and your solution back end, see Azure IoT SDKs.

先决条件Prerequisites

  • Node.js 版本 10.0.x 或更高版本。Node.js version 10.0.x or later. 准备开发环境介绍了如何在 Windows 或 Linux 上安装本教程所用的 Node.js。Prepare your development environment describes how to install Node.js for this tutorial on either Windows or Linux.

  • 有效的 Azure 帐户。An active Azure account. (如果没有帐户,只需几分钟即可创建一个试用帐户。)(If you don't have an account, you can create a trial account in just a couple of minutes.)

创建 IoT 中心Create an IoT hub

此部分介绍如何使用 Azure 门户创建 IoT 中心。This section describes how to create an IoT hub using the Azure portal.

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 从 Azure 主页中选择“+ 创建资源”按钮,然后在“搜索市场”字段中输入“IoT 中心”。 From the Azure homepage, select the + Create a resource button, and then enter IoT Hub in the Search the Marketplace field.

  3. 在搜索结果中选择“IoT 中心”,然后选择“创建” 。Select IoT Hub from the search results, and then select Create.

  4. 在“基本信息”选项卡上,按如下所示填写字段: On the Basics tab, complete the fields as follows:

    • 订阅:选择要用于中心的订阅。Subscription: Select the subscription to use for your hub.

    • 资源组:选择一个资源组或新建一个资源组。Resource Group: Select a resource group or create a new one. 若要新建资源组,请选择“新建”并填写要使用的名称。 To create a new one, select Create new and fill in the name you want to use. 若要使用现有的资源组,请选择它。To use an existing resource group, select that resource group. 有关详细信息,请参阅管理 Azure 资源管理器资源组For more information, see Manage Azure Resource Manager resource groups.

    • 区域:选择中心所在的区域。Region: Select the region in which you want your hub to be located. 选择最靠近你的位置。Select the location closest to you.

    • IoT 中心名称:输入中心的名称。IoT Hub Name: Enter a name for your hub. 此名称必须全局唯一。This name must be globally unique. 如果输入的名称可用,会显示一个绿色复选标记。If the name you enter is available, a green check mark appears.

    重要

    IoT 中心将公开为 DNS 终结点,因此,命名时请务必避免包含任何敏感信息。The IoT hub will be publicly discoverable as a DNS endpoint, so make sure to avoid any sensitive information while naming it.

    在 Azure 门户中创建中心

  5. 在完成时选择“下一步: 大小和规模”,以继续创建中心。Select Next: Size and scale to continue creating your hub.

    使用 Azure 门户为新的中心设置大小和规模

    在此屏幕中可以设置以下值:This screen allows you to set the following values:

    • 定价和缩放层:选择的层。Pricing and scale tier: Your selected tier. 可以根据你需要的功能数以及每天通过解决方案发送的消息数从多个层级中进行选择。You can choose from several tiers, depending on how many features you want and how many messages you send through your solution per day. 免费层适用于测试和评估。The free tier is intended for testing and evaluation. 允许 500 台设备连接到中心,每天最多可传输 8,000 条消息。It allows 500 devices to be connected to the hub and up to 8,000 messages per day. 每个 Azure 订阅可以在免费层中创建一个 IoT 中心。Each Azure subscription can create one IoT Hub in the free tier.

    • IoT 中心单元:每个单位每日允许的消息数取决于中心的定价层。IoT Hub units: The number of messages allowed per unit per day depends on your hub's pricing tier. 例如,如果希望中心支持 700,000 条消息引入,请选择两个 S1 层单位。For example, if you want the hub to support ingress of 700,000 messages, you choose two S1 tier units. 有关其他层选项的详细信息,请参阅选择合适的 IoT 中心层For details about the other tier options, see Choosing the right IoT Hub tier.

    • 高级设置 > 设备到云的分区:此属性将设备到云消息与这些消息的同步读取器数目相关联。Advanced Settings > Device-to-cloud partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. 大多数中心只需要 4 个分区。Most hubs need only four partitions.

  6. 对于本文,请接受默认选项,然后选择“查看 + 创建”以查看所做的选择。 For this article, accept the default choices, and then select Review + create to review your choices. 会显示类似于以下的屏幕。You see something similar to this screen.

    查看用于创建新中心的信息

  7. 选择“创建”以创建新的中心 。Select Create to create your new hub. 创建中心需要几分钟时间。Creating the hub takes a few minutes.

获取 IoT 中心连接字符串Get the IoT hub connection string

在本文中,将创建一个后端服务,该服务在标识注册表中添加一个设备,然后向该设备添加一个模块。In this article, you create a back-end service that adds a device in the identity registry and then adds a module to that device. 你的服务需要“注册表写入” 权限。Your service requires the registry write permission. 默认情况下,每个 IoT 中心都使用名为 registryReadWrite 的共享访问策略创建,该策略授予此权限。By default, every IoT hub is created with a shared access policy named registryReadWrite that grants this permission.

若要获取 registryReadWrite 策略的 IoT 中心连接字符串,请执行以下步骤:To get the IoT Hub connection string for the registryReadWrite policy, follow these steps:

  1. Azure 门户中,选择“资源组” 。In the Azure portal, select Resource groups. 选择中心所在的资源组,然后从资源列表中选择中心。Select the resource group where your hub is located, and then select your hub from the list of resources.

  2. 在中心的左侧窗格中,选择“共享访问策略” 。On the left-side pane of your hub, select Shared access policies.

  3. 从策略列表中选择“registryReadWrite” 策略。From the list of policies, select the registryReadWrite policy.

  4. 在“共享访问密钥” 下,选择“连接字符串 - 主密钥” 所对应的“复制”图标并保存该值。Under Shared access keys, select the copy icon for the Connection string -- primary key and save the value.

    显示如何检索连接字符串

有关 IoT 中心共享访问策略和权限的详细信息,请参阅访问控制和权限For more information about IoT Hub shared access policies and permissions, see Access control and permissions.

在 IoT 中心中创建设备标识和模块标识Create a device identity and a module identity in IoT Hub

本部分将创建一个 Node.js 应用,用于在 IoT 中心的标识注册表中创建设备标识和模块标识。In this section, you create a Node.js app that creates a device identity and a module identity in the identity registry in your IoT hub. 设备或模块无法连接到 IoT 中心,除非它在标识注册表中具有条目。A device or module cannot connect to IoT hub unless it has an entry in the identity registry. 有关详细信息,请参阅 IoT 中心开发人员指南的“标识注册表”部分。For more information, see the "Identity registry" section of the IoT Hub developer guide. 运行此控制台应用时,它会为设备和模块生成唯一的 ID 和密钥。When you run this console app, it generates a unique ID and key for both device and module. 设备和模块在向 IoT 中心发送设备到云的消息时,使用这些值来标识自身。Your device and module use these values to identify itself when it sends device-to-cloud messages to IoT Hub. ID 区分大小写。The IDs are case-sensitive.

  1. 创建目录以保存代码。Create a directory to hold your code.

  2. 在该目录中,首先运行 npm init -y 使用默认值创建一个空的 package.json 。Inside of that directory, first run npm init -y to create an empty package.json with defaults. 这是代码的项目文件。This is the project file for your code.

  3. 运行  npm install -S azure-iothub@modules-preview,以在  node_modules  子目录中安装服务 SDK。Run npm install -S azure-iothub@modules-preview to install the service SDK inside the node_modules subdirectory.

    备注

    子目录名称 node_modules 使用字模块来表示“节点库”。The subdirectory name node_modules uses the word module to mean "a node library". 此处的术语与 IoT 中心模块无关。The term here has nothing to do with IoT Hub modules.

  4. 在目录中创建以下 .js 文件。Create the following .js file in your directory. 将它命名为 add.js 。Call it add.js. 复制并粘贴中心连接字符串和中心名称。Copy and paste your hub connection string and hub name.

    var Registry = require('azure-iothub').Registry;
    var uuid = require('uuid');
    // Copy/paste your connection string and hub name here
    var serviceConnectionString = '<hub connection string from portal>';
    var hubName = '<hub name>.azure-devices.cn';
    // Create an instance of the IoTHub registry
    var registry = Registry.fromConnectionString(serviceConnectionString);
    // Insert your device ID and moduleId here.
    var deviceId = 'myFirstDevice';
    var moduleId = 'myFirstModule';
    // Create your device as a SAS authentication device
    var primaryKey = new Buffer(uuid.v4()).toString('base64');
    var secondaryKey = new Buffer(uuid.v4()).toString('base64');
    var deviceDescription = {
      deviceId: deviceId,
      status: 'enabled',
      authentication: {
        type: 'sas',
        symmetricKey: {
          primaryKey: primaryKey,
          secondaryKey: secondaryKey
        }
      }
    };
    
    // First, create a device identity
    registry.create(deviceDescription, function(err) {
      if (err) {
        console.log('Error creating device identity: ' + err);
        process.exit(1);
      }
      console.log('device connection string = "HostName=' + hubName + ';DeviceId=' + deviceId + ';SharedAccessKey=' + primaryKey + '"');
    
    // Then add a module to that device
      registry.addModule({ deviceId: deviceId, moduleId: moduleId }, function(err) {
        if (err) {
          console.log('Error creating module identity: ' + err);
          process.exit(1);
        }
    
    // Finally, retrieve the module details from the hub so we can construct the connection string
        registry.getModule(deviceId, moduleId, function(err, foundModule) {
          if (err) {
            console.log('Error getting module back from hub: ' + err);
            process.exit(1);
          }
          console.log('module connection string = "HostName=' + hubName + ';DeviceId=' + foundModule.deviceId + ';ModuleId='+foundModule.moduleId+';SharedAccessKey=' + foundModule.authentication.symmetricKey.primaryKey + '"');
          process.exit(0);
        });
      });
    });
    

此应用在设备“myFirstDevice”下创建 ID 为“myFirstDevice”的设备标识,以及 ID 为“myFirstModule”的模块标识 。This app creates a device identity with ID myFirstDevice and a module identity with ID myFirstModule under device myFirstDevice. (如果该模块 ID 已在标识注册表中,代码就只检索现有的模块信息。)然后,应用程序会显示该标识的主密钥。(If that module ID already exists in the identity registry, the code simply retrieves the existing module information.) The app then displays the primary key for that identity. 在模拟模块应用中使用此密钥连接到 IoT 中心。You use this key in the simulated module app to connect to your IoT hub.

使用节点 add.js 运行它。Run this using node add.js. 它将为设备标识提供一个连接字符串,并为模块标识提供另一个连接字符串。It will give you a connection string for your device identity and another one for your module identity.

备注

IoT 中心标识注册表只存储设备和模块标识,以启用对 IoT 中心的安全访问。The IoT Hub identity registry only stores device and module identities to enable secure access to the IoT hub. 标识注册表存储用作安全凭据的设备 ID 和密钥。The identity registry stores device IDs and keys to use as security credentials. 标识注册表还为每个设备存储启用/禁用标志,该标志可以用于禁用对该设备的访问。The identity registry also stores an enabled/disabled flag for each device that you can use to disable access for that device. 如果应用程序需要存储其他特定于设备的元数据,则应使用特定于应用程序的存储。If your application needs to store other device-specific metadata, it should use an application-specific store. 没有针对模块标识的“已启用/已禁用”标记。There is no enabled/disabled flag for module identities. 有关详细信息,请参阅 IoT 中心开发人员指南For more information, see IoT Hub developer guide.

使用 Node.js 设备 SDK 更新模块孪生Update the module twin using Node.js device SDK

在本节中,将在更新模块孪生报告属性的模拟设备上创建 Node.js 应用。In this section, you create a Node.js app on your simulated device that updates the module twin reported properties.

  1. 获取模块连接字符串 - 登录到 Azure 门户Get your module connection string -- Sign in to the Azure portal. 导航到 IoT 中心并单击 IoT 设备。Navigate to your IoT Hub and click IoT Devices. 查找并打开 myFirstDevice,可以看到 myFirstModule 已成功创建。Find myFirstDevice, open it and you see myFirstModule was successfully created. 复制模块连接字符串。Copy the module connection string. 下一步将需要它。It is needed in the next step.

    Azure 门户模块详细信息

  2. 与上面步骤中的操作类似,为设备代码创建一个目录,使用 NPM 对它进行初始化并安装设备 SDK (npm install -S azure-iot-device-amqp@modules-preview)。Similar to you did in the step above, create a directory for your device code and use NPM to initialize it and install the device SDK (npm install -S azure-iot-device-amqp@modules-preview).

    备注

    npm install 命令可能有点慢。The npm install command may feel slow. 请耐心等待,它正在从包存储库中提取大量代码。Be patient, it's pulling down lots of code from the package repository.

    备注

    如果看到错误 npm ERR!If you see an error that says npm ERR! 分析 json 时出现注册表错误,可以安全忽略。registry error parsing json, this is safe to ignore. 如果看到错误 npm ERR!If you see an error that says npm ERR! 分析 json 时出现注册表错误,可以安全忽略。registry error parsing json, this is safe to ignore.

  3. 创建名为 twin.js 的文件。Create a file called twin.js. 复制并粘贴模块标识字符串。Copy and paste your module identity string.

    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-amqp').Amqp;
    // Copy/paste your module connection string here.
    var connectionString = '<insert module connection string here>';
    // Create a client using the Amqp protocol.
    var client = Client.fromConnectionString(connectionString, Protocol);
    client.on('error', function (err) {
      console.error(err.message);
    });
    // connect to the hub
    client.open(function(err) {
      if (err) {
        console.error('error connecting to hub: ' + err);
        process.exit(1);
      }
      console.log('client opened');
    // Create device Twin
      client.getTwin(function(err, twin) {
        if (err) {
          console.error('error getting twin: ' + err);
          process.exit(1);
        }
    // Output the current properties
        console.log('twin contents:');
        console.log(twin.properties);
    // Add a handler for desired property changes
        twin.on('properties.desired', function(delta) {
            console.log('new desired properties received:');
            console.log(JSON.stringify(delta));
        });
    // create a patch to send to the hub
        var patch = {
          updateTime: new Date().toString(),
          firmwareVersion:'1.2.1',
          weather:{
            temperature: 72,
            humidity: 17
          }
        };
    // send the patch
        twin.properties.reported.update(patch, function(err) {
          if (err) throw err;
          console.log('twin state reported');
        });
      });
    });
    
  4. 现在请使用命令 node twin.js 来运行它  。Now, run this using the command node twin.js.

    F:\temp\module_twin>node twin.js
    

    然后,你将看到:You will then see:

    client opened
    twin contents:
    { reported: { update: [Function: update], '$version': 1 },
      desired: { '$version': 1 } }
    new desired properties received:
    {"$version":1}
    twin state reported
    

后续步骤Next steps

若要继续了解 IoT 中心入门知识并浏览其他 IoT 方案,请参阅:To continue getting started with IoT Hub and to explore other IoT scenarios, see: