教學課程：使用 Azure IoT 中樞 訊息擴充

訊息擴充是 Azure IoT 中樞 在訊息傳送至指定端點之前，以其他資訊戳記訊息的能力。 使用訊息擴充的其中一個原因是要包含可用於簡化下游處理的資料。 例如，使用裝置對應項標籤擴充裝置訊息可減少客戶負載，以針對這項資訊進行裝置對應項 API 呼叫。 如需詳細資訊，請參閱 訊息擴充概觀。

在本教學課程的第一個部分中，您已瞭解如何建立自定義端點，並將訊息路由傳送至其他 Azure 服務。 在本教學課程中，您將瞭解如何建立和設定測試 IoT 中樞訊息擴充所需的額外資源。 資源包含現有記憶體帳戶的第二個記憶體容器（在本教學課程的第一個部分中建立），以保存擴充的訊息和訊息路由以傳送到該處。 訊息路由和訊息擴充的設定完成之後，您可以使用應用程式將訊息傳送至IoT中樞。 接著，中樞會將它們路由傳送至兩個記憶體容器。 只會擴充傳送至擴充記憶體容器端點的訊息。

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

• 在您的記憶體帳戶中建立第二個容器。
• 建立另一個自定義端點，並從IoT中樞將訊息路由傳送至該端點。
• 設定路由傳送至新端點的訊息擴充。
• 執行應用程式，模擬將訊息傳送至中樞的IoT裝置。
• 檢視結果，並確認訊息擴充已套用至目標訊息。

必要條件

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

• 您必須已完成教學課程：使用 IoT 中樞 訊息路由將裝置數據傳送至 Azure 儲存體，並維護您為其建立的資源。

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

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。

在記憶體帳戶中建立第二個容器

在本 教學課程的第一個部分中 ，您已建立路由訊息的記憶體帳戶和容器。 現在您應該為擴充的訊息建立第二個容器。

Azure 入口網站

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

2. 選取您稍早建立的帳戶。

3. 在記憶體帳戶功能表中，從 [資料記憶體] 區段選取 [容器]。

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

   

5. 將容器 enriched命名為 ，然後選取 [ 建立]。

Azure CLI

提示

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

這些變數的值應該與您在本教學課程的第一個部分中所使用的相同資源。

1. 定義IoT中樞、記憶體帳戶和容器的變數。

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

   IOTHUB_NAME：以IoT中樞的名稱取代此佔位元。

   DEVICE_ID：將此佔位元取代為您的裝置識別碼。

   STORAGE_NAME：以記憶體帳戶的名稱取代此佔位元元。

   在本教學課程中，應該擴充變數的值containerName。

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. 使用 az storage container create 命令，將容器新增至您的記憶體帳戶。

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

將訊息路由傳送至第二個端點

為擴充的訊息建立第二個端點和路由。

Azure 入口網站

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

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

   

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

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

   

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

5. 繼續建立新的路由，現在您已新增記憶體端點。 提供新路由的下列資訊：

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

   

6. 選取 [ 建立 + 新增擴充]。

Azure CLI

1. 設定端點和路由命令的變數，以分別使用 Contoso 儲存體 EndpointEnriched 和 Contoso 儲存體 RouteEnriched 值。

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

   az iot hub message-endpoint create \
     --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"'
   

將訊息擴充新增至新端點

建立三個訊息擴充，以路由傳送至擴充的記憶體容器。

Azure 入口網站

1. 在 [新增路由精靈] 的 [擴充] 索引卷標上，新增三個訊息擴充，讓訊息移至名為 enriched 之記憶體容器的端點。

   將這些值新增為 Contoso 的訊息擴充 儲存體 EndpointEnriched 端點：

   名稱	值
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location （假設裝置對應項具有位置標籤）
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   當您完成時，擴充看起來應該類似下圖：

   

2. 選取 [新增 ] 以新增訊息擴充。

Azure CLI

對 az iot hub message-enrichment create 命令進行三次呼叫，以將訊息擴充新增至先前所建立端點的路由。

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

您現在已針對路由傳送至針對擴充訊息所建立端點的所有訊息設定訊息擴充。 如果您不想要將位置標籤新增至裝置對應項，您可以跳至 測試訊息擴充 區段，以繼續進行教學課程。

將位置標籤新增至裝置對應項

IoT 中樞上設定的其中一個訊息擴充會指定 DeviceLocation 的索引鍵，其值取決於下列裝置對應項路徑：$twin.tags.location。 如果您的裝置對應項沒有位置標記，則對應項路徑$twin.tags.location會戳記為訊息擴充中 DeviceLocation 機碼的字串。

請遵循下列步驟，將位置標籤新增至裝置的對應項：

Azure 入口網站

1. 流覽至 Azure 入口網站 中的IoT中樞。

2. 選取 IoT中樞導覽功能表上的 [裝置 ]，然後選取您的裝置。

3. 選取裝置頁面頂端的 [ 裝置 對應項] 索引標籤，並在裝置對應項底部的右大括號前面新增下列這一行。 然後選取儲存。

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

使用 az iot hub device-twin update 命令，以新的標籤索引鍵和值來更新裝置對應項。

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

提示

請等候大約五分鐘，再繼續進行下一節。 裝置對應項的更新最多可能需要該時間才會反映在訊息擴充值中。

若要深入瞭解如何使用訊息擴充來處理裝置對應項路徑，請參閱 訊息擴充限制。 若要深入瞭解裝置對應項，請參閱瞭解和使用 IoT 中樞 中的裝置對應項。

測試訊息擴充

現在已針對 Contoso 儲存體 EndpointEnriched 端點設定訊息擴充，請執行模擬裝置應用程式以將訊息傳送至 IoT 中樞。 此時，訊息路由已設定如下：

• 路由傳送至 您在教學課程第一部分中建立 的記憶體端點的訊息將不會擴充，而且會儲存在您建立的記憶體容器中。

• 路由傳送至記憶體端點 Contoso 的訊息 儲存體 EndpointEnriched 將會擴充並儲存在擴充的記憶體容器中。

如果您尚未從本教學課程的第一個部分執行 SimulatedDevice 主控控台應用程式，請再次執行：

提示

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

1. 在範例資料夾中，瀏覽至 /iot-hub/Tutorials/Routing/SimulatedDevice/ 資料夾。

2. 您之前更新的變數定義應該仍然有效，但如果不是，請在檔案中 Program.cs 加以編輯：

   1. 尋找 Program 類別頂端的變數定義。 使用您自己的資訊更新下列變數：

      • s_myDeviceId：向IoT中樞註冊裝置時指派的裝置標識碼。
      • s_iotHubUri：IoT 中樞的主機名，採用 格式IOTHUB_NAME.azure-devices.net。
      • s_deviceKey：裝置身分識別資訊中找到的裝置主鍵。

   2. 儲存並關閉檔案。

3. 執行範例程式代碼：

   dotnet run
   

離開主控台應用程式以執行幾分鐘之後，請檢視資料：

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

2. 從導覽功能表中選取 儲存體 瀏覽器。 選取 [Blob 容器 ] 以查看您在這些教學課程中建立的兩個容器。

   

容器中稱為 enriched 的訊息具有訊息擴充包含在訊息中。 您稍早建立之容器中的訊息具有沒有擴充的原始訊息。 向下切入擴充的容器，直到您進入底部，然後開啟最新的訊息檔案。 然後，對另一個容器執行相同的動作，以確認已擴充一個容器，另一個容器並未擴充。

當您查看已擴充的訊息時，您應該會看到 "myIotHub" 中樞名稱、位置和客戶識別碼，如下所示：

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

清除資源

若要移除您在本教學課程的兩個部分中建立的所有資源，請刪除資源群組。 此動作會刪除群組中包含的所有資源。 如果您不想刪除整個資源群組，則可以選取要刪除的個別資源。

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
     

下一步

在本教學課程中，您會在訊息路由傳送至端點時，為 IoT 中樞 訊息設定及測試訊息擴充。

如需訊息擴充的詳細資訊，請參閱 訊息擴充概觀。

若要深入瞭解 IoT 中樞，請繼續進行下一個教學課程。

教學課程：設定及使用IoT中樞的計量和記錄