Oktatóanyag: Az Azure IoT Hub üzenet-bővítésének használata

Az üzenetek bővítése lehetővé teszi az Azure IoT Hub számára, hogy további információkkal bélyegozza meg az üzeneteket, mielőtt az üzeneteket elküldené a kijelölt végpontnak. Az üzenetdúsítások használatának egyik oka, hogy olyan adatokat tartalmazzon, amelyek az alsóbb rétegbeli feldolgozás egyszerűsítése érdekében használhatók. Az eszközüzenetek ikercímkével való bővítése például csökkentheti az ügyfelek terhelését, így ikereszköz API-hívásokat indíthat ezekre az információkra. További információkért tekintse meg az üzenetek bővítésének áttekintését.

Az oktatóanyag első részében láthatta, hogyan hozhat létre egyéni végpontokat, és hogyan irányíthatja az üzeneteket más Azure-szolgáltatásokba. Ebben az oktatóanyagban megtudhatja, hogyan hozhatja létre és konfigurálhatja az IoT Hub üzenetbővítéseinek teszteléséhez szükséges további erőforrásokat. Az erőforrások közé tartozik egy második tároló egy meglévő tárfiókhoz (amelyet az oktatóanyag első részében hoztak létre) a bővített üzenetek tárolására és egy üzenetútvonalra, hogy elküldhesse őket oda. Miután befejeződött az üzenet-útválasztás és az üzenet-bővítés konfigurációja, egy alkalmazással üzeneteket küldhet az IoT Hubnak. A központ ezután mindkét tárolóhoz irányítja őket. Csak a gazdagított tároló végpontjának küldött üzenetek lesznek gazdagítva.

Az oktatóanyagban az alábbi feladatokat fogja végrehajtani:

• Hozzon létre egy második tárolót a tárfiókban.
• Hozzon létre egy másik egyéni végpontot, és irányozza az üzeneteket az IoT Hubról.
• Konfigurálja az új végpontra irányított üzenetdúsításokat.
• Futtasson egy alkalmazást, amely egy IoT-eszközt szimulál, amely üzeneteket küld a központnak.
• Tekintse meg az eredményeket, és ellenőrizze, hogy a megcélzott üzenetekre alkalmazza-e az üzenet-bővítéseket.

Előfeltételek

• Rendelkeznie kell egy Azure-előfizetéssel. Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

• Be kell fejeznie az oktatóanyagot: Eszközadatok küldése az Azure Storage-ba az IoT Hub üzenet-útválasztásával , és a számára létrehozott erőforrások fenntartása.

• Győződjön meg arról, hogy a 8883-as port nyitva van a tűzfalon. Az oktatóanyagban szereplő eszközminta MQTT protokollt használ, amely a 8883-es porton keresztül kommunikál. Ez a port néhány vállalati és oktatási hálózati környezetben blokkolható. További információkért és a probléma megoldásának módjaiért tekintse meg az IoT Hubra (MQTT) való Csatlakozás.

Azure Portal

Az Azure Portalnak nincsenek egyéb előfeltételei.

Azure CLI

• Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.

  

• Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.

  • Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.

  • Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.

  • Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

Második tároló létrehozása a tárfiókban

Az oktatóanyag első részében létrehozott egy tárfiókot és egy tárolót az irányított üzenetekhez. Most létre kell hoznia egy második tárolót a bővített üzenetekhez.

Azure Portal

1. Az Azure Portalon keressen tárfiókokat.

2. Válassza ki a korábban létrehozott fiókot.

3. A Tárfiók menüben válassza a Tárolók lehetőséget az Adattárolás szakaszban.

4. Válassza a Tároló lehetőséget az új tároló létrehozásához.

   

5. Nevezze el a tárolótenriched, és válassza a Létrehozás lehetőséget.

Azure CLI

Tipp.

Az oktatóanyag során használt parancssori felületi parancsok közül sok ugyanazokat a paramétereket használja. Az Ön kényelme érdekében meghatározzuk a helyi változókat, amelyek igény szerint hívhatók meg. Mindenképpen futtassa az összes parancsot ugyanabban a munkamenetben, különben újra kell definiálnia a változókat.

Ezeknek a változóknak az értékeinek ugyanazokra az erőforrásokra kell lenniük, amelyeket az oktatóanyag első részében használt.

1. Határozza meg az IoT Hub, a tárfiók és a tároló változóit.

   GROUP_NAME: Cserélje le ezt a helyőrzőt az IoT Hubot tartalmazó erőforráscsoport nevére.

   IOTHUB_NAME: Cserélje le ezt a helyőrzőt az IoT Hub nevére.

   DEVICE_ID: Cserélje le ezt a helyőrzőt az eszköz azonosítójára.

   STORAGE_NAME: Cserélje le ezt a helyőrzőt a tárfiók nevére.

   Ebben az oktatóanyagban a változó értékét containerName bővíteni kell.

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

2. Az az storage container create paranccsal adja hozzá a tárolót a tárfiókhoz.

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

Üzenetek átirányítása egy második végpontra

Hozzon létre egy második végpontot és útvonalat a bővített üzenetekhez.

Azure Portal

1. Az Azure Portalon nyissa meg az IoT Hubot.

2. Az Erőforrás menü Központi beállítások területén válassza az Üzenet útválasztása, majd a Hozzáadás lehetőséget.

   

3. A Végpont lapon hozzon létre egy Storage-végpontot a következő információk megadásával:

   Paraméter	Érték
   Végpont típusa	Válassza a Storage lehetőséget.
   Végpont neve	Írja be ContosoStorageEndpointEnriched.
   Azure Storage-tároló	Válassza a Tároló kiválasztása lehetőséget. Az utasításokat követve válassza ki az előző szakaszban létrehozott tárfiókot és bővített tárolót .
   Kódolás	Válassza a JSON lehetőséget. Ha ez a mező szürkítve jelenik meg, akkor a tárfiók régiója nem támogatja a JSON-t. Ebben az esetben folytassa az alapértelmezett AVRO-val.

   

4. Fogadja el a többi paraméter alapértelmezett értékeit, és válassza a Létrehozás + tovább lehetőséget.

5. Folytassa az új útvonal létrehozását, most, hogy hozzáadta a tárvégpontot. Adja meg a következő információkat az új útvonalról:

   Paraméter	Érték
   Név	ContosoStorageRouteEnriched
   Adatforrás	Ellenőrizze, hogy az eszköz telemetriai üzenetei ki van-e választva a legördülő listából.
   Útvonal engedélyezése	Ellenőrizze, hogy ez a mező be van-e állítva enabled.
   Útválasztási lekérdezés	Adja meg level="storage" a lekérdezési sztringet.

   

6. Válassza a Létrehozás és bővítés hozzáadása lehetőséget.

Azure CLI

1. Konfigurálja a végpont- és útvonalparancsok változóit a ContosoStorageEndpointEnriched és a ContosoStorageRouteEnriched értékek használatára.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Az az iot hub message-endpoint create parancsával hozzon létre egy egyéni végpontot, amely az előző szakaszban létrehozott tárolóra mutat.

   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 az iot hub message-route create paranccsal hozzon létre egy útvonalat, amely minden üzenetet level=storage továbbít a tárolóvégpontnak.

   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"'
   

Üzenetdúsítás hozzáadása az új végponthoz

Hozzon létre három üzenetbővítést, amelyek a bővített tárolóhoz lesznek irányítva .

Azure Portal

1. Az Útvonal hozzáadása varázsló Bővítés lapján adjon hozzá három üzenetbővítést a bővített nevű tároló végpontjára irányuló üzenetekhez.

   Adja hozzá ezeket az értékeket üzenetbővítésként a ContosoStorageEndpointEnriched végponthoz:

   Név szerint	Érték
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (feltételezi, hogy az ikereszköz rendelkezik helycímkével)
   Vevőkód	6ce345b8-1e4a-411e-9398-d34587459a3a

   Ha végzett, a bővítésnek a következő képhez hasonlóan kell kinéznie:

   

2. Válassza a Hozzáadás lehetőséget az üzenet bővítésének hozzáadásához.

Azure CLI

Az az iot hub üzenetbővítési létrehozási parancsának három hívásával hozzáadhatja az üzenetbővítéseket a korábban létrehozott végpontra vezető útvonalhoz.

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

Most már be van állítva az összes üzenet bővítése a bővített üzenetekhez létrehozott végpontra irányítva. Ha nem szeretne helycímkét hozzáadni az ikereszközhöz, az oktatóanyag folytatásához ugorjon az Üzenetbővítések tesztelése szakaszra.

Helycímke hozzáadása az ikereszközhöz

Az IoT Hubon konfigurált üzenetnövelések egyike megadja a DeviceLocation kulcsát, amelynek értékét az alábbi ikereszköz-elérési út határozza meg: $twin.tags.location Ha az ikereszköze nem rendelkezik helycímkével, $twin.tags.locationaz ikerpéldány elérési útja sztringként lesz megjelölve a DeviceLocation kulcshoz az üzenet bővítési pontjaiban.

Kövesse az alábbi lépéseket, ha helycímkét szeretne hozzáadni az eszköz ikerpéldányához:

Azure Portal

1. Lépjen az IoT Hubra az Azure Portalon.

2. Válassza az Eszközök lehetőséget az IoT Hub navigációs menüjében, majd válassza ki az eszközt.

3. Válassza az ikereszköz lapot az eszközlap tetején, és adja hozzá a következő sort az ikereszköz alján található záró zárójel előtt. Ezután válassza a Mentés lehetőséget.

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

   

Azure CLI

Az az iot hub device-twin update parancsával frissítse az ikereszközt egy új címkekulcs és érték használatával.

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

Tipp.

Várjon körülbelül öt percet, mielőtt továbblép a következő szakaszra. Akár ennyi ideig is eltarthat, amíg az ikereszköz frissítései megjelennek az üzenetgazdagítási értékekben.

Ha többet szeretne megtudni arról, hogy az ikereszköz-útvonalak hogyan kezelhetők az üzenetdúsításokkal, tekintse meg az üzenetnövelési korlátozásokat. Az ikereszközökkel kapcsolatos további információkért tekintse meg az IoT Hub ikerpéldányainak megértését és használatát ismertető témakört.

Üzenetbővítések tesztelése

Most, hogy az üzenetbővítések konfigurálva lettek a ContosoStorageEndpointEnriched végponthoz, futtassa a szimulált eszközalkalmazást, hogy üzeneteket küldjön az IoT Hubnak. Ezen a ponton az üzenet-útválasztás a következőképpen lett beállítva:

• Az oktatóanyag első részében létrehozott tárolási végpontra átirányított üzenetek nem lesznek gazdagítva, és az akkor létrehozott tárolóban lesznek tárolva.

• A ContosoStorageEndpointEnriched tárolóvégpontra átirányított üzenetek gazdagodnak, és a tárolóban gazdagodnak.

Ha az oktatóanyag első részében még nem futtatja a SimulatedDevice konzolalkalmazást, futtassa újra:

Tipp.

Ha az oktatóanyaghoz tartozó Azure CLI-lépéseket követi, futtassa a mintakódot egy külön munkamenetben. Így engedélyezheti a mintakód futtatását a parancssori felület többi lépésének végrehajtása közben.

1. A mintamappában keresse meg a /iot-hub/Tutorials/Routing/SimulatedDevice/ mappát.

2. A korábban frissített változódefinícióknak továbbra is érvényesnek kell lenniük, de ha nem, szerkessze őket a Program.cs fájlban:

   1. Keresse meg a változódefiníciókat a Program osztály tetején. Frissítse a következő változókat a saját adataival:

      • s_myDeviceId: Az eszköz IoT Hubra való regisztrálásakor hozzárendelt eszközazonosító.
      • s_iotHubUri: Az IoT Hub gazdagépneve, amely a formátumot IOTHUB_NAME.azure-devices.netveszi fel.
      • s_deviceKey: Az eszköz identitásadataiban található elsődleges eszközkulcs.

   2. Mentse és zárja be a fájlt.

3. Futtassa a mintakódot:

   dotnet run
   

Miután elhagyta a konzolalkalmazást, hogy néhány percig fusson, tekintse meg az adatokat:

1. Az Azure Portalon lépjen a tárfiókra.

2. Válassza a Storage böngészőt a navigációs menüből. A Blob-tárolók kiválasztásával megtekintheti az oktatóanyagok során létrehozott két tárolót.

   

A gazdagított tárolóban lévő üzenetekben szerepelnek az üzenetekben található üzenetdúsítások. A korábban létrehozott tárolóban lévő üzenetek nyers üzenetekkel rendelkeznek, és nem rendelkeznek bővítéssel. Fúrjon le a bővített tárolóba, amíg el nem ér az aljára, majd nyissa meg a legújabb üzenetfájlt. Ezután tegye ugyanezt a másik tároló esetében is annak ellenőrzéséhez, hogy az egyik gazdagodott-e, és hogy az egyik nem.

Ha a bővített üzeneteket tekinti meg, a központ nevét, helyét és ügyfél-azonosítóját a következőképpen kell látnia "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"
}

Az erőforrások eltávolítása

Az oktatóanyag mindkét részében létrehozott összes erőforrás eltávolításához törölje az erőforráscsoportot. Ez a művelet törli a csoportban lévő összes erőforrást. Ha nem szeretné törölni a teljes erőforráscsoportot, az egyes erőforrásokat is kijelölheti a törléshez.

Azure Portal

1. Az Azure Portalon keresse meg azt az erőforráscsoportot, amely az oktatóanyaghoz tartozó IoT Hub- és tárfiókot tartalmazza.
2. Tekintse át az erőforráscsoportban található összes erőforrást, és állapítsa meg, hogy mely erőforrásokat szeretné törölni.
   • Ha az összes erőforrást törölni szeretné, válassza az Erőforráscsoport törlése lehetőséget.
   • Ha csak bizonyos erőforrásokat szeretne törölni, az egyes erőforrásnevek melletti jelölőnégyzetekkel jelölje ki a törölni kívánt erőforrásokat. Ezután válassza a Törlés elemet.

Azure CLI

1. Az az resource list paranccsal megtekintheti az erőforráscsoport összes erőforrását.

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

2. Tekintse át az erőforráscsoportban található összes erőforrást, és állapítsa meg, hogy mely erőforrásokat szeretné törölni.

   • Ha az összes erőforrást törölni szeretné, használja az az group delete parancsot.

     az group delete --name $resourceGroup
     

   • Ha csak bizonyos erőforrásokat szeretne törölni, használja az az resource delete parancsot. Példa:

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

Következő lépések

Ebben az oktatóanyagban konfigurálta és tesztelte az IoT Hub-üzenetek üzeneteinek bővítését, miközben azokat egy végpontra irányítják.

Az üzenetdúsításokkal kapcsolatos további információkért tekintse meg az üzenetek bővítésének áttekintését.

Az IoT Hubról további információt a következő oktatóanyagban talál.

Oktatóanyag: Metrikák és naplók beállítása és használata IoT Hub használatával