快速入门:使用对称密钥向 IoT 中心预配模拟设备Quickstart: Provision a simulated device to IoT Hub with symmetric keys

本快速入门介绍如何在 Windows 开发计算机上创建和运行设备模拟器。In this quickstart, you will learn how to create and run a device simulator on a Windows development machine. 你将配置此模拟设备,以使用对称密钥对设备预配服务 (DPS) 实例进行身份验证,并将此模拟设备分配到 IoT 中心。You will configure this simulated device to use a symmetric key to authenticate with a Device Provisioning Service (DPS) instance and be assigned to an IoT hub. 将使用适用于 Java 的 Microsoft Azure IoT SDK 中的示例代码来模拟启动预配的设备的启动序列。Sample code from the Microsoft Azure IoT SDKs for Java will be used to simulate a boot sequence for the device that initiates provisioning. 将根据 DPS 服务实例的单个注册来识别该设备,然后将其分配到 IoT 中心。The device will be recognized based on an individual enrollment with a DPS service instance and assigned to an IoT hub.

虽然本文演示了使用单个注册进行预配,但你也可以使用注册组。Although this article demonstrates provisioning with an individual enrollment, you can 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. 虽然对称密钥注册组不限于旧设备,但如何使用对称密钥证明预配旧设备提供了注册组示例。Although symmetric key enrollment groups are not limited to legacy devices, How to provision legacy devices using Symmetric key attestation provides an enrollment group example. 有关详细信息,请参阅对称密钥证明的组注册For more information, see Group Enrollments for Symmetric Key Attestation.

如果你不熟悉自动预配过程,请查看自动预配的概念If you're unfamiliar with the process of auto-provisioning, review Auto-provisioning concepts.

另外,在继续学习本快速入门之前,请确保已完成通过 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 How to provision for multitenancy.

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

先决条件Prerequisites

准备 Java SDK 环境Prepare the Java SDK environment

  1. 确保在计算机上安装 Git 并将其添加到可供命令窗口访问的环境变量。Make sure Git is installed on your machine and is added to the environment variables accessible to the command window. 请参阅软件自由保护组织提供的 Git 客户端工具,了解要安装的最新版 git 工具,其中包括 Git Bash,这是一个命令行应用,可以用来与本地 Git 存储库交互。See Software Freedom Conservancy's Git client tools for the latest version of git tools to install, which includes the Git Bash, the command-line app that you can use to interact with your local Git repository.

  2. 打开命令提示符。Open a command prompt. 为设备模拟代码示例克隆 GitHub 存储库:Clone the GitHub repo for device simulation code sample:

    git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
    
  3. 导航到 azure-iot-sdk-java 根目录,并生成项目以下载全部所需的包。Navigate to the root azure-iot-sdk-java directory and build the project to download all needed packages.

    cd azure-iot-sdk-java
    mvn install -DskipTests=true
    

创建设备注册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-java-device-007For example, symm-key-java-device-007.

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

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

  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-java-device-007” 。Your symmetric key device enrollment appears as symm-key-java-device-007 under the Registration ID column in the Individual Enrollments tab.

    打开注册并复制生成的“主要密钥” 的值。Open the enrollment and copy the value of your generated Primary Key. 稍后在更新设备的 Java 代码时,将使用此密钥值和注册 IDYou will use this key value and the Registration ID later when you update the Java code for the device.

模拟设备启动序列Simulate device boot sequence

在本部分,你将更新向 DPS 实例发送设备启动序列的设备示例代码。In this section, you will update the device sample code to send the device's boot sequence to your DPS instance. 此启动序列使得设备可被识别、完成身份验证,并分配到与 DPS 实例链接的 IoT 中心。This boot sequence will cause the device to be recognized, authenticated, and assigned to an IoT hub linked to the DPS instance.

  1. 在“设备预配服务”菜单中选择“概述”,并记下“ID 范围”和“预配服务全局终结点”。From the Device Provisioning Service menu, select Overview and note your ID Scope and Provisioning Service Global Endpoint.

    服务信息

  2. 打开 Java 设备示例代码进行编辑。Open the Java device sample code for editing. 设备示例代码的完整路径为:The full path to the device sample code is:

    azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-symmetrickey-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningSymmetricKeySampleSample.java

    • 添加 DPS 实例的“ID 范围”和“预配服务全局终结点” 。Add the ID Scope and Provisioning Service Global Endpoint of your DPS instance. 另外,包含你为单独注册选择的主对称密钥和注册 ID。Also include the primary symmetric key and the registration ID you chose for your individual enrollment. 保存所做更改。Save your changes.

         private static final String SCOPE_ID = "[Your scope ID here]";
         private static final String GLOBAL_ENDPOINT = "[Your Provisioning Service Global Endpoint here]";
         private static final String SYMMETRIC_KEY = "[Enter your Symmetric Key here]";
         private static final String REGISTRATION_ID = "[Enter your Registration ID here]";
      
  3. 打开命令提示符进行生成。Open a command prompt for building. 导航到 Java SDK 存储库的预配示例项目文件夹。Navigate to the provisioning sample project folder of the Java SDK repository.

    cd azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-symmetrickey-sample
    
  4. 生成示例,然后导航到 target 文件夹执行所创建的 .jar 文件。Build the sample then navigate to the target folder to execute the created .jar file.

    mvn clean install
    cd target
    java -jar ./provisioning-symmetrickey-sample-{version}-with-deps.jar
    
  5. 预期的输出应如下所示:The expected output should look similar to the following:

      Starting...
      Beginning setup.
      Waiting for Provisioning Service to register
      IotHUb Uri : <Your DPS Service Name>.azure-devices.cn
      Device ID : java-device-007
      Sending message from device to IoT Hub...
      Press any key to exit...
      Message received! Response status: OK_EMPTY
    
  6. 在 Azure 门户中,导航到已链接到预配服务的 IoT 中心,然后打开“Device Explorer”边栏选项卡。In the Azure portal, navigate to the IoT hub linked to your provisioning service and open the Device Explorer blade. 将模拟的对称密钥设备成功预配到中心后,设备 ID 会显示在“Device Explorer”边栏选项卡上,“状态”为“已启用”。After successful provisioning the simulated symmetric key device to the hub, its device ID appears on the Device Explorer blade, 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 sample device application.

    设备注册到 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. 关闭计算机上的设备客户端示例输出窗口。Close the device client sample output window on your machine.
  2. 在 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.
  3. 在 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

本快速入门介绍了如何在 Windows 计算机上创建模拟设备,以及如何在门户中通过 Azure IoT 中心设备预配服务使用对称密钥将其预配到 IoT 中心。In this quickstart, you’ve created a simulated device on your Windows machine and provisioned it to your IoT hub using Symmetric key with the Azure IoT Hub Device Provisioning Service on the portal. 若要了解如何以编程方式注册设备,请继续学习快速入门中关于 X.509 设备的编程注册部分的内容。To learn how to enroll your device programmatically, continue to the quickstart for programmatic enrollment of X.509 devices.