本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學課程：將裝置資料儲存在 DynamoDB 表格中
本教學課程示範如何建立將訊息資料傳送至 DynamoDB 資料表的 AWS IoT 規則。
在此教學課程中，您會建立一個規則，將訊息資料從虛構天氣感應器裝置傳送至 DynamoDB 表格。該規則會格式化來自多個天氣感應器的資料，由此可將其新增至單個資料庫表格中。
**您會在本教學課程中學到什麼**
+ 如何建立 DynamoDB 表格
+ 如何從 AWS IoT 規則傳送訊息資料至 DynamoDB 資料表
+ 如何在 AWS IoT 規則中使用替代範本
+ 如何在規則查詢陳述式中使用簡單的 SQL 查詢和函數
+ 如何使用 MQTT 用戶端測試 AWS IoT 規則
此教學課程約需 30 分鐘方能完成。
**Topics**
+ [步驟 1：為本教學課程建立 DynamoDB 表格](#iot-ddb-rule-ddb-table)
+ [步驟 2：建立 AWS IoT 規則以將資料傳送至 DynamoDB 資料表](#iot-ddb-rule-topic-rule)
+ [步驟 3：測試 AWS IoT 規則和 DynamoDB 資料表](#iot-ddb-rule-test)
+ [步驟 4：檢閱結果及後續步驟](#iot-ddb-rule-review)
**開始本教學課程之前，請確定您有：**
+
**[設定 AWS 帳戶](setting-up.md)**
您需要 AWS 帳戶 和 AWS IoT 主控台才能完成本教學課程。
+
**檢閱 [使用 MQTT 用戶端檢視 AWS IoT MQTT 訊息](view-mqtt-messages.md)**
請確定您可使用 MQTT 用戶端來訂閱並發佈至主題。您會使用 MQTT 用戶端，在此程序中測試您的新規則。
+
**檢閱了 [Amazon DynamoDB](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/Introduction.html) 概觀**
若您未曾使用過 DynamoDB，請查閱 [DynamoDB 入門](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)，以熟悉 DynamoDB 的基本概念和作業。
## 步驟 1：為本教學課程建立 DynamoDB 表格
於本教學課程中，您會建立一個具下列屬性的 DynamoDB 表格，以記錄來自虛構氣候感應器裝置的資料：
+ `sample_time` 為主索引鍵，並說明記錄範例的時間。
+ `device_id` 為排序索引鍵，並說明提供範例的裝置
+ `device_data` 為從裝置接收並由規則查詢陳述式格式化的資料
**如要建立本教學課程的 DynamoDB 表格**
1. 開啟 [DynamoDB 主控台](https://console.aws.amazon.com//dynamodb/home)，然後選擇 **Create table** (建立表格)。
1. 在 **Create table** (建立資料表) 中：
1. 於 **Table name** (表格名稱) 中，輸入表格名稱：**wx\$1data**。
1. 在 **Primary key** (主索引鍵) 中，輸入 **sample\$1time**，然後在欄位旁的選項清單中，選擇 **Number**。
1. 在 **Sort key** (排序索引鍵) 中，輸入 **device\$1id**，然後在欄位旁的選項清單中，選擇 **Number**。
1. 請在頁面底部，選擇 **Create** (建立)。
您稍後將在設定 DynamoDB 規則動作時定義 `device_data`。
## 步驟 2：建立 AWS IoT 規則以將資料傳送至 DynamoDB 資料表
於此步驟中，您會使用規則查詢陳述式，格式化虛構天氣感應器裝置的資料，以寫入資料庫表格。
從天氣感應器裝置接收的訊息承載範例如下所示：
```
{
"temperature": 28,
"humidity": 80,
"barometer": 1013,
"wind": {
"velocity": 22,
"bearing": 255
}
}
```
對於資料庫項目，您會使用規則查詢陳述式將訊息承載的結構平面化，如下所示：
```
{
"temperature": 28,
"humidity": 80,
"barometer": 1013,
"wind_velocity": 22,
"wind_bearing": 255
}
```
於此規則中，您還會使用一些 [替代範本](iot-substitution-templates.md)。替代範本是可讓您從函數和訊息資料插入動態值的運算式。
**建立 AWS IoT 規則以將資料傳送至 DynamoDB 資料表**
1. 開啟[AWS IoT 主控台的 Rules (規則) 中樞](https://console.aws.amazon.com//iot/home#/rulehub)。或者，您可以在 AWS 管理主控台 中開啟 AWS IoT 首頁，並導覽至**訊息路由＞規則**。
1. 如要在 **Rules** (規則) 中開始建立新規則，請選擇 **Create rule** (建立規則)。
1. 在 **Rule properties** (規則屬性) 中：
1. 在 **Rule name** (規則名稱) 中，輸入 **wx\$1data\$1ddb**。
請記住，規則名稱在您的 AWS 帳戶 和 區域中必須是唯一的，而且不能有任何空格。我們在此名稱中使用底線字元來分隔規則名稱中的兩個單字。
1. 在 **Rule description** (規則說明) 中，說明規則。
有意義的說明可讓您更容易記住此規則的作用及您建立規則的原因。說明可依所需而定，因此請盡可能詳細說明。
1. 選擇 **Next** (下一步) 繼續。
1. 在 **SQL statement** (SQL 陳述式) 中：
1. 在 **SQL version** (SQL 版本) 中，選取 **2016-03-23**。
1. 在 **SQL statement** (SQL 陳述式) 編輯方塊中，輸入陳述式：
```
SELECT temperature, humidity, barometer,
wind.velocity as wind_velocity,
wind.bearing as wind_bearing,
FROM 'device/+/data'
```
本陳述式：
+ 聆聽具與 `device/+/data` 主題篩選條件相符之主題的 MQTT 訊息。
+ 將 `wind` 屬性的元素格式化為個別屬性。
+ 傳遞 `temperature`、`humidity` 和 `barometer` 屬性不變。
1. 選擇 **Next** (下一步) 繼續。
1. 在 **Rule actions** (規則動作) 中：
1. 若要開啟此規則的規則動作清單，請於 **Action 1** (動作 1) 中，選擇 **DynamoDB**。
**注意**
請務必選擇 DynamoDB 而非 DynamoDBv2 作為規則動作。
1. 於 **Table name** (表格名稱) 中，選擇您在先前步驟中建立的 DynamoDB 表格名稱：**wx\$1data**。
**Partition key type** (分割區索引鍵類型) 和 **Sort key type** (排序索引鍵類型) 欄位，都會填入 DynamoDB 表格中的值。
1. 在 **Partition key (分區索引鍵)**，輸入 **sample\$1time**。
1. 在 **Partition key value (分割區索引鍵值)** 中，輸入 **\$1\$1timestamp()\$1**。
這是您將用於此規則中 [替代範本](iot-substitution-templates.md) 的首項。而非使用訊息承載中的值，其會使用 timestamp 函數傳回的值。如需進一步了解，請參閱*AWS IoT Core 開發人員指南中*的[時間戳記](iot-sql-functions.md#iot-function-timestamp)。
1. 在 **Sort key** (排序索引鍵) 中，輸入 **device\$1id**。
1. 在 **Sort key value (排序索引鍵值)** 中，輸入 **\$1\$1cast(topic(2) AS DECIMAL)\$1**。
這是您將用於此規則中 [替代範本](iot-substitution-templates.md) 第二項。其會在主題名稱中插入第二個元素值，即裝置的 ID，然後將其轉換為 DECIMAL 值，以與索引鍵的數值格式相符。若要進一步了解主題，請參閱*AWS IoT Core 開發人員指南*中的[主題](iot-sql-functions.md#iot-function-topic)。或者，若要了解將值轉換為數值的詳細資訊，請參閱*AWS IoT Core 開發人員指南*中的[將值轉換為數值](iot-sql-functions.md#iot-sql-function-cast)。
1. 在 **Write message data to this column (寫入訊息資料至此欄)** 中輸入 **device\$1data**。
這會建立 DynamoDB 表格中的 `device_data` 欄。
1. 將 **Operation (操作)** 保持空白。
1. 在 **IAM Role** (IAM 角色) 中，選擇 **Create a new Role** (建立新角色)。
1. 在 **Create role** (建立角色) 對話方塊中，請為 **Role name** (角色名稱) 輸入 **wx\$1ddb\$1role**。這個新角色會自動包含以 "aws-iot-rule" 為字首的政策，其允許 **wx\$1data\$1ddb** 規則將資料傳送到您建立的 **wx\$1data** DynamoDB 資料表。
1. 在 **IAM role** (IAM 角色) 中，選擇 **wx\$1ddb\$1role**。
1. 請選擇頁面最下方的 **Next** (下一頁)。
1. 請在 **Review and create** (檢閱和建立) 頁面底部，選擇 **Create** (建立) 來建立規則。
## 步驟 3：測試 AWS IoT 規則和 DynamoDB 資料表
若要測試新規則，您會使用 MQTT 用戶端來發佈和訂閱用於此測試的 MQTT 訊息。
在新視窗的 [AWS IoT 主控台中開啟 MQTT 用戶端](https://console.aws.amazon.com//iot/home#/test)。這可讓您編輯規則，而不會遺失 MQTT 用戶端的組態。如果您讓它轉到主控台中的另一個頁面，MQTT 用戶端不會保留任何訂閱或訊息記錄。您也需要在主控台中開啟單獨的[AWS IoT 主控台視窗至 DynamoDB Tables 中樞](https://console.aws.amazon.com//dynamodb/home#tables:)，以檢視規則傳送的新項目。
**如要使用 MQTT 用戶端來測試您的規則。**
1. 於 [AWS IoT 主控台的 MQTT 用戶端](https://console.aws.amazon.com//iot/home#/test) 中，訂閱輸入主題 `device/+/data`。
1. 於 MQTT 用戶端中，選擇 **Subscribe to a topic** (訂閱主題)。
1. 若為 **Topic filter** (主題篩選條件)，請輸入輸入主題篩選條件的主題 **device/\$1/data**。
1. 選擇 **Subscribe (訂閱)**。
1. 現在，使用特定裝置 ID **device/22/data** 將訊息發佈至輸入主題。您無法發佈至包含萬用字元的 MQTT 主題。
1. 於 MQTT 用戶端中，請選擇 **Publish to a topic** (發佈至主題)。
1. 若為 **Topic name** (主題名稱)，請輸入輸入主題名稱 **device/22/data**。
1. 若為 **Message payload** (訊息承載)，請輸入下列範例資料。
```
{
"temperature": 28,
"humidity": 80,
"barometer": 1013,
"wind": {
"velocity": 22,
"bearing": 255
}
}
```
1. 如要發佈 MQTT 訊息，請選擇 **Publish** (發佈)。
1. 現在，於 MQTT 用戶端中，選擇 **Subscribe to a topic** (訂閱主題)。於 **Subscribe** (訂閱) 欄中，選擇 **device/\$1/data** 訂閱。確認上一步的範例資料會顯示於此處。
1. 查看您規則所建立 DynamoDB 表格中的列。
1. 在[AWS IoT 主控台的 DynamoDB Tables 中樞](https://console.aws.amazon.com//dynamodb/home#tables:)中，選擇 **wx\$1data**，然後選擇**項目**索引標籤。
若您已在 **Items** (項目) 索引標籤上，您可能需要選擇表格標題右上角的重新整理圖示來重新整理該顯示。
1. 請注意，表格中的 **sample\$1time** 值為連結並開啟一個。若您剛傳送了第一則訊息，則其將是清單中唯一的訊息。
此連結會顯示表格該列中的所有資料。
1. 展開 **device\$1data** 項目，查看規則查詢陳述式所產生的資料。
1. 探索此顯示中可用資料的不同表示法。您亦可於此顯示中編輯資料。
1. 完成查閱此資料列之後，如要儲存所做的任何變更，請選擇 **Save** (儲存)，或者，如要結束而不儲存任何變更，請選擇 **Cancel** (取消)。
若您並未看到正確的行為，請查看疑難排解提示。
### 對您的 DynamoDB 規則進行疑難排解
若您並未看到預期的結果，請查看以下事項。
+
**您收到錯誤的橫幅**
若在您發佈輸入訊息時出現錯誤，請先更正該錯誤。下列步驟可協助您修正該錯誤。
+
**您並未在 MQTT 用戶端中看到輸入訊息**
每次您將輸入訊息發佈至 `device/22/data` 主題時，若您依程序中所述訂閱了 `device/+/data` 主題篩選條件，則該訊息應會顯示於 MQTT 用戶端中。
**要檢查的事項**
+
**檢查您訂閱的主題篩選條件**
若您依程序中所述訂閱了輸入訊息主題，則每次發佈輸入訊息時都應該會看到其複本。
若您並未訊息，請檢查您訂閱的主題名稱，並將其與所發佈的主題進行比較。主題名稱區分大小寫，且您訂閱的主題必須與所發佈訊息承載的主題相同。
+
**檢查訊息發佈功能**
在 MQTT 用戶端中的 **Subscriptions** (訂閱) 下，選擇 **device/\$1/data**，檢查發佈訊息的主題，然後選擇 **Publish to topic** (發佈至主題)。您應該會在訊息清單中出現主題下方的編輯方塊中看到訊息承載。
+
**您在 DynamoDB 表格中看不到您的資料**
首先要做的是選擇表格標題右上角的重新整理圖示，以重新整理顯示。若未顯示您正在尋找的資料，請檢查下列內容。
**要檢查的事項**
+
**檢查 MQTT 用戶端 AWS 區域 的 和您建立的規則**
您正在執行 MQTT 用戶端的主控台必須與您建立的規則處於相同的 AWS 區域。
+
**檢查規則查詢陳述式中的輸入訊息主題**
若要讓規則運作，其必須收到一則訊息，其主題名稱與規則查詢陳述式之 FROM 子句中的主題篩選條件相符。
檢查規則查詢陳述式中主題篩選條件的拼字與 MQTT 用戶端中主題的拼字。主題名稱區分大小寫，且郵件的主題必須與規則查詢陳述式中的主題篩選條件相符。
+
**檢查輸入訊息承載的內容**
若要讓規則運作，其必須在 SELECT 陳述式中宣告的訊息承載中尋找資料欄位。
檢查規則查詢陳述式中 `temperature` 欄位的拼字與 MQTT 用戶端中訊息承載的拼字。欄位名稱區分大小寫，規則查詢陳述式中的 `temperature` 欄位必須與訊息承載中的 `temperature` 欄位相符。
請確定訊息承載中的 JSON 文件格式正確。若 JSON 有任何錯誤，例如缺少逗號，則規則將無法進行讀取。
+
**檢查用於規則動作中的索引鍵和欄位名稱**
用於主題規則中的欄位名稱必須與已發佈訊息之 JSON 訊息承載中找到的欄位名稱相符。
開啟您建立於主控台中的規則，並檢查規則動作組態中的欄位名稱與用於 MQTT 用戶端中的欄位名稱。
+
**檢查規則所使用的角色**
規則動作必須具有接收原始主題及發佈新主題的權限。
授權規則以接收訊息資料及更新 DynamoDB 表格的政策是所使用主題特有的。若您變更規則使用的主題或 DynamoDB 表格名稱，則必須更新規則動作的角色，以更新其相符的政策。
若您懷疑這會是問題，請編輯規則動作並建立新角色。規則動作建立的新角色會收到執行這些動作所需的授權。
## 步驟 4：檢閱結果及後續步驟
在您使用此規則將數則訊息傳送至 DynamoDB 表格後，請試著對其進行試驗，以查看變更教學課程中的某些層面如何影響寫入表格的資料。此處有幾種簡單的入門方式。
+ 變更輸入訊息主題中的 *device\$1id*，並觀察對資料的影響。您可使用此來模擬從多個天氣感應器接收資料。
+ 變更規則查詢陳述式中所選取的欄位，並觀察對資料的影響。您可以此來篩選儲存於表格中的資料。
+ 新增重新發佈規則動作，為新增至表格中的每一列傳送 MQTT 訊息。您可以此來進行除錯。
完成本教學課程後，請查看 [教學課程：使用 AWS Lambda 函數格式化通知](iot-lambda-rule.md)。