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

發行項
05/24/2023

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

在本教學課程的第一個部分中，您已瞭解如何建立自訂端點，並將訊息路由傳送至其他 Azure 服務。在本教學課程中，您會看到如何建立和設定測試 IoT 中樞訊息擴充所需的額外資源。這些資源包含現有儲存體帳戶的第二個儲存體容器 (在本教學課程的第一個部分中建立的) 保存擴充的訊息和訊息路由，以便傳送到該處。在您完成訊息路由和訊息擴充的設定後，便能使用應用程式將訊息傳送至 IoT 中樞。中樞便會將訊息路由傳送至這兩個儲存體容器。僅擴充傳送至 enriched 儲存體容器端點的訊息。

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

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

必要條件

您必須擁有 Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
您必須已完成教學課程：使用 IoT 中樞訊息路由，將裝置資料傳送至 Azure 儲存體，並維護您為其建立的資源。
請確定您的防火牆已開啟連接埠 8883。本教學課程中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。某些公司和教育網路環境可能會封鎖此連接埠。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

Azure 入口網站
Azure CLI

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

在您的儲存體帳戶中建立第二個容器

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

Azure 入口網站
Azure CLI

在 Azure 入口網站中，搜尋儲存體帳戶。
選取您稍早建立的帳戶。
在儲存體帳戶功能表中，從 [資料儲存體] 中選取 [容器]。
選取 [容器] 以建立新的容器。
將容器 enriched 命名為，然後選取 [ 建立]。

秘訣

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

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

定義 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
```

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

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

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

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

Azure 入口網站
Azure CLI

在 Azure 入口網站中，移至您的 IoT 中樞。
在 [中 樞設定] 底下的 [資源] 功能表中，選取 [ 訊息路由 ]，然後選取 [ 新增]。

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

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

螢幕擷取畫面：選取端點容器。

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

繼續建立新路由，現在您已新增儲存體端點。請提供新路由的下列資訊：

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

螢幕擷取畫面：儲存路由查詢資訊。

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

設定端點和路由命令的變數，以分別使用 ContosoStorageEndpointEnriched 和 ContosoStorageRouteEnriched 值。
```
endpointName=ContosoStorageEndpointEnriched
routeName=ContosoStorageRouteEnriched
```

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

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

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

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

將訊息擴充新增至新的端點

建立將路由傳送至擴充儲存體容器的三個訊息擴充。

Azure 入口網站
Azure CLI

在 [新增路由精靈] 的 [擴充] 索引標籤上，針對移至名為enriched之儲存體容器端點的訊息新增三個訊息擴充。

將這些值新增為 ContosoStorageEndpointEnriched 端點的訊息擴充：

名稱值

myIotHub $hubname

DeviceLocation $twin.tags.location (假設裝置對應項具有位置標記)

customerID 6ce345b8-1e4a-411e-9398-d34587459a3a

完成時，您的擴充看起來應該類似下圖：
選取 [新增 ] 以新增訊息擴充。

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

對 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 入口網站
Azure CLI

瀏覽至您在 Azure 入口網站中的 IoT 中樞。
選取 IoT 中樞導覽功能表上的 [ 裝置 ]，然後選取您的裝置。
選取裝置頁面頂端的 [裝置對應項] 索引標籤，然後在裝置對應項底端的右大括號前方新增下行。然後選取 [儲存]。
```
  , "tags": {"location": "Plant 43"}
```

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

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

秘訣

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

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

測試訊息擴充

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

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

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

秘訣

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

在範例資料夾中，瀏覽至 /iot-hub/Tutorials/Routing/SimulatedDevice/ 資料夾。
您之前更新的變數定義仍然有效，但如果不是，請在 Program.cs 檔案中編輯這些定義：
1. 尋找程式類別頂端的變數定義。使用您自己的資訊更新下列變數：
  - s_myDeviceId：將裝置註冊到 IoT 中樞時所指派的裝置識別碼。
  - s_iotHubUri：採用格式 IOTHUB_NAME.azure-devices.net，您的 IoT 中樞主機名稱。
  - s_deviceKey：裝置身分識別資訊中找到的裝置主索引鍵。
2. 儲存並關閉檔案。
執行範例程式碼：
```
dotnet run
```

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

在 Azure 入口網站中，瀏覽至您的儲存體帳戶。
然後從瀏覽功能表選取 [儲存體瀏覽器]。選取 [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 入口網站
Azure CLI

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

使用 az resource list 命令檢視您資源群組中的所有資源。
```
az resource list --resource-group $resourceGroup --output table
```
檢閱資源群組中的所有資源，以判斷您要清除哪些資源。
- 若要刪除所有資源，請使用 az group delete 命令。
```
az group delete --name $resourceGroup
```
- 如果只想要刪除特定資源，請使用 az resource delete 命令。例如：
```
az resource delete --resource-group $resourceGroup --name $storageName
```

後續步驟

在本教學課程中，您已在訊息路由至端點時，針對 IoT 中樞訊息設定及測試訊息擴充。

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

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

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