本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS IoT Jobs 库演示
<a name="freertos-jobs-demo"></a>

**重要**  <a name="deprecation-message-demo"></a>
该演示托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 [Amazon-FreeRTOS Github 存储库迁移指南](github-repo-migration.md)。

## 简介
<a name="freertos-jobs-demo-introduction"></a>

AWS IoT Jobs 库演示展示了如何通过 MQTT 连接连接到 [AWS IoT Jobs 服务](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)、从 AWS IoT 设备检索作业以及在设备上处理作业。AWS IoT Jobs 演示项目使用 [FreeRTOS Windows 端口](https://www.freertos.org/FreeRTOS-Windows-Simulator-Emulator-for-Visual-Studio-and-Eclipse-MingW.html)，因此可以在 Windows 上使用 [Visual Studio 社区](https://visualstudio.microsoft.com/vs/community/)版本进行构建和评估。无需微控制器硬件。该演示使用 TLS 与 AWS IoT MQTT 代理建立安全连接，其方式与 [coreMQTT 双向身份验证演示](mqtt-demo-ma.md)相同。

**注意**  
要设置和运行 FreeRTOS 演示，请按照[开始使用 FreeRTOS](freertos-getting-started.md)中的步骤操作。

## 源代码组织
<a name="freertos-jobs-demo-source-code-org"></a>

演示代码位于 `jobs_demo.c` 文件中，可在 [GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c) 网站或 `freertos/demos/jobs_for_aws/` 目录中找到。

## 配置 AWS IoT MQTT 代理连接
<a name="freertos-jobs-demo-configure-mqtt-broker"></a>

在本演示中，您将使用与 MQTT 代理的 AWS IoT MQTT 连接。此连接的配置方式与 [coreMQTT 双向身份验证演示](mqtt-demo-ma.md)相同。

## 功能
<a name="freertos-jobs-demo-functionality"></a>

该演示展示了用于从 AWS IoT 接收任务并在设备上处理这些任务的工作流程。该演示是交互式的，需要您使用 AWS IoT 控制台或 AWS Command Line Interface (AWS CLI) 来创建作业。有关创建作业的更多信息，请参阅 *AWS CLI 命令参考*中的 [create-job](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html)。该演示要求将作业文档的 `action` 键设置为 `print` 才能将消息输出到控制台。

请参阅此作业文档的以下格式。

```
{
    "action": "print",
    "message": "ADD_MESSAGE_HERE"
}
```

您可以使用 AWS CLI 创建作业，如以下示例命令所示。

```
aws iot create-job \
    --job-id t12 \
    --targets arn:aws:iot:region:123456789012:thing/device1 \
    --document '{"action":"print","message":"hello world!"}'
```

该演示还使用将 `action` 键设置为 `publish` 的作业文档来将消息重新发布到主题。请参阅此作业文档的以下格式。

```
{
    "action": "publish",
    "message": "ADD_MESSAGE_HERE",
    "topic": "topic/name/here"
}
```

该演示会循环执行，直到收到一个将 `action` 键设置为 `exit` 的作业文档才会退出。作业文档的格式如下所示。

```
{
    "action: "exit"
}
```

### Jobs 演示的入口点
<a name="freertos-jobs-demo-functionality-entry-point"></a>

Jobs 演示入口点函数的源代码可以在 [GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c#L773-L967) 上找到。该函数执行以下操作：

1. 使用 `mqtt_demo_helpers.c` 中的帮助程序函数建立 MQTT 连接。

1. 使用 `mqtt_demo_helpers.c` 中的帮助程序函数为 `NextJobExecutionChanged` API 订阅 MQTT 主题。主题字符串是之前使用 AWS IoT Jobs 库定义的宏汇编而成的。

1. 使用 `mqtt_demo_helpers.c` 中的帮助程序函数为 `StartNextPendingJobExecution` API 发布 MQTT 主题。主题字符串是之前使用 AWS IoT Jobs 库定义的宏汇编而成的。

1. 反复调用 `MQTT_ProcessLoop` 以接收传入的消息，这些消息将交给 `prvEventCallback` 进行处理。

1. 演示收到退出操作后，使用文件中的帮助程序函数取消订阅 MQTT 主题并断开连接。`mqtt_demo_helpers.c`

### 收到的 MQTT 消息的回调
<a name="freertos-jobs-demo-functionality-callback"></a>

[prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c#L674-L769) 函数从 AWS IoT Jobs 库调用 `Jobs_MatchTopic`，以便对传入的 MQTT 消息进行分类。如果消息类型对应于新作业，则会调用 `prvNextJobHandler()`。

[prvNextJobHandler](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c#L601-L670) 函数及其调用的函数从 JSON 格式的消息中解析作业文档，然后运行作业指定的操作。`prvSendUpdateForJob` 函数非常让人感兴趣。

### 为正在运行的作业发送更新
<a name="freertos-jobs-demo-functionality-send-update"></a>

函数 [prvSendUpdateForJob()](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c#L413-L457) 从 Jobs 库调用 `Jobs_Update()`，以便填充在紧随其后的 MQTT 发布操作中使用的主题字符串。