快速入门:使用 Node.js 预配对称密钥设备Quickstart: Provision a symmetric key device using Node.js

本快速入门将介绍如何使用 Node.js 将 Windows 开发计算机作为设备预配到 IoT 中心。In this quickstart, you will learn how to provision a Windows development machine as a device to an IoT hub using Node.js. 此设备将使用对称密钥和单个注册对设备预配服务 (DPS) 实例进行身份验证,以便被分配到 IoT 中心。This device will use a symmetric key and an individual enrollment to authenticate with a Device Provisioning Service (DPS) instance in order to be assigned to an IoT hub. 适用于 Node.js 的 Azure IoT SDK 中的示例代码将用于预配设备。Sample code from the Azure IoT SDK for Node.js will be used to provision the device.

虽然本文演示了使用单个注册进行预配,但你也可以使用注册组。Although this article demonstrates provisioning with an individual enrollment, you can also use enrollment groups. 使用注册组时有一些不同之处。There are some differences when using enrollment groups. 例如,必须将派生的设备密钥与设备的唯一注册 ID 一起使用。For example, you must use a derived device key with a unique registration ID for the device. 使用对称密钥预配设备提供了注册组示例。Provision devices with symmetric keys provides an enrollment group example. 有关注册组的详细信息,请参阅对称密钥证明的组注册For more information on enrollment groups, see Group Enrollments for Symmetric Key Attestation.

如果不熟悉自动预配过程,请查看预配概述。If you're unfamiliar with the process of auto-provisioning, review the provisioning overview.

另外,在继续学习本快速入门之前,请确保已完成通过 Azure 门户设置 IoT 中心设备预配服务中的步骤。Also, make sure you've completed the steps in Set up IoT Hub Device Provisioning Service with the Azure portal before continuing with this quickstart. 本快速入门需要你已创建设备预配服务实例。This quickstart requires you to have already created your Device Provisioning Service instance.

本文面向基于 Windows 的工作站。This article is oriented toward a Windows-based workstation. 但是,你也可以在 Linux 上执行过程。However, you can perform the procedures on Linux. 对于 Linux 示例,请参阅多租户预配For a Linux example, see Provision for multitenancy.

如果没有 Azure 试用版订阅,请在开始前创建一个试用版订阅If you don't have an Azure trail subscription, create a trial subscription before you begin.

先决条件Prerequisites

创建设备注册Create a device enrollment

  1. 登录到 Azure 门户,选择左侧菜单上的“所有资源”按钮,打开设备预配服务 (DPS) 实例。Sign in to the Azure portal, select the All resources button on the left-hand menu and open your Device Provisioning service (DPS) instance.

  2. 选择“管理注册”选项卡,然后选择顶部的“添加个人注册”按钮 。Select the Manage enrollments tab, and then select the Add individual enrollment button at the top.

  3. 在“添加注册”面板中输入以下信息,然后按“保存”按钮 。In the Add Enrollment panel, enter the following information, and press the Save button.

    • 机制:选择“对称密钥”作为标识证明“机制” 。Mechanism: Select Symmetric Key as the identity attestation Mechanism.

    • 自动生成密钥:选中此框。Auto-generate keys: Check this box.

    • 注册 ID:输入注册 ID 以标识注册。Registration ID: Enter a registration ID to identify the enrollment. 仅使用小写字母数字和短划线(“-”)字符。Use only lowercase alphanumeric and dash ('-') characters. 例如 symm-key-nodejs-device-01。For example, symm-key-nodejs-device-01.

    • IoT 中心设备 ID: 输入设备标识符。IoT Hub Device ID: Enter a device identifier. 例如 nodejs-device-01。For example, nodejs-device-01.

      在门户中为对称密钥证明添加单个注册

  4. 保存注册后,将生成“主要密钥”和“辅助密钥”,并将其添加到注册条目 。Once you have saved your enrollment, the Primary Key and Secondary Key will be generated and added to the enrollment entry. 对称密钥设备注册会在“单个注册”选项卡的“注册 ID”列下显示为“symm-key-nodejs-device-01” 。Your symmetric key device enrollment appears as symm-key-nodejs-device-01 under the Registration ID column in the Individual Enrollments tab.

  5. 打开注册并复制生成的“主要密钥”的值。Open the enrollment and copy the value of your generated Primary Key. 稍后你将在添加用于设备预配示例代码的环境变量时使用此密钥值和“注册 ID”。You will use this key value and the Registration ID later when you add environment variables for use with the device provisioning sample code.

准备 Node.js 环境Prepare the Node.js environment

  1. 打开 Git CMD 或 Git Bash 命令行环境。Open a Git CMD or Git Bash command-line environment. 使用以下命令克隆适用于 Node.js 的 Azure IoT SDK GitHub 存储库:Clone the Azure IoT SDK for Node.js GitHub repository using the following command:

    git clone https://github.com/Azure/azure-iot-sdk-node.git --recursive
    

准备设备预配代码Prepare the device provisioning code

本部分将添加以下四个环境变量,这些变量将作为参数用于设备预配示例代码,以预配对称密钥设备。In this section, you will add the following four environment variables that will be used as parameters for the device provisioning sample code to provision your symmetric key device.

  • PROVISIONING_HOST
  • PROVISIONING_IDSCOPE
  • PROVISIONING_REGISTRATION_ID
  • PROVISIONING_SYMMETRIC_KEY

预配代码将根据这些变量联系 DPS 实例,以便对设备进行身份验证。The provisioning code will contact the DPS instance based on these variables in order to authenticate your device. 然后,会根据单个注册配置将设备分配到已链接到 DPS 实例的 IoT 中心。The device will then be assigned to an IoT hub already linked to the DPS instance based on the individual enrollment configuration. 预配后,示例代码会将一些测试遥测发送到 IoT 中心。Once provisioned, the sample code will send some test telemetry to the IoT hub.

  1. Azure 门户中的“设备预配服务”菜单上,选择“概述”,并复制“服务终结点”和“ID 范围” 。In the Azure portal, on your Device Provisioning Service menu, select Overview and copy your Service Endpoint and ID Scope. 你会将这些值用于 PROVISIONING_HOSTPROVISIONING_IDSCOPE 环境变量。You will use these values for the PROVISIONING_HOST and PROVISIONING_IDSCOPE environment variables.

    服务信息

  2. 打开用于执行 Node.js 命令的命令提示符,然后导航到以下 provisioning/device/samples 目录。Open a command prompt for executing Node.js commands, and navigate to the following provisioning/device/samples directory.

    cd azure-iot-sdk-node/provisioning/device/samples
    
  3. 在“provisioning/device/samples”文件夹中打开“register_symkey.js”并查看代码 。In the provisioning/device/samples folder, open register_symkey.js and review the code.

    请注意,示例代码将设置自定义有效负载…Notice the sample code sets a custom payload...

    provisioningClient.setProvisioningPayload({a: 'b'});
    

    本快速入门不需要此代码。This code is not needed with this quick start. 如果要使用自定义分配函数将设备分配到 IoT 中心,可参考此代码示例设置自定义有效负载。This code is an example of setting a custom payload if you wanted to use a custom allocation function to assign your device to an IoT Hub. 有关详细信息,请参阅教程:使用自定义分配策略For more information, see Tutorial: Use custom allocation policies.

    使用 provisioningClient.register() 方法尝试注册设备。The provisioningClient.register() method attempts the registration of your device.

    无需对示例代码进行任何更改即可注册设备。No changes will be necessary to the sample code to register your device.

  4. 在命令提示符中,为上一部分从单个注册中复制的预配主机、ID 范围、注册 ID 和主对称密钥添加环境变量。In your command prompt, add the environment variables for the provisioning host, ID Scope, registration ID, and primary symmetric key you copied from the individual enrollment in the previous section.

    以下命令是展示命令语法的示例。The following commands are examples to show command syntax. 确保使用正确的值。Make sure to use your correct values.

    set PROVISIONING_HOST=test-dps-docs.azure-devices-provisioning.cn
    
    set PROVISIONING_IDSCOPE=0ne00000A0A
    
    set PROVISIONING_REGISTRATION_ID=symm-key-nodejs-device-01
    
    set PROVISIONING_SYMMETRIC_KEY=sbDDeEzRuEuGKag+kQKV+T1QGakRtHpsERLP0yPjwR93TrpEgEh/Y07CXstfha6dhIPWvdD1nRxK5T0KGKA+nQ==
    
  5. 使用以下命令生成和运行示例代码。Build and run the sample code using the following commands.

    npm install
    
    node register_symkey.js
    
  6. 预期输出应与以下内容类似,其中显示根据单个注册设置设备被分配到的已链接的 IoT 中心。The expected output should look similar to the following that shows the linked IoT hub that the device was assigned to based on the individual enrollment settings. “Hello World”字符串将作为测试消息发送到此中心:A "Hello World" string is sent to the hub as a test message:

    D:\Docs\test\azure-iot-sdk-node\provisioning\device\samples>node register_symkey.js
    registration succeeded
    assigned hub=docs-test-iot-hub.azure-devices.net
    deviceId=nodejs-device-01
    payload=undefined
    Client connected
    send status: MessageEnqueued    
    
  7. 在 Azure 门户中,导航到已链接到预配服务的 IoT 中心,并打开“IoT 设备”边栏选项卡。In the Azure portal, navigate to the IoT hub linked to your provisioning service and open the IoT devices blade. 成功将对称密钥设备预配到中心后,设备 ID 的“状态”会显示为“已启用”。After successfully provisioning the symmetric key device to the hub, the device ID is shown with STATUS as enabled. 如果在运行设备示例代码前已打开边栏选项卡,则可能需要按顶部的“刷新”按钮。You might need to press the Refresh button at the top if you already opened the blade prior to running the device sample code.

    设备注册到 IoT 中心

备注

如果从设备的注册项中的默认值更改了“初始设备孪生状态” ,则它会从中心拉取所需的孪生状态,并执行相应的操作。If you changed the initial device twin state from the default value in the enrollment entry for your device, it can pull the desired twin state from the hub and act accordingly. 有关详细信息,请参阅了解并在 IoT 中心内使用设备孪生For more information, see Understand and use device twins in IoT Hub.

清理资源Clean up resources

如果打算继续使用和探索设备客户端示例,请勿清理在本快速入门中创建的资源。If you plan to continue working on and exploring the device client sample, do not clean up the resources created in this quickstart. 如果不打算继续学习,请按以下步骤删除本快速入门中创建的所有资源。If you do not plan to continue, use the following steps to delete all resources created by this quickstart.

  1. 在 Azure 门户的左侧菜单中选择“所有资源”,然后选择设备预配服务。From the left-hand menu in the Azure portal, select All resources and then select your Device Provisioning service. 打开服务的“管理注册”,然后选择“个人注册”选项卡 。选中在本快速入门中注册的设备的“注册 ID”旁边的复选框,然后按窗格顶部的“删除”按钮 。Open Manage Enrollments for your service, and then select the Individual Enrollments tab. Select the check box next to the REGISTRATION ID of the device you enrolled in this quickstart, and press the Delete button at the top of the pane.
  2. 在 Azure 门户的左侧菜单中选择“所有资源”,然后选择 IoT 中心 。From the left-hand menu in the Azure portal, select All resources and then select your IoT hub. 打开中心的“IoT 设备”,选中在本快速入门中注册的设备的“设备 ID”旁边的复选框,然后按窗格顶部的“删除”按钮 。Open IoT devices for your hub, select the check box next to the DEVICE ID of the device you registered in this quickstart, and then press the Delete button at the top of the pane.

后续步骤Next steps

在此快速入门中,你使用 IoT 中心设备预配服务将基于 Windows 的对称密钥设备预配到了 IoT 中心。In this quickstart, you provisioned a Windows-based symmetric key device to your IoT hub using the IoT Hub Device Provisioning Service. 若要了解如何使用 Node.js 预配 X.509 证书设备,请继续阅读下面的 X.509 设备快速入门。To learn how to provision X.509 certificate devices using Node.js, continue with the quickstart below for X.509 devices.