本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS IoT 任務程式庫示範
<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)。 FreeRTOS 

## 簡介
<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 任務示範專案使用 [ 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"
}
```

### 任務示範的進入點
<a name="freertos-jobs-demo-functionality-entry-point"></a>

您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/jobs_for_aws/jobs_demo.c#L773-L967) 上找到 Jobs 示範進入點函數的原始碼。此函數會執行下列操作：

1. 使用 中的協助程式函數建立 MQTT 連線`mqtt_demo_helpers.c`。

1. 使用 中的協助程式函數，訂閱 `NextJobExecutionChanged` API 的 MQTT 主題`mqtt_demo_helpers.c`。主題字串會稍早使用 AWS IoT Jobs 程式庫定義的巨集進行組合。

1. 使用 中的協助程式函數，發佈至 `StartNextPendingJobExecution` API 的 MQTT 主題`mqtt_demo_helpers.c`。主題字串會稍早使用 AWS IoT Jobs 程式庫定義的巨集進行組合。

1. 重複呼叫 `MQTT_ProcessLoop` 以接收傳遞給 `prvEventCallback`進行處理的傳入訊息。

1. 示範收到結束動作後，請使用 `mqtt_demo_helpers.c` 檔案中的協助程式函數，取消訂閱 MQTT 主題並中斷連線。

### 已接收 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)函數`Jobs_MatchTopic`會從 AWS IoT Jobs 程式庫呼叫 來分類傳入的 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_Update()` 從 Jobs 程式庫呼叫 ，填入接下來 MQTT 發佈操作中使用的主題字串。