教程:使用 Linux 容器开发 Java IoT Edge 模块

适用于:“是”图标 IoT Edge 1.1 “是”图标 IoT Edge 1.2

可以使用 Azure IoT Edge 模块部署代码,直接将业务逻辑实现到 IoT Edge 设备。 本教程详细介绍如何创建并部署用于筛选传感器数据的 IoT Edge 模块。 你将使用在快速入门文章的“在模拟设备上部署 Azure IoT Edge”部分创建的模拟 IoT Edge 设备。 在本教程中,你将了解如何执行以下操作:

  • 使用 Visual Studio Code,根据 Azure IoT Edge maven 模板包和 Azure IoT Java 设备 SDK 创建 IoT Edge Java 模块。
  • 使用 Visual Studio Code 和 Docker 创建 Docker 映像并将其发布到注册表。
  • 将模块部署到 IoT Edge 设备。
  • 查看生成的数据。

在本教程中创建的 IoT Edge 模块可以筛选由设备生成的温度数据。 它只在温度高于指定阈值的情况下,向上游发送消息。 在边缘进行的此类分析适用于减少传递到云中和存储在云中的数据量。

如果没有 Azure 订阅,可在开始前创建一个试用帐户

先决条件

本教程演示如何在 Visual Studio Code 中使用 Java 开发模块,以及如何将其部署到 IoT Edge 设备。 IoT Edge 不支持以 Windows 容器形式生成的 Java 模块。

使用下表了解用于开发和部署 Java 模块的选项:

Java Visual Studio Code Visual Studio 2017/2019
Linux AMD64 将 VS Code 用于 Linux AMD64 上的 Java 模块
Linux ARM32 将 VS Code 用于 Linux ARM32 上的 Java 模块

在开始学习本教程之前,应已完成上一篇教程来设置用于开发 Linux 容器的开发环境:开发适用于 Linux 设备的 IoT Edge 模块。 完成这两个教程中的一个以后,你应该已经准备好以下必备组件:

若要开发以 Java 编写的 IoT Edge 模块,请在开发计算机上安装下述额外的必备组件:

  • 适用于 Visual Studio Code 的 Java 扩展包

  • Java SE 开发工具包 11。请JAVA_HOME 环境变量设置为指向 JDK 安装项目。

  • Maven

    提示

    Java 和 Maven 安装过程中会向系统添加环境变量。 完成安装后,重新启动任何打开的 Visual Studio Code 终端、Powershell 或命令提示符实例。 此步骤确保这些实用工具可继续识别 Java 和 Maven 命令。

创建模块项目

以下步骤创建基于 Azure IoT Edge maven 模板包和 Azure IoT Java 设备 SDK 的 IoT Edge 项目。 使用 Visual Studio Code 和 Azure IoT 工具创建该项目。

创建新项目

创建可以使用你自己的代码进行自定义的 Java 解决方案模板。

  1. 在 Visual Studio Code 中,选择“查看” > “命令面板”,以打开 VS Code 命令面板。

  2. 在“命令面板”中,输入并运行 Azure IoT Edge:New IoT Edge solution 命令。 按命令面板中的提示创建解决方案。

    字段 Value
    选择文件夹 在适用于 VS Code 的开发计算机上选择用于创建解决方案文件的位置。
    提供解决方案名称 输入解决方案的描述性名称,或者接受默认的 EdgeSolution
    选择模块模板 选择“Java 模块”。
    提供模块名称 将模块命名为 JavaModule
    为模块提供 Docker 映像存储库 映像存储库包含容器注册表的名称和容器映像的名称。 容器映像是基于你在上一步中提供的名称预先填充的。 将 localhost:5000 替换为 Azure 容器注册表中的“登录服务器”值。 可以在 Azure 门户的容器注册表的“概述”页中检索登录服务器。

    最终的映像存储库类似于 <registry name>.azurecr.cn/javamodule。
    为 groupId 提供值 输入组 ID 值或接受默认的 com.edgemodule

    提供 Docker 映像存储库

如果你是第一次创建 Java 模块,则下载 maven 包可能需要几分钟时间。 解决方案准备就绪后,VS Code 窗口会加载 IoT Edge 解决方案工作区。 解决方案工作区包含五个顶级组件:

  • modules 文件夹包含模块的 Java 代码,以及用于将模块构建为容器映像的 Docker 文件。
  • .env 文件存储容器注册表凭据。
  • deployment.template.json 文件包含 IoT Edge 运行时用于在设备上部署模块的信息。
  • deployment.debug.template.json 文件包含模块的调试版本。
  • 你不会在本教程中编辑 .vscode 文件夹或 .gitignore 文件。

如果在创建解决方案时未指定容器注册表,但接受了默认的 localhost:5000 值,则不会有 .env 文件。

添加注册表凭据

环境文件存储容器注册表的凭据,并将其与 IoT Edge 运行时共享。 此运行时需要这些凭据才能将专用映像拉取到 IoT Edge 设备中。

IoT Edge 扩展尝试从 Azure 中拉取容器注册表凭据并将其填充到环境文件中。 检查凭据是否已包含在内。 如果没有,请立即添加:

  1. 在 VS Code 资源管理器中,打开 .env 文件。
  2. 使用从 Azure 容器注册表复制的 usernamepassword 值更新相关字段。
  3. 保存此文件。

备注

本教程使用 Azure 容器注册表的管理员登录凭据,这对于开发和测试方案非常方便。 为生产方案做好准备后,建议使用最低权限身份验证选项(如服务主体)。 有关详细信息,请参阅管理容器注册表的访问权限

选择目标体系结构

目前,Visual Studio Code 可以开发适用于 Linux AMD64 和 Linux ARM32v7 设备的 Java 模块。 需要选择面向每个解决方案的体系结构,因为每种体系结构类型的容器的生成和运行方式均不相同。 默认值为 Linux AMD64。

  1. 打开命令面板并搜索 Azure IoT Edge:Set Default Target Platform for Edge Solution,或选择窗口底部侧栏中的快捷方式图标。

  2. 在命令面板中,从选项列表中选择目标体系结构。 在本教程中,我们使用 Ubuntu 虚拟机作为 IoT Edge 设备,因此将保留默认的“amd64” 。

使用自定义代码更新模块

  1. 在 VS Code 资源管理器中,打开 modules > JavaModule > src > main > java > com > edgemodule > App.java

  2. 在该文件顶部添加以下代码,以便导入新的引用的类。

    import java.io.StringReader;
    import java.util.concurrent.atomic.AtomicLong;
    import java.util.HashMap;
    import java.util.Map;
    
    import javax.json.Json;
    import javax.json.JsonObject;
    import javax.json.JsonReader;
    
    import com.microsoft.azure.sdk.iot.device.DeviceTwin.Pair;
    import com.microsoft.azure.sdk.iot.device.DeviceTwin.Property;
    import com.microsoft.azure.sdk.iot.device.DeviceTwin.TwinPropertyCallBack;
    
  3. 将以下定义添加到 App 类中。 此变量设置温度阈值。 在测量的机器温度超过此值之前,不会向 IoT 中心报告此温度。

    private static final String TEMP_THRESHOLD = "TemperatureThreshold";
    private static AtomicLong tempThreshold = new AtomicLong(25);
    
  4. MessageCallbackMqtt 执行方法替换为以下代码。 每当模块从 IoT Edge 中心接收 MQTT 消息,就会调用此方法。 此方法筛选掉那些所报告温度低于温度阈值(通过孪生模块进行设置)的消息。

    protected static class MessageCallbackMqtt implements MessageCallback {
        private int counter = 0;
        @Override
        public IotHubMessageResult execute(Message msg, Object context) {
            this.counter += 1;
    
            String msgString = new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET);
            System.out.println(
                   String.format("Received message %d: %s",
                            this.counter, msgString));
            if (context instanceof ModuleClient) {
                try (JsonReader jsonReader = Json.createReader(new StringReader(msgString))) {
                    final JsonObject msgObject = jsonReader.readObject();
                    double temperature = msgObject.getJsonObject("machine").getJsonNumber("temperature").doubleValue();
                    long threshold = App.tempThreshold.get();
                    if (temperature >= threshold) {
                        ModuleClient client = (ModuleClient) context;
                        System.out.println(
                            String.format("Temperature above threshold %d. Sending message: %s",
                            threshold, msgString));
                        client.sendEventAsync(msg, eventCallback, msg, App.OUTPUT_NAME);
                    }
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
            return IotHubMessageResult.COMPLETE;
        }
    }
    
  5. 将下面的两个静态内部类添加到 App 类中。 当模块孪生的所需属性发生更改时,这些类将更新 tempThreshold 变量。 所有模块都有自己的孪生模块,因此可以直接从云配置在模块中运行的代码。

    protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
        @Override
        public void execute(IotHubStatusCode status, Object context) {
            System.out.println("IoT Hub responded to device twin operation with status " + status.name());
        }
    }
    
    protected static class OnProperty implements TwinPropertyCallBack {
        @Override
        public void TwinPropertyCallBack(Property property, Object context) {
            if (!property.getIsReported()) {
                if (property.getKey().equals(App.TEMP_THRESHOLD)) {
                    try {
                        long threshold = Math.round((double) property.getValue());
                        App.tempThreshold.set(threshold);
                    } catch (Exception e) {
                        System.out.println("Faile to set TemperatureThread with exception");
                        e.printStackTrace();
                    }
                }
            }
        }
    }
    
  6. 将以下行添加到 main 方法的 client.open() 后面,以便订阅模块孪生更新。

    client.startTwin(new DeviceTwinStatusCallBack(), null, new OnProperty(), null);
    Map<Property, Pair<TwinPropertyCallBack, Object>> onDesiredPropertyChange = new HashMap<Property, Pair<TwinPropertyCallBack, Object>>() {
        {
            put(new Property(App.TEMP_THRESHOLD, null), new Pair<TwinPropertyCallBack, Object>(new OnProperty(), null));
        }
    };
    client.subscribeToTwinDesiredProperties(onDesiredPropertyChange);
    client.getTwin();
    
  7. 保存 App.java 文件。

  8. 在 VS Code 资源管理器的 IoT Edge 解决方案工作区中打开 deployment.template.json 文件。

  9. JavaModule 模块孪生添加到部署清单。 在 moduleContent 节底部的 $edgeHub 模块孪生后面插入以下 JSON 内容:

      "JavaModule": {
          "properties.desired":{
              "TemperatureThreshold":25
          }
      }
    

    将模块孪生添加到部署模板

  10. 保存 deployment.template.json 文件。

生成并推送模块

在上一部分,你已经创建了一个 IoT Edge 解决方案并将代码添加到了 JavaModule,该函数会筛选出其中报告的计算机温度低于可接受限制的消息。 现在,请将解决方案生成为容器映像并将其推送到容器注册表。

  1. 打开 VS Code 集成终端,方法是选择“视图” > “终端” 。

  2. 在终端中输入以下命令,以登录到 Docker。 使用 Azure 容器注册表中的用户名、密码和登录服务器登录。 可以在 Azure 门户中从注册表的“访问密钥”部分检索这些值。

    docker login -u <ACR username> -p <ACR password> <ACR login server>
    

    可能会收到一条安全警告,推荐使用 --password-stdin。 这条最佳做法是针对生产方案建议的,这超出了本教程的范畴。 有关详细信息,请参阅 docker login 参考。

  3. 在 VS Code 资源管理器中右键单击“deployment.template.json”文件,然后选择“生成并推送 IoT Edge 解决方案”。

    “生成并推送”命令会启动三项操作。 首先,它在解决方案中创建名为 config 的新文件夹,用于保存基于部署模板和其他解决方案文件中的信息生成的完整部署清单。 其次,它会运行 docker build,以基于目标体系结构的相应 dockerfile 生成容器映像。 然后,它会运行 docker push,以将映像存储库推送到容器注册表。

    首次执行此过程可能需要几分钟时间,但下次运行命令时速度会变快。

将模块部署到设备

使用 Visual Studio Code 资源管理器和 Azure IoT Tools 扩展将模块项目部署到 IoT Edge 设备。 你已经为方案准备了部署清单,即 config 文件夹中的 deployment.amd64.json 文件。 现在需要做的就是选择一个设备来接收部署。

确保 IoT Edge 设备已启动并运行。

  1. 在 Visual Studio Code 资源管理器中的“Azure IoT 中心”部分下,展开“设备”可查看 IoT 设备的列表。

  2. 右键单击 IoT Edge 设备的名称,然后选择“为单个设备创建部署”。

  3. 选择 config 文件夹中的 deployment.amd64.json 文件,然后单击“选择 Edge 部署清单”。 不要使用 deployment.template.json 文件。

  4. 在设备下,展开“模块”可查看已部署的正在运行的模块的列表。 单击“刷新”按钮。 此时应看到新的 JavaModuleSimulatedTemperatureSensor 模块以及 $edgeAgent$edgeHub 一起运行。

    启动模块可能需要数分钟时间。 IoT Edge 运行时需要接收其新的部署清单,从容器运行时下拉模块映像,然后启动每个新模块。

查看生成的数据

将部署清单应用到 IoT Edge 设备以后,设备上的 IoT Edge 运行时就会收集新的部署信息并开始在其上执行操作。 在设备上运行的未包括在部署清单中的任何模块都会停止。 设备中缺失的任何模块都会启动。

  1. 在 Visual Studio Code 资源管理器中右键单击 IoT Edge 设备的名称,选择“开始监视内置事件终结点”。

  2. 查看抵达 IoT 中心的消息。 消息到达可能需要一段时间。 IoT Edge 设备必须接收其新部署并启动所有模块。 然后,在发送消息之前我们对 JavaModule 代码所做的更改需等到机器温度达到 25 度才会生效。 IoT 中心还会将消息类型“警报”添加到达到该温度阈值的任何消息。

编辑模块孪生

我们已使用部署清单中的 JavaModule 模块孪生将温度阈值设置为 25 度。 可以使用模块孪生来更改功能,而无需更新模块代码。

  1. 在 Visual Studio Code 中,展开 IoT Edge 设备下的详细信息以查看正在运行的模块。

  2. 右键单击 JavaModule,然后选择“编辑模块孪生”。

  3. 在所需属性中找到 TemperatureThreshold。 将其值更改为比上次报告的温度高出 5 到 10 度的新温度。

  4. 保存模块孪生文件。

  5. 右键单击模块孪生编辑窗格中的任意位置,然后选择“更新模块孪生”。

  6. 监视传入的设备到云消息。 应会看到,在达到新的温度阈值之前,消息会停止发送。

清理资源

如果打算继续学习下一篇建议的文章,可以保留已创建的资源和配置,以便重复使用。 还可以继续使用相同的 IoT Edge 设备作为测试设备。

否则,可以删除本文中创建的本地配置和 Azure 资源,以避免收费。

删除 Azure 资源

删除 Azure 资源和资源组的操作不可逆。 请确保不要意外删除错误的资源组或资源。 如果在现有的包含要保留资源的资源组中创建了 IoT 中心,请只删除 IoT 中心资源本身,而不要删除资源组。

若要删除资源,请执行以下操作:

  1. 登录到 Azure 门户,然后选择“资源组”。

  2. 选择包含 IoT Edge 测试资源的资源组的名称。

  3. 查看包含在资源组中的资源的列表。 若要删除这一切,可以选择“删除资源组”。 如果只需删除部分内容,可以单击要单独删除的每个资源。

后续步骤

在本教程中,你已创建一个 IoT Edge 模块用于筛选 IoT Edge 设备生成的原始数据。

继续学习后续教程,了解如何借助 Azure IoT Edge 部署 Azure 云服务,以便在边缘位置处理和分析数据。

自定义视觉服务