教學課程：使用 IoT 中樞訊息路由，將裝置資料傳送至 Azure 儲存體

使用 Azure IoT 中樞內的訊息路由，從 IoT 裝置將遙測資料傳送至 Azure 服務，例如 Blob 儲存體、服務匯流排佇列、服務匯流排主題，以及事件中樞。 每個 IoT 中樞都有與事件中樞相容的預設內建端點。 您也可以藉由定義路由查詢，建立自訂端點，並將訊息路由傳送至其他 Azure 服務。 抵達 IoT 中樞的每個訊息都會路由傳送至其所符合之路由查詢的所有端點。 如果訊息不符合任何定義的路由查詢，就會將其路由傳送至預設端點。

在本教學課程中，您會執行下列工作：

• 建立 IoT 中樞，並將裝置訊息傳送給它。
• 建立儲存體帳戶。
• 建立儲存體帳戶的自訂端點，並從 IoT 中樞將訊息路由傳送至該端點。
• 檢視儲存體帳戶 Blob 中的裝置訊息。

必要條件

• Azure 訂用帳戶。 如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

• Azure 訂用帳戶中的 IoT 中樞。 如果您還沒有中樞，可遵循建立 IoT 中樞中的步驟。

• 本教學課程使用 適用於 C# 的 Azure IoT SDK 中的範例程式碼。

  • 將 SDK 存放庫下載並複製到您的開發電腦。
  • 您的開發電腦必須有 .NET Core 3.0.0 或以上版本。 視需要執行 dotnet --version 並下載 .NET 以檢查版本。

• 請確定您的防火牆已開啟連接埠 8883。 本教學課程中的範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。 某些公司和教育網路環境可能會封鎖此連接埠。 如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

• 選擇性的安裝 Azure IoT 總管。 此工具可協助您觀察訊息抵達 IoT 中樞時。 本文使用 Azure IoT Explorer。

Azure 入口網站

Azure 入口網站沒有其他必要條件。

Azure CLI

• 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

  

• 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。

  • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。

  • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。

  • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

註冊裝置並將訊息傳送至 IoT 中樞

在 IoT 中樞註冊新裝置。

Azure 入口網站

1. 登入 Azure 入口網站，然後瀏覽至 IoT 中樞。

2. 從功能表的 [裝置管理] 區段中選取 [裝置]。

3. 選取 [新增裝置]。

   

4. 提供裝置識別碼，然後選取 [儲存]。

5. 新裝置現在應該位於裝置清單中。 如果沒有，請重新整理頁面。 選取該裝置識別碼以開啟裝置詳細資料頁面。

6. 複製其中一個裝置金鑰並加以儲存。 您將使用此值來設定產生模擬裝置遙測訊息的範例程式碼。

   

Azure CLI

提示

本教學課程中使用的許多 CLI 命令都會使用相同的參數。 為了方便起見，我們定義了可視需要呼叫的區域變數。 請務必在相同的會話中執行所有命令，否則您必須重新定義變數。

1. 定義 IoT 中樞和裝置的變數。

   IOTHUB_NAME：將此預留位置取代為您的 IoT 中樞名稱。

   DEVICE_NAME:將此預留位置取代為您要在本教學課程中用於裝置的任何名稱。

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. 在 CLI 殼層中，執行 az iot hub device-identity create 命令。 此命令會建立裝置身分識別。

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. 從裝置身分識別輸出中，複製不含周圍引號 的 primaryKey 值並加以儲存。 您將使用此值來設定產生模擬裝置遙測訊息的範例程式碼。

既然您有裝置識別碼和金鑰，請使用範例程式碼開始將裝置遙測訊息傳送至IoT 中樞。

提示

如果您遵循本教學課程的 Azure CLI 步驟，請在個別會話中執行範例程式碼。 如此一來，您可以允許範例程式碼在遵循其餘 CLI 步驟時繼續執行。

1. 如果您不是必要條件的一部分，請立即從 GitHub 下載或複製適用於 C# 存放庫的 Azure IoT SDK。

2. 從您下載或複製 SDK 的資料夾，瀏覽至 azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample 資料夾。

3. 安裝 Azure IoT C# SDK 和檔案中指定的 HubRoutingSample.csproj 必要相依性：

   dotnet restore
   

4. 在您選擇的編輯器中開啟 Parameters.cs 檔案。 此檔案會顯示範例所支援的參數。 執行範例時，本文只會使用 PrimaryConnectionString 參數。 檢閱此檔案中的程式碼。 不需要任何變更。

5. 使用下列命令建置和執行範例程式碼：

   以 IoT 中樞中裝置提供的主要連接字串取代 <myDevicePrimaryConnectionString>。

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. 您應該會在訊息傳送至 IoT 中樞時，開始看到列印到輸出的訊息。 讓此程式在教學課程期間保持執行狀態。

設定 IoT 檔案總管以檢視訊息

設定 IoT Explorer 以連線到 IoT 中樞，並在訊息抵達內建端點時讀取訊息。

首先，擷取 IoT 中樞的連接字串。

Azure 入口網站

1. 在 Azure 入口網站中，瀏覽至您的 IoT 中樞。

2. 從功能表的安全性設定區段中選取共用存取原則。

3. 選取 iothubowner 原則。

   

4. 複製主要連結字串。

   

Azure CLI

1. 執行 az iot hub connection-string show 命令：

   az iot hub connection-string show --hub-name $hubName
   

2. 複製不含周圍引號的連接字串。

現在，使用該連接字串來設定 IoT 中樞的 IoT 總管。

1. 在開發電腦上安裝 IoT 總管。

2. 請選取新增連線。

   

3. 將中樞的連接字串貼上至文字方塊中。

4. 選取 [儲存]。

5. 連線到 IoT 中樞後，您應該會看到裝置清單。 選取您為此教學課程建立的裝置識別碼。

6. 選取 [遙測]。

7. 當您的裝置仍在執行時，請選取 [啟動]。 如果您的裝置不在執行中，則不會看到遙測資料。

   

8. 您應該會看到從裝置抵達的訊息，其中最近的訊息會顯示於頂端。

   

   觀察傳入訊息的特定時間，以確認您看到三種不同類型的訊息：一般、儲存和重要。 看到此遙測之後，即可停止裝置。

這些訊息全都會抵達 IoT 中樞的預設內建端點。 在下一節中，我們將建立自訂端點，並根據訊息屬性將其中部分訊息路由傳送至儲存體。 這些訊息將會停止出現在 IoT 總管中，因為訊息只會在訊息不符合 IoT 中樞的任何其他路由時，才會移至內建端點。

設定訊息路由

您將根據由模擬裝置附加至訊息的屬性，將訊息路由至不同的資源。 沒有自訂路由的訊息會傳送至預設的端點 (訊息/事件)。

本教學課程的範例應用程式會將 level 屬性指派給傳送至 IoT 中樞的每個訊息。 每個訊息都會隨機指派一個層級的一般、儲存或重要。

第一個步驟是設定要作為資料路由傳送目的地的端點。 第二個步驟是設定會使用該端點的訊息路由。 設定好路由之後，您便可以在入口網站中檢視端點和訊息路由。

建立儲存體帳戶

建立 Azure 儲存體帳戶和該帳戶內的容器，會保存路由至該帳戶的裝置訊息。

Azure 入口網站

1. 在 Azure 入口網站中，搜尋儲存體帳戶。

2. 選取 建立。

3. 為您的儲存體帳戶提供下列值：

   參數	值
   訂用帳戶	選取包含 IoT 中樞的相同訂閱。
   資源群組	選取包含 IoT 中樞的相同資源群組。
   儲存體帳戶名稱	為您的儲存體帳戶提供全域唯一名稱。
   效能	接受預設標準值。

   

4. 您可以選取 [檢閱 + 建立]，接受所有其他預設值。

5. 驗證完成時，選取 [建立]。

6. 部署完成後，請選取 [前往資源]。

7. 在儲存體帳戶功能表中，從 [資料儲存體] 中選取 [容器]。

8. 選取 [+ 容器] 以建立新的容器。

   

9. 為您的儲存體提供名稱，然後選取 [建立]。

Azure CLI

1. 定義儲存體帳戶和容器的變數。

   GROUP_NAME：將此預留位置取代為包含 IoT 中樞的資源群組名稱。

   STORAGE_NAME：將此預留位置取代為您的儲存體帳戶名稱。 儲存體帳戶名稱必須全部小寫，且是全域唯一。

   CONTAINER_NAME：將此預留位置取代為容器名稱。

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. 使用 az storage account create 命令建立標準一般用途 v2 的儲存體帳戶。

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. 使用 az storage container create 將容器新增至儲存體帳戶。

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

路由傳送至儲存體帳戶

現在來設定儲存體帳戶的路由。 在本節中，您會定義指向您所建立儲存體帳戶的新端點。 然後，建立路由以篩選 level 屬性設定為 storage 的訊息，並將這些路由傳送至儲存體端點。

注意

資料可採用 Apache Avro (英文) 格式 (預設值) 或 JSON 寫入至 Blob 儲存體。

您只能在設定 Blob 儲存體端點時設定編碼格式。 已完成設定的端點就無法變更此格式。 在使用 JSON 編碼時，您必須在訊息系統屬性中將 contentType 設定為 JSON，並將 contentEncoding 設定為 UTF-8。

如需如何使用 Blob 儲存體端點的詳細資訊，請參閱路由傳送至儲存體的指引。

Azure 入口網站

1. 在 Azure 入口網站中，移至您的 IoT 中樞。

2. 在資源功能表的 [中樞設定] 底下，選取 [訊息路由]，然後選取 [新增]。

   

3. 在 [端點] 索引標籤上，提供下列資訊來建立儲存體端點：

   參數	值
   端點類型	選取儲存體。
   端點名稱	提供此端點的唯一名稱。
   Azure 儲存體容器	選取 [挑選容器]。 依照提示選取儲存體帳戶與您在上一節中建立的容器。
   編碼方式	選取 [JSON]。 如果此欄位呈現灰色，則您的儲存體帳戶區域不支援 JSON。 在此情況下，請繼續進行預設 AVRO。

   

4. 接受其餘參數的預設值並選取 [建立 + 下一步]。

5. 在 [路由] 索引標籤上，提供下列資訊，以建立指向您建立之儲存體端點的路由：

   參數	值
   名稱	為路由建立名稱。
   資料來源	確認已從下拉式清單中選取 [裝置遙測訊息]。
   啟用路由	確認已選取此欄位。
   路由查詢	輸入 level="storage" 作為查詢字串。

   

6. 選取 [建立 + 略過擴充]。

Azure CLI

1. 設定端點和路由命令所需的變數。

   ENDPOINT_NAME：提供代表儲存體容器的端點名稱。

   ROUTE_NAME：為篩選儲存體端點訊息的路由提供名稱

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. 使用 az iot hub message-endpoint create 命令來建立自訂端點，指向您在上一節中建立的儲存體容器。

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. 使用 az iot hub message-route create 命令來建立路由，將 level=storage 的任何訊息傳遞至儲存體容器端點。

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

檢視路由訊息

在 IoT 中樞中建立路由並啟用後，它會立即開始路由訊息，以符合其查詢準則至儲存體端點。

使用 IoT 總管監視內建端點

返回開發電腦上的 IoT 總管工作階段。 回想一下，IoT 總管會監視 IoT 中樞的內建端點。 這表示您現在應該只會看到我們建立的自訂路由「未」路由的訊息。

執行程式碼，再次啟動範例。 觀察傳入的訊息一段時間，您應該只會看到 level 設定為 normal 或 critical 的訊息。

檢視儲存體容器中的訊息

確認訊息已抵達儲存體容器。

1. 在 Azure 入口網站中，瀏覽至您的儲存體帳戶。

2. 從功能表的 [資料儲存體] 區段選取 [容器]。

3. 選取您為此教學課程建立的容器。

4. 應該會有具有 IoT 中樞名稱的資料夾。 向下鑽研檔案結構，直到您取得 .json 檔案為止。

   

5. 選取 JSON 檔案，然後選取 [下載] 以下載 JSON 檔案。 確認檔案包含裝置中已將 level 屬性設定為 storage 的訊息。

6. 停止執行範例。

清除資源

如果您想要移除本教學課程使用的的所有 Azure 資源，請刪除資源群組。 此動作會同時刪除群組內含的所有資源。 如果您不想要刪除整個資源群組，請使用 Azure 入口網站尋找和刪除個別資源。

如果您打算繼續進行下一個教學課程，請保留您在這裡建立的資源。

Azure 入口網站

1. 在 Azure 入口網站中，瀏覽至包含本教學課程 IoT 中樞和儲存體帳戶的資源群組。
2. 檢閱資源群組中的所有資源，以判斷您要清除哪些資源。
   • 若要刪除所有資源，您可以選取 [刪除資源群組]。
   • 如果您只想要刪除特定資源，請使用每個資源名稱旁邊的核取方塊來選取您要刪除的資源。 接著選取刪除。

Azure CLI

1. 使用 az resource list 命令檢視您資源群組中的所有資源。

   az resource list --resource-group $resourceGroup --output table
   

2. 檢閱資源群組中的所有資源，以判斷您要清除哪些資源。

   • 若要刪除所有資源，請使用 az group delete 命令。

     az group delete --name $resourceGroup
     

   • 如果只想要刪除特定資源，請使用 az resource delete 命令。 例如：

     az resource delete --resource-group $resourceGroup --name $storageName
     

下一步

在本教學課程中，您已了解如何建立 Azure 資源的自訂端點，然後建立路由將裝置訊息傳送至該端點。 繼續進行下一個教學課程，了解如何使用額外的資料擴充訊息，以簡化下游流程

使用 Azure IoT 中樞訊息擴充