快速入门:使用 Java 将 X.509 设备注册到设备预配服务
在本快速入门中,你将使用 Java 以编程方式将一组 X.509 模拟设备注册到 Azure IoT 中心设备预配服务。 通过创建注册组或单个注册,将设备注册到预配服务实例。 本快速入门介绍如何使用 Java 服务 SDK 和示例 Java 应用程序创建这两种类型的注册。
先决条件
- 完成使用 Azure 门户设置 IoT 中心设备预配服务。
- 具有活动订阅的 Azure 帐户。 创建试用版订阅。
- Java SE 开发工具包 8。 本快速入门将在下面安装 Java 服务 SDK。 它可以在 Windows 和 Linux 上运行。 本快速入门使用 Windows。
- Maven 3。
- Git。
下载并修改 Java 示例代码
本部分中将使用自签名 X.509 证书,请务必记住以下要点:
- 自签名证书仅用于测试,不应在生产环境中使用。
- 自签名证书的默认过期日期为一年。
下面的步骤展示了如何向示例代码添加 X.509 设备的预配详细信息。
打开命令提示符。 使用 Java 服务 SDK 克隆设备注册代码示例的 GitHub 存储库:
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
在下载的源代码中,导航到示例文件夹 azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample 。 在所选编辑器中打开文件 /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java ,添加以下详细信息:
在门户中为预配服务添加
[Provisioning Connection String]
,如下所示:在 Azure 门户中导航到预配服务。
打开“共享访问策略”,选择具有 EnrollmentWrite 权限的策略。
复制“主密钥连接字符串” 。
在示例代码文件 ServiceEnrollmentGroupSample.java 中,将
[Provisioning Connection String]
替换为“主密钥连接字符串”。private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";
添加此组设备的根证书。 如需示例根证书,请使用 X.509 证书生成器工具,如下所示:
在命令窗口中,导航到文件夹 azure-iot-sdk-java/provisioning/provisioning-tools/provisioning-x509-cert-generator 。
通过运行以下命令来生成工具:
mvn clean install
使用以下命令来运行工具:
cd target java -jar ./provisioning-x509-cert-generator-{version}-with-deps.jar
出现提示时,可以选择性地为证书输入“公用名称” 。
此工具在本地生成“客户端证书”、“客户端证书私钥”和“根证书”。
复制“根证书”, 包括 -----BEGIN CERTIFICATE----- 行和 -----END CERTIFICATE----- 行。
将“根证书”的值指定给 参数 PUBLIC_KEY_CERTIFICATE_STRING,如下所示:
private static final String PUBLIC_KEY_CERTIFICATE_STRING = "-----BEGIN CERTIFICATE-----\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "-----END CERTIFICATE-----\n";
关闭命令窗口,或者在系统提示输入“验证码”时输入 。
也可选择通过示例代码配置预配服务:
若要将此配置添加到示例,请执行以下步骤:
在 Azure 门户中导航到已链接到预配服务的 IoT 中心。 打开中心的“概览”选项卡,复制“主机名”。 将该“主机名” 指定给 IOTHUB_HOST_NAME 参数。
private static final String IOTHUB_HOST_NAME = "[Host name].azure-devices.cn";
为 DEVICE_ID 参数指定一个友好名称,并保留 PROVISIONING_STATUS 的默认值 ENABLED。
或者,如果选择不配置预配服务,请确保注释掉或删除 ServiceEnrollmentGroupSample.java 文件中的以下语句:
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME); // Optional parameter. enrollmentGroup.setProvisioningStatus(ProvisioningStatus.ENABLED); // Optional parameter.
研究示例代码。 此代码用于创建、更新、查询和删除 X.509 设备的组注册。 若要验证是否已在门户中成功注册,请暂时性地注释掉 ServiceEnrollmentGroupSample.java 文件末尾的以下代码行:
// ************************************** Delete info of enrollmentGroup *************************************** System.out.println("\nDelete the enrollmentGroup..."); provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
保存 ServiceEnrollmentGroupSample.java 文件。
生成并运行示例组注册
Azure IoT 设备预配服务支持两类注册:
此过程使用注册组。 下一部分使用单个注册。
打开命令窗口,导航到文件夹 azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample 。
使用以下命令生成示例代码:
mvn install -DskipTests
此命令将 Maven 包
com.microsoft.azure.sdk.iot.provisioning.service
下载到计算机。 此包包括示例代码需要生成的适用于 Java 服务 SDK 的二进制文件。 如果在上一部分运行了 X.509 证书生成器工具,则此包已下载到计算机上。运行示例,方法是在命令窗口使用以下命令:
cd target java -jar ./service-enrollment-group-sample-{version}-with-deps.jar
在成功注册后观察输出窗口。
在 Azure 门户中导航到预配服务。 单击“管理注册”。 请注意,X.509 设备组显示在“注册组”选项卡下,带有自动生成的“组名称”。
注册单个 X.509 设备所需的修改
若要注册单个 X.509 设备,请修改使用 Java 服务 SDK 将 TPM 设备注册到 IoT 中心设备预配服务一文中使用的单个注册 示例代码,如下所示:
将 X.509 客户端证书的“公用名称”复制到剪贴板。 如果希望使用上一示例代码部分所示的 X.509 证书生成器工具,请输入证书的“公用名称”,或者使用默认的 microsoftriotcore。 将该“公用名称”用作 REGISTRATION_ID 变量的值。
// Use common name of your X.509 client certificate private static final String REGISTRATION_ID = "[RegistrationId]";
将变量 TPM_ENDORSEMENT_KEY 重命名为 PUBLIC_KEY_CERTIFICATE_STRING。 复制你的客户端证书或者 “X.509 证书生成器”工具的输出中的“客户端证书”,作为 PUBLIC_KEY_CERTIFICATE_STRING 变量的值。
// Rename the variable *TPM_ENDORSEMENT_KEY* as *PUBLIC_KEY_CERTIFICATE_STRING* private static final String PUBLIC_KEY_CERTIFICATE_STRING = "-----BEGIN CERTIFICATE-----\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" + "-----END CERTIFICATE-----\n";
在 main 函数中,将
Attestation attestation = new TpmAttestation(TPM_ENDORSEMENT_KEY);
行替换为以下内容,以便使用 X.509 客户端证书:Attestation attestation = X509Attestation.createFromClientCertificates(PUBLIC_KEY_CERTIFICATE_STRING);
使用生成并运行个人注册的示例代码部分的步骤保存、生成和运行个人注册 示例文件。
清理资源
如果打算学习 Java 服务示例,请勿清理本快速入门中创建的资源。 如果不打算继续学习,请按以下步骤删除本快速入门中创建的所有资源。
- 关闭计算机上的 Java 示例输出窗口。
- 关闭计算机上的“X509 证书生成器” 窗口。
- 在 Azure 门户中导航到设备预配服务,选择“管理注册”,然后选择“注册组”选项卡 。选中通过本快速入门注册的 X.509 设备的“组名称”旁边的复选框,然后按窗格顶部的“删除”按钮 。
后续步骤
在本快速入门中,你将模拟的 X.509 设备组注册到了设备预配服务。 若要深入了解设备预配,请继续学习本教程有关如何在 Azure 门户中进行设备预配服务设置的内容。