本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT Device Defender 示範
**重要**
此示範託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS
## 簡介
此示範說明如何使用 AWS IoT Device Defender 程式庫連線至 [AWS IoT Device Defender](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender.html)。示範使用 coreMQTT 程式庫，透過 TLS 建立 MQTT 連線 （相互身分驗證） 至 AWS IoT MQTT 代理程式和 coreJSON 程式庫，以驗證和剖析從 AWS IoT Device Defender 服務收到的回應。示範示範如何使用從裝置收集的指標來建構 JSON 格式的報告，以及如何將建構的報告提交給 AWS IoT Device Defender 服務。示範也會示範如何向 coreMQTT 程式庫註冊回呼函數，以處理來自 AWS IoT Device Defender 服務的回應，以確認傳送的報告是否被接受或拒絕。
**注意**
若要設定和執行 FreeRTOS 示範，請遵循中的步驟[FreeRTOS 入門](freertos-getting-started.md)。
## 功能
此示範會建立單一應用程式任務，示範如何收集指標、以 JSON 格式建構裝置防禦者報告，並透過安全 MQTT 連線至 AWS IoT MQTT 代理程式將其提交至 AWS IoT Device Defender 服務。示範包含標準聯網指標和自訂指標。對於自訂指標，示範包含：
+ 名為「`task_numbers`」的指標，是 FreeRTOS 任務 IDs的清單。此指標的類型是「數字清單」。
+ 名為 "`stack_high_water_mark`" 的指標，是示範應用程式任務的堆疊高浮水印。此指標的類型為「數字」。
我們收集聯網指標的方式取決於使用的 TCP/IP 堆疊。對於 FreeRTOS\$1TCP 和支援的 lwIP 組態，我們提供指標收集實作，從裝置收集真實指標並在 AWS IoT Device Defender 報告中提交它們。您可以在 GitHub 上找到 [ FreeRTOS\$1TCP](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/metrics_collector/freertos_plus_tcp/metrics_collector.c) 和 [ lwIP](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/metrics_collector/lwip/metrics_collector.c) 的實作。
對於使用任何其他 TCP/IP 堆疊的電路板，我們提供指標收集函數的短信定義，其會為所有聯網指標傳回零。在 中`freertos/demos/device_defender_for_aws/metrics_collector/stub/metrics_collector.c`為您的網路堆疊實作 函數，以傳送實際指標。此檔案也可在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/metrics_collector/stub/metrics_collector.c) 網站上取得。
對於 ESP32，預設的 lwIP 組態不使用核心鎖定，因此示範將使用截斷的指標。如果您想要使用參考 lwIP 指標集合實作，請在 中定義下列巨集`lwiopts.h`：
```
#define LINK_SPEED_OF_YOUR_NETIF_IN_BPS 0
#define LWIP_TCPIP_CORE_LOCKING 1
#define LWIP_STATS 1
#define MIB2_STATS 1
```
以下是您執行示範時的範例輸出。
![\[主控台日誌輸出，顯示 DemoThing 應用程式的 MQTT 連線、發佈和記憶體用量事件。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/Defender_p4_supported.png)
如果您的電路板未使用 FreeRTOS\$1TCP 或支援的 lwIP 組態，輸出會如下所示。
![\[日誌訊息顯示示範應用程式的 MQTT 連線建立、主題訂閱嘗試、發佈承載和封包處理。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/Defender_p4_unsupported.png)
示範的原始程式碼位於您在 `freertos/demos/device_defender_for_aws/`目錄或 [GitHub](https://github.com/aws/amazon-freertos/tree/main/demos/device_defender_for_aws) 網站上的下載中。
### 訂閱 AWS IoT Device Defender 主題
[ subscribeToDefenderTopics](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/defender_demo.c#L514-L530) 函數會訂閱 MQTT 主題，接收對已發佈 Device Defender 報告的回應。它會使用巨集`DEFENDER_API_JSON_ACCEPTED`來建構主題字串，以接收已接受之裝置防禦者報告的回應。它使用 巨集`DEFENDER_API_JSON_REJECTED`來建構主題字串，以接收被拒絕的裝置防禦者報告的回應。
### 收集裝置指標
[ collectDeviceMetrics](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/defender_demo.c#L376-L511) 函數會使用 中定義的函數收集聯網指標`metrics_collector.h`。收集的指標包括傳送和接收的位元組和封包數量、開啟的 TCP 連接埠、開啟的 UDP 連接埠，以及已建立的 TCP 連線。
### 產生 AWS IoT Device Defender 報告
[ generateDeviceMetricsReport](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/defender_demo.c#L552-L581) 函數會使用 中定義的函數產生裝置防禦者報告`report_builder.h`。該函數採用聯網指標和緩衝區，以 預期的格式建立 JSON 文件， AWS IoT Device Defender 並將其寫入提供的緩衝區。開發人員*AWS IoT 指南*中的[裝置端指標](https://docs.aws.amazon.com/iot/latest/developerguide/detect-device-side-metrics.html)中會 AWS IoT Device Defender 指定 預期的 JSON 文件格式。
### 發佈 AWS IoT Device Defender 報告
AWS IoT Device Defender 報告會發佈在用於發佈 JSON AWS IoT Device Defender 報告的 MQTT 主題上。報告使用巨集 建構`DEFENDER_API_JSON_PUBLISH`，如 GitHub 網站上的此[程式碼片段](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/defender_demo.c#L691-L695)所示。
### 處理回應的回呼
[ publishCallback ](https://github.com/aws/amazon-freertos/blob/main/demos/device_defender_for_aws/defender_demo.c#L302-L373)函數會處理傳入的 MQTT 發佈訊息。它使用來自程式 AWS IoT Device Defender 庫的 `Defender_MatchTopic` API 來檢查傳入的 MQTT 訊息是否來自 AWS IoT Device Defender 服務。如果訊息來自 AWS IoT Device Defender 服務，它會剖析收到的 JSON 回應，並在回應中擷取報告 ID。然後，報告 ID 會經過驗證，與報告中傳送的報告 ID 相同。