快速入门:使用适用于 IoT 中心设备预配服务的 Python 设备 SDK 创建和预配模拟的 X.509 设备Quickstart: Create and provision a simulated X.509 device using Python device SDK for IoT Hub Device Provisioning Service

在本快速入门中,我们在 Windows 计算机上创建一台模拟 X.509 设备。In this quickstart, you create a simulated X.509 device on a Windows computer. 我们使用设备预配服务 (DPS) 的单个注册,通过设备示例 Python 代码将此模拟设备连接到 IoT 中心。You use device sample Python code to connect this simulated device with your IoT hub using an individual enrollment with the Device Provisioning Service (DPS).

先决条件Prerequisites

重要

本文仅适用于已弃用的 V1 Python SDK。This article only applies to the deprecated V1 Python SDK. V2 中尚不提供用于 IoT 中心设备预配服务的设备和服务客户端。Device and service clients for the Iot Hub Device Provisioning Service are not yet available in V2. 该团队目前正在努力使 V2 具有功能奇偶一致性。The team is currently hard at work to bring V2 to feature parity.

备注

初始的设备孪生状态配置仅在 IoT 中心的标准层中提供。The initial device twin state configuration is available only in the standard tier of IoT Hub. 有关基本和标准 IoT 中心层的详细信息,请参阅如何选择合适的 IoT 中心层For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

准备环境Prepare the environment

  1. 确保你已安装了 Visual Studio 2015 或更高版本,并为你的 Visual Studio 安装启用“使用 C++ 的桌面开发”。Make sure you have installed either Visual Studio 2015 or later, with the 'Desktop development with C++' workload enabled for your Visual Studio installation.

  2. 下载并安装 CMake 生成系统Download and install the CMake build system.

  3. 确保在计算机上安装 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.

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

    git clone https://github.com/Azure/azure-iot-sdk-python.git --recursive
    
  5. 在该 GitHub 存储库的本地副本中创建一个用于 CMake 生成过程的文件夹。Create a folder in your local copy of this GitHub repo for CMake build process.

    cd azure-iot-sdk-python/c
    mkdir cmake
    cd cmake
    
  6. 运行以下命令,为预配客户端创建 Visual Studio 解决方案。Run the following command to create the Visual Studio solution for the provisioning client.

    cmake -Duse_prov_client:BOOL=ON ..
    

创建自签名的 X.509 设备证书和单个注册项Create a self-signed X.509 device certificate and individual enrollment entry

在本部分中,将使用自签名的 X.509 证书。In this section you, will use a self-signed X.509 certificate. 请务必记住以下几点:It is important to keep in mind the following points:

  • 自签名证书仅用于测试,不应在生产环境中使用。Self-signed certificates are for testing only, and should not be used in production.
  • 自签名证书的默认过期日期为一年。The default expiration date for a self-signed certificate is one year.

你将使用来自 Azure IoT C SDK 的示例代码创建要与模拟设备的个人注册条目一起使用的证书。You will use sample code from the Azure IoT C SDK to create the certificate to be used with the individual enrollment entry for the simulated device.

Azure IoT 设备预配服务支持两类注册:The Azure IoT Device Provisioning Service supports two types of enrollments:

本文演示单个注册。This article demonstrates individual enrollments.

  1. 打开在 cmake 文件夹中生成的名为 azure_iot_sdks.sln 的解决方案,将其内置到 Visual Studio 中。Open the solution generated in the cmake folder named azure_iot_sdks.sln, and build it in Visual Studio.

  2. 右键单击 Provision_Tools 文件夹中的 dice_device_enrollment 项目,然后选择“设置为启动项目”。Right-click the dice_device_enrollment project under the Provision_Tools folder, and select Set as Startup Project. 运行解决方案。Run the solution.

  3. 在输出窗口中,当系统提示时输入 i 进行单独注册。In the output window, enter i for individual enrollment when prompted. 输出窗口会显示在本地为模拟设备生成的 X.509 证书。The output window displays a locally generated X.509 certificate for your simulated device.

    Copy the first certificate to clipboard. Begin with the first occurrence of:
    
        -----BEGIN CERTIFICATE----- 
    
    End you copying after the first occurrence of:
    
        -----END CERTIFICATE-----
    
    Make sure to include both of those lines as well.
    

    Dice 设备注册应用程序

  4. 在 Windows 计算机上创建名为 X509testcertificate.pem 的文件,在所选编辑器中将其打开,然后将剪贴板内容复制到该文件中。Create a file named X509testcertificate.pem on your Windows machine, open it in an editor of your choice, and copy the clipboard contents to this file. 保存文件。Save the file.

  5. 登录到 Azure 门户,选择左侧菜单上的“所有资源”按钮,打开预配服务。Sign in to the Azure portal, select the All resources button on the left-hand menu and open your provisioning service.

  6. 在“设备预配服务”菜单中,选择“管理注册”。From the Device Provisioning Service menu, select Manage enrollments. 选择“个人注册”选项卡,然后选择顶部的“添加个人注册”按钮 。Select Individual Enrollments tab and select the Add individual enrollment button at the top.

  7. 在“添加注册”面板中,输入以下信息:In the Add Enrollment panel, enter the following information:

    • 选择“X.509”作为标识证明机制。Select X.509 as the identity attestation Mechanism.

    • 在“主要证书 .pem 或 .cer 文件”下,选择“选择文件”以选择在前述步骤中创建的证书文件 X509testcertificate.pem 。Under the Primary certificate .pem or .cer file, choose Select a file to select the certificate file X509testcertificate.pem created in the previous steps.

    • (可选)可以提供以下信息:Optionally, you may provide the following information:

      • 选择与预配服务链接的 IoT 中心。Select an IoT hub linked with your provisioning service.
      • 输入唯一设备 ID。Enter a unique device ID. 为设备命名时,请确保避免使用敏感数据。Make sure to avoid sensitive data while naming your device.
      • 使用设备所需的初始配置更新“初始设备孪生状态”。Update the Initial device twin state with the desired initial configuration for the device.
    • 完成后,按“保存”按钮。Once complete, press the Save button.

      在门户中为 X.509 证明添加单个注册Add individual enrollment for X.509 attestation in the portal

    成功注册以后,X.509 设备会在“单个注册”选项卡的“注册 ID”列下显示为 riot-device-certUpon successful enrollment, your X.509 device appears as riot-device-cert under the Registration ID column in the Individual Enrollments tab.

模拟设备Simulate the device

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

    服务信息

  2. 下载并安装 Python 2.x 或 3.xDownload and install Python 2.x or 3.x. 请确保根据安装程序的要求,使用 32 位或 64 位安装。Make sure to use the 32-bit or 64-bit installation as required by your setup. 在安装过程中出现提示时,请确保将 Python 添加到特定于平台的环境变量中。When prompted during the installation, make sure to add Python to your platform-specific environment variables. 如果使用 Python 2.x,则可能需要安装或升级 pip - Python 包管理系统If you are using Python 2.x, you may need to install or upgrade pip, the Python package management system.

    备注

    如果使用的是 Windows,还需要安装 Visual C++ Redistributable for Visual Studio 2015If you are using Windows, also install the Visual C++ Redistributable for Visual Studio 2015. pip 包需要可再发行组件,才能加载/执行 C DLL。The pip packages require the redistributable in order to load/execute the C DLLs.

  3. 按照这些说明生成 Python 包。Follow these instructions to build the Python packages.

    备注

    如果使用 pip,请确保也安装 azure-iot-provisioning-device-client 包。If using pip make sure to also install the azure-iot-provisioning-device-client package.

  4. 导航到示例文件夹。Navigate to the samples folder.

    cd azure-iot-sdk-python/provisioning_device_client/samples
    
  5. 使用 Python IDE,编辑名为 provisioning_device_client_sample.py 的 Python 脚本。Using your Python IDE, edit the python script named provisioning_device_client_sample.py. GLOBAL_PROV_URIID_SCOPE 变量修改为以前记下的值。Modify the GLOBAL_PROV_URI and ID_SCOPE variables to the values noted previously.

    GLOBAL_PROV_URI = "{globalServiceEndpoint}"
    ID_SCOPE = "{idScope}"
    SECURITY_DEVICE_TYPE = ProvisioningSecurityDeviceType.X509
    PROTOCOL = ProvisioningTransportProvider.HTTP
    
  6. 运行该示例。Run the sample.

    python provisioning_device_client_sample.py
    
  7. 应用程序会进行连接,注册设备,然后显示注册成功的消息。The application will connect, enroll the device, and display a successful enrollment message.

    成功注册

  8. 在门户中导航到已链接到预配服务的 IoT 中心,然后打开“Device Explorer”边栏选项卡。In the portal, navigate to the IoT hub linked to your provisioning service and open the Device Explorer blade. 将模拟的 X.509 设备成功预配到中心以后,设备 ID 会显示在“Device Explorer”边栏选项卡上,“状态”为“已启用”。On successful provisioning of the simulated X.509 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 the Manage Enrollments blade 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 the IoT devices blade 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 计算机上创建模拟 X.509 设备,以及如何使用门户中的 Azure IoT 中心设备预配服务将其预配到 IoT 中心。In this quickstart, you’ve created a simulated X.509 device on your Windows machine and provisioned it to your IoT hub using the Azure IoT Hub Device Provisioning Service on the portal. 若要了解如何以编程方式注册 X.509 设备,请继续阅读快速入门中关于 X.509 设备的编程注册内容。To learn how to enroll your X.509 device programmatically, continue to the quickstart for programmatic enrollment of X.509 devices.