Megosztás a következőn keresztül:

Kommunikáció egy IoT Hubbal az MQTT protokoll használatával

Ez a cikk azt ismerteti, hogy az eszközök hogyan használhatják az MQTT protokollt az Azure IoT Hubbal való kommunikációhoz. Az IoT Hub-eszközvégpontok a következőkkel támogatják az eszközkapcsolatot:

Megjegyzés:

A cikkben említett egyes funkciók, például a felhő–eszköz irányú üzenetküldés, az ikereszközök és az eszközfelügyelet csak a standard szintű IoT Hubon érhető el. Az alapszintű és standard/ingyenes IoT Hub-szintekkel kapcsolatban további információkért lásd Válassza ki a megoldása számára megfelelő IoT Hub-szintet és -méretet.

Az IoT Hubbal folytatott összes eszközkommunikációt TLS használatával kell védeni. Ezért az IoT Hub nem támogatja a nem biztonságos MQTT-kapcsolatokat az 1883-es porton keresztül.

MQTT-támogatás összehasonlítása az IoT Hubban és az Event Gridben

Az IoT Hub nem teljes körű MQTT-közvetítő, és nem támogatja az MQTT v3.1.1 szabványban megadott összes viselkedést. Ha a megoldáshoz felhőalapú MQTT-közvetítőre van szüksége, használja inkább az Azure Event Gridet . Az Event Grid kétirányú kommunikációt tesz lehetővé az MQTT-ügyfelek között rugalmas hierarchikus témakörökben egy közzétételre feliratkozott üzenetkezelési modell használatával. Lehetővé teszi az MQTT-üzenetek átirányítását más Azure-szolgáltatásokba vagy egyéni végpontokra további feldolgozás céljából.

Az alábbi táblázat a két szolgáltatás MQTT-támogatásának aktuális különbségeit foglalja össze:

IoT Hub Eseményhálózat
Ügyfél-kiszolgáló modell az eszközök és a felhőalkalmazások szoros összekapcsolásával. Közzétételi-előfizetési modell, amely elválasztja a közzétevőket és az előfizetőket.
Korlátozott funkciótámogatás az MQTT 3.1.1-es verzióhoz. MQTT v3.1.1 és v5 protokoll támogatása.
Statikus, előre definiált témakörök. Egyéni hierarchikus témakörök helyettesítő karakterek támogatásával.
Nem támogatottak a felhőből az eszközre irányuló közvetítések vagy az eszközök közötti kommunikáció. Támogatja az eszköz-felhő, a széles sugárzású felhő-eszköz közötti közvetítéseket és az eszköz-eszköz közötti kommunikációs mintákat.
256 KB maximális üzenetméret. 512 KB maximális üzenetméret.

Csatlakozás az IoT Hubhoz

Az eszközök az MQTT protokoll használatával csatlakozhatnak egy IoT Hubhoz az alábbi lehetőségek egyikével:

Számos vállalati és oktatási tűzfal blokkolja az MQTT-portot (TCP-port: 8883). Ha nem tudja megnyitni a 8883-at a tűzfalon, használja az MQTT-t WebSocketeken keresztül. A WebSocket-en keresztüli MQTT a 443-es porton keresztül kommunikál, ami szinte mindig nyitva van. Az Azure IoT SDK-k használata során az MQTT és az MQTT WebSockets protokollok megadásának módjáról az Eszköz SDK-k használata című témakörben olvashat.

Az eszköz SDK-k használata

Az MQTT protokollt támogató Azure IoT-eszköz SDK-k Java, Node.js, C, C# és Python esetén érhetők el. Az eszköz SDK-k a választott hitelesítési mechanizmussal létesítenek kapcsolatot egy IoT Hubhoz. Az MQTT protokoll használatához az ügyfélprotokoll paraméterét MQTT értékre kell állítani. Az ügyfélprotokoll paraméterben websocketeken keresztül is megadhatja az MQTT-t. Az eszköz SDK-jai alapértelmezés szerint egy IoT Hubhoz csatlakoznak a 0-rabeállított CleanSession jelzővel, és a QoS 1 használatával váltanak üzeneteket az IoT Hubbal. Bár a QoS 0 konfigurálható a gyorsabb üzenetcsere érdekében, vegye figyelembe, hogy a kézbesítés nem garantált, és nem nyugtázható. Ezért a QoS 0-t gyakran "tüzelj és felejts"-nek is nevezik.

Amikor egy eszköz IoT Hubhoz csatlakozik, az eszköz SDK-jai olyan módszereket biztosítanak, amelyekkel az eszköz üzeneteket cserélhet egy IoT Hubbal.

Az alábbi táblázat az egyes támogatott nyelvekhez tartozó kódmintákra mutató hivatkozásokat tartalmaz, és meghatározza azt a paramétert, amelyet az MQTT vagy az MQTT over WebSockets protokoll használatával az IoT Hubhoz való csatlakozáshoz használ.

Nyelv MQTT protokollparaméter MQTT protokollparaméter WebSockets felett
Node.js azure-iot-device-mqtt.Mqtt azure-iot-device-mqtt.MqttWs
Jáva IotHubClientProtocol. MQTT IotHubClientProtocol.MQTT_WS
C MQTT_Protocol MQTT_WebSocket_Protocol
C# TransportType. MQTT A TransportType.Mqtt visszaesik az MQTT-hez WebSocketsen keresztül, ha az MQTT meghiúsul. Ha csak WebSocketeken szeretné megadni az MQTT-t, használja a TransportType.Mqtt_WebSocket_Only
Piton Alapértelmezés szerint MQTT-t használ Az ügyfél létrehozásához adja hozzá websockets=True a híváshoz.

Az alábbi töredék bemutatja, hogyan adhatja meg az MQTT over WebSockets protokollt az Azure IoT Node.js SDK használatakor:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

Az alábbi töredék bemutatja, hogyan adhatja meg az MQTT over WebSockets protokollt az Azure IoT Python SDK használatakor:

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

Fontos

Ez a cikk az eszközök közös hozzáférésű jogosultságkóddal, más néven szimmetrikus kulcshitelesítéssel való csatlakoztatásának lépéseit tartalmazza. Ez a hitelesítési módszer alkalmas tesztelésre és kiértékeléshez, de az eszköz hitelesítése X.509-tanúsítványokkal biztonságosabb módszer. További információkért tekintse meg az IoT-megoldások biztonsági javaslatait és a kapcsolatbiztonságot>.

Alapértelmezett életben tartási időkeret

Annak érdekében, hogy az IoT Hub-kapcsolat ügyfélkapcsolata életben maradjon, a szolgáltatás és az ügyfél is rendszeresen küld egymásnak egy keep-alive pinget. Ha az eszköz egyik SDK-ját használja, az ügyfél a következő táblázatban meghatározott időközönként küld egy életben maradó üzenetet:

Nyelv Alapértelmezett életben tartási időköz Konfigurálható
Node.js 180 másodperc Nem
Jáva 230 másodperc Nem
C 240 másodperc Igen
C# 300* másodperc Igen
Piton 60 másodperc Igen

*A C# SDK az MQTT KeepAliveInSeconds tulajdonság alapértelmezett értékét 300 másodpercként határozza meg. A valóságban az SDK egy pingelési jelzést négyszer küld az életben tartási időtartam alatt. Más szóval az SDK 75 másodpercenként küld egy élő pinget.

Az MQTT 3.1.1-es specifikációját követve az IoT Hub életben tartásának pingelési időköze 1,5-szerese az ügyfél életben tartásának; Az IoT Hub azonban a kiszolgálóoldali időtúllépés maximális időtartamát 29,45 percre (1767 másodpercre) korlátozza.

Egy Java SDK-t használó eszköz például elküldi az életben maradó pinget, majd elveszíti a hálózati kapcsolatot. 230 másodperccel később az eszköz elmulasztja az életben tartási pinget, mert offline állapotban van. Az IoT Hub azonban nem zárja be azonnal a kapcsolatot – a DeviceConnectionClosedRemotely(230 * 1.5) - 230 = 115még egy másodpercet vár, mielőtt leválasztaná az eszközt.

A kapcsolat maximálisan beállítható életben tartási ideje 1767 / 1.5 = 1177 másodperc. Minden forgalom alaphelyzetbe állítja az életben tartást. Például egy megosztott hozzáférési jogosultságkód (SAS) token sikeres frissítése alaphelyzetbe állítja a kapcsolat fenntartását.

Eszközalkalmazás migrálása AMQP-ről MQTT-be

Ha az eszköz SDK-jait használja, az AMQP-ről az MQTT-re való váltáshoz módosítania kell a protokollparamétert az ügyfél inicializálásában.

Amikor AMQP-ről MQTT-ra vált, ellenőrizze a következő elemeket:

  • Az AMQP számos feltétel hibáit adja vissza, míg az MQTT megszakítja a kapcsolatot. Emiatt előfordulhat, hogy módosítania kell a kivételkezelési logikát.

  • Az MQTT nem támogatja az elutasítási műveletet, ha felhőből eszközre irányuló üzeneteket fogad. Ha a háttéralkalmazásnak választ kell kapnia az eszközalkalmazástól, fontolja meg a közvetlen módszerek használatát.

  • Az AMQP nem támogatott a Python SDK-ban.

Az MQTT protokoll használata közvetlenül egy eszközről

Ha egy eszköz nem tudja használni az IoT-eszköz SDK-jait, akkor is csatlakozhat a nyilvános eszközvégpontokhoz a 8883-es port MQTT protokolljával.

Fontos

Ez a cikk az eszközök közös hozzáférésű jogosultságkóddal, más néven szimmetrikus kulcshitelesítéssel való csatlakoztatásának lépéseit tartalmazza. Ez a hitelesítési módszer alkalmas tesztelésre és kiértékeléshez, de az eszköz hitelesítése X.509-tanúsítványokkal biztonságosabb módszer. További információkért tekintse meg az IoT-megoldások biztonsági javaslatait és a kapcsolatbiztonságot>.

A CONNECT-csomagban az eszköznek a következő értékeket kell használnia:

  • A ClientId mezőhöz használja az eszközazonosítót.

  • A Felhasználónév mezőben használja a {iotHub-hostname}/{device-id}/?api-version=2021-04-12, ahol a {iotHub-hostname} az IoT Hub teljes CName neve.

    Ha például az IoT Hub neve contoso.azure-devices.net , és ha az eszköz neve MyDevice01, a Felhasználónév mező a következőket tartalmazza:

    contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

    A váratlan viselkedés elkerülése érdekében adja meg az API-verziót a mezőben.

  • A Jelszó mezőben használjon SAS-jogkivonatot. Az alábbi kódrészlet az SAS-jogkivonat formátumát mutatja be:

    SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    Megjegyzés:

    Ha X.509-tanúsítványhitelesítést használ, az SAS-jogkivonat jelszavai nem szükségesek. További információ : Oktatóanyag: Tanúsítványok létrehozása és feltöltése teszteléshez , és kövesse a TLS konfigurációs szakaszában található kódutasításokat.

    Az SAS-jogkivonatok létrehozásának módjáról további információt az Sas-jogkivonatok használata az IoT Hubhoz való hozzáférés vezérlése eszközként a közös hozzáférésű jogosultságkódok használatával című szakaszában talál.

    A Visual Studio Code Azure IoT Hub-bővítményét vagy az az iot hub generate-sas-token parancssori felületi bővítmény parancsát is használhatja SAS-jogkivonat létrehozásához. Ezután tesztelési célokra másolhatja és beillesztheti az SAS-jogkivonatot a saját kódjába.

    A bővítmény létrehoz egy SAS-jogkivonatot a következő struktúrával:

    HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

    Ennek a jogkivonatnak a MQTT használatával történő csatlakozáshoz szükséges jelszó mezőként használt része a következő:

    SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Az eszközalkalmazás megadhat egy Will-üzenetet a CONNECT-csomagban . Az eszközalkalmazásnak a devices/{device-id}/messages/events/ vagy devices/{device-id}/messages/events/{property-bag} témakörnevet kell használnia mint Will, a telemetriai üzenetként továbbítandó Will-üzenetek meghatározásához. Ebben az esetben, ha a hálózati kapcsolat lezárult, de az eszközről korábban nem érkezett DISCONNECT csomag, akkor az IoT Hub elküldi a Will üzenetet a CONNECT csomagban megadva a telemetriai csatornára. A telemetriai csatorna lehet az alapértelmezett Eseményvégpont vagy az IoT Hub-útválasztás által definiált egyéni végpont. Az üzenethez hozzá van rendelve az iothub-MessageType tulajdonság, amelynek értéke Will .

Az MQTT protokoll használata közvetlenül egy modulból

Az IoT Hubhoz MQTT-n keresztül is csatlakozhat egy modulidentitás használatával. Ez a megközelítés hasonló az eszközként való csatlakozáshoz, de a következő értékeket kell használnia:

  • Állítsa be az ügyfélazonosítót a következőre {device-id}/{module-id}: .

  • Ha felhasználónévvel és jelszóval hitelesíti a felhasználónevet, állítsa be a felhasználónevet a következőre <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12: . Ha SAS-t használ, használja a modul identitásához társított SAS-jogkivonatot jelszóként.

  • devices/{device-id}/modules/{module-id}/messages/events/ használandó a telemetria közzétételének témájaként.

  • devices/{device-id}/modules/{module-id}/messages/events/ használja a Will témakörként.

  • Üzenetek fogadására használja a devices/{device-id}/modules/{module-id}/# témakört.

  • Az iker GET és a PATCH témakörök ugyanazok a modulok és eszközök esetében.

  • Az ikerállapot-témakör a modulok és az eszközök esetében is ugyanaz.

Az MQTT modulokkal való használatáról az IoT Edge Hub MQTT-végpontja nyújt további információt.

Azure IoT-eszköz SDK nélküli MQTT-t használó minták

Az IoT MQTT-mintaadattár C/C++, Python és CLI-mintákat tartalmaz, amelyek bemutatják, hogyan küldhet telemetriai üzeneteket, fogadhat felhőből eszközre irányuló üzeneteket, és hogyan használhat ikereszközöket az Azure-eszköz SDK-k használata nélkül.

A C/C++ minták az Eclipse Mosquitto

További információ: Oktatóanyag – Az MQTT használata IoT-eszközügyfél fejlesztésére eszköz SDK használata nélkül.

TLS-konfiguráció

Az MQTT protokoll közvetlen használatához az ügyfélnek TLS 1.2-n keresztül kell csatlakoznia. A lépés kihagyására tett kísérletek csatlakozási hibákkal meghiúsulnak.

TLS-kapcsolat létrehozásához előfordulhat, hogy le kell töltenie és hivatkoznia kell az Azure által használt DigiCert Global Root G2 főtanúsítványra. A tanúsítványról további információt a Digicert webhelyén talál.

Az alábbi példa bemutatja, hogyan implementálhatja ezt a konfigurációt a Paho MQTT-kódtár Python-verziójával.

Először telepítse a Paho-kódtárat a parancssori környezetből:

pip install paho-mqtt

Ezután implementálja az ügyfelet egy Python-szkriptben. Cserélje le ezeket a helyőrzőket a következő kódrészletben:

  • <local path to digicert.cer> A DigiCert főtanúsítványt tartalmazó helyi fájl elérési útja. Ezt a fájlt úgy hozhatja létre, hogy a tanúsítványinformációkat a certs.c fájlból másolja a C-hez készült Azure IoT SDK-ba. Adja hozzá a sorokat-----BEGIN CERTIFICATE-----, és -----END CERTIFICATE-----távolítsa el a " jeleket minden sor elején és végén, és távolítsa el a \r\n karaktereket minden sor végén.

  • <device id from device registry> az IoT Hubhoz hozzáadott eszköz azonosítója.

  • A <generated SAS token> a jelen cikkben korábban ismertetett módon létrehozott eszköz SAS-jogkivonata.

  • <iot hub name> az IoT Hub neve.

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

Eszköztanúsítvány használatával történő hitelesítéshez frissítse az előző kódrészletet az alábbi kódrészletben megadott módosításokkal. A tanúsítványalapú hitelesítésre való felkészülésről további információt az X.509 CA tanúsítvány beszerzése szakaszban talál az X.509 tanúsítvánnyal történő hitelesítés dokumentumban.

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

Eszközről felhőbe irányuló üzenetek küldése

Miután egy eszköz csatlakozott, üzeneteket küldhet az IoT Hubnak, a devices/{device-id}/messages/events/ vagy devices/{device-id}/messages/events/{property-bag}témakörnév használatával. Az {property-bag} elem lehetővé teszi, hogy az eszköz más tulajdonságokkal rendelkező üzeneteket küldjön URL-kódolású formátumban. Például:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Ez az {property_bag} elem ugyanazt a kódolást használja, mint a HTTPS protokoll lekérdezési sztringjei.

Ha D2C-üzeneteket szeretne átirányítani egy Azure Storage-fiókba, és JSON-kódolást szeretne használni, meg kell adnia a tartalomtípust és a tartalomkódolási adatokat, beleértve $.ct=application%2Fjson&$.ce=utf-8az {property_bag} előző megjegyzésben említett adatokat is.

Megjegyzés:

Ezeknek az attribútumoknak a formátuma protokollspecifikus. Az IoT Hub ezeket az attribútumokat lefordítja a megfelelő rendszertulajdonságokra. További információt az IoT Hub üzenet-útválasztási lekérdezés szintaxisának Rendszertulajdonságok szakaszában talál.

Az alábbi lista az IoT Hub MQTT implementációspecifikus viselkedéseit foglalja össze:

  • Az IoT Hub nem támogatja a QoS 2-üzeneteket. Ha egy eszközalkalmazás a QoS 2 használatával tesz közzé üzenetet, az IoT Hub bezárja a hálózati kapcsolatot.

  • Az IoT Hub nem őriz meg Retain üzeneteket. Ha egy eszköz 1 értékre állított RETAIN jelzővel küld üzenetet, az IoT Hub hozzáadja az mqtt-retain alkalmazás tulajdonságot az üzenethez. Ebben az esetben a megtartott üzenet megőrzése helyett az IoT Hub átadja azt a háttéralkalmazásnak.

  • Az IoT Hub eszközönként csak egy aktív MQTT-kapcsolatot támogat. Ha egy új MQTT-kapcsolat ugyanazon eszközazonosító nevében történik, az IoT Hub elveti a meglévő kapcsolatot, és 400027 ConnectionForcefullyClosedOnNewConnectiont ír az IoT Hub-naplókba

  • Az üzenetek üzenettörzs alapján történő átirányításához először adjon hozzá tulajdonságot ct az MQTT-témakör végére, és állítsa az értékét application/json;charset=utf-8 az alábbi példában látható módon. Az üzenetek üzenettulajdonságok vagy üzenettörzs alapján történő útválasztásával kapcsolatos további információkért tekintse meg az IoT Hub üzenet-útválasztási lekérdezés szintaxisának dokumentációját.

    devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

További információ: Üzenetek küldése és fogadása az IoT Hub használatával.

Felhőből eszközre irányuló üzenetek fogadása

Az IoT Hubtól érkező üzenetek fogadásához az eszköznek devices/{device-id}/messages/devicebound/#témakörszűrőként kell előfizetnie. A témakörszűrő többszintű helyettesítő karaktere # lehetővé teszi, hogy az eszköz további tulajdonságokat kapjon a témakör nevében. Az IoT Hub nem engedélyezi a # vagy ? helyettesítő karakterek használatát az altopikák szűréséhez. Az IoT Hub nem általános célú közzétételi-feliratkozási üzenetközvetítő, csak a dokumentált témakörneveket és témakörszűrőket támogatja. Egy eszköz egyszerre csak öt témakörre tud előfizetni.

Az eszköz nem kap üzeneteket az IoT Hubtól, amíg sikeresen elő nem iratkozhat az eszközspecifikus végpontjára, amelyet a devices/{device-id}/messages/devicebound/# témakörszűrő jelöl. Az előfizetés létrehozása után az eszköz megkapja a felhőből az eszközre irányuló üzeneteket, amelyeket az előfizetés időpontja után küldtek neki. Ha az eszköz 0-ra beállított CleanSession jelzővel csatlakozik, az előfizetés különböző munkamenetekben megmarad. Ebben az esetben a következő alkalommal, amikor az eszköz CleanSession 0-val csatlakozik, megkap minden függőben lévő üzenetet, amelyeket a leválasztott állapotban küldtek neki. Ha az eszköz az 1-nek beállított CleanSession jelzőt használja, addig nem kap üzeneteket az IoT Hubtól, amíg elő nem iratkozhat az eszközvégpontjára.

Az IoT Hub a témakörnévveldevices/{device-id}/messages/devicebound/vagy devices/{device-id}/messages/devicebound/{property-bag} üzenettulajdonságokkal rendelkező üzeneteket küld. {property-bag} URL-kódolt kulcs-/értékpárokat tartalmaz az üzenettulajdonságokhoz. A tulajdonságcsomagban csak az alkalmazástulajdonságok és a felhasználó által beállított rendszertulajdonságok (például messageId vagy correlationId) szerepelnek. A rendszertulajdonságok nevei előtaggal $rendelkeznek, az alkalmazástulajdonságok az eredeti tulajdonságnevet használják előtag nélkül. A tulajdonságcsomag formátumáról további információt az eszközről a felhőbe irányuló üzenetek küldése című témakörben talál.

A felhőből az eszközre irányuló üzenetekben a tulajdonságcsomag értékei az alábbi táblázatban látható módon jelennek meg:

Tulajdonságérték Képviselet Leírás
null key Csak a kulcs jelenik meg a tulajdonságcsomagban
üres karaktersorozat key= Az egyenlőségjel után következő kulcsnak nincs értéke
nem null, nem üres érték key=value A kulcs, majd egy egyenlőségjel és az érték

Az alábbi példa egy tulajdonság tárolót mutat be, amely három alkalmazástulajdonságot tartalmaz: prop1 értéke null; prop2, egy üres sztring (""); és prop3 értéke "egy sztring".

/?prop1&prop2=&prop3=a%20string

Amikor egy eszközalkalmazás feliratkozik egy QoS 2-es témakörre, az IoT Hub maximális 1. szintű QoS-szintet biztosít a SUBACK-csomagban . Ezt követően az IoT Hub az 1. QoS használatával küld üzeneteket az eszköznek.

Ikereszköz tulajdonságainak lekérése

Először egy eszköz feliratkozik a $iothub/twin/res/#művelet válaszainak fogadásához. Ezután egy üres üzenetet küld a $iothub/twin/GET/?$rid={request id} témára, amely egy kitöltött kérésazonosítóval rendelkezik. A szolgáltatás ezután egy válaszüzenetet küld, amely az ikereszköz adatait tartalmazza a témakörben $iothub/twin/res/{status}/?$rid={request-id}, ugyanazzal a kérésazonosítóval , mint a kérés.

A kérésazonosító bármilyen érvényes érték lehet egy üzenettulajdonság értékéhez, és az állapot egész számként van érvényesítve. További információ: Üzenetek küldése és fogadása az IoT Hub használatával.

A válasz törzse az ikereszköz tulajdonságok szakaszát tartalmazza, ahogyan az a következő válaszpéldában is látható:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

A lehetséges állapotkódok a következők:

Státusz Leírás
200 (No changes required, the translation remains "Siker.")
429 Túl sok kérés (korlátozva). További információ: IoT Hub-kvóták és szabályozás
5** Kiszolgálóhibák

További információért olvassa el a Eszköz ikerállapotok megértése és használata az IoT Hubban című részt.

Az ikereszköz jelentett tulajdonságainak frissítése

A jelentett tulajdonságok frissítéséhez az eszköz kérést küld az IoT Hubnak egy kijelölt MQTT-témakör közzétételével. Miután az IoT Hub feldolgozta a kérést, a frissítési művelet sikeres vagy sikertelen állapotával válaszol egy másik témakörbe való közzététellel. Az eszköz feliratkozhat erre a témakörre, hogy értesítéseket kapjon az ikerfrissítési kérelem eredményéről. Az ilyen típusú kérés-válasz interakció az MQTT-ben való implementálásához az eszköz a kezdeti frissítési kérelemben egy kérésazonosítót ($rid) biztosít. Ez a kérésazonosító ekkor megjelenik az IoT Hub válaszában, hogy az eszköz a megfelelő kéréssel korrelálja a választ.

Az alábbi sorozat bemutatja, hogyan frissíti az eszköz a jelentett tulajdonságokat az IoT Hub ikereszközén:

  1. Egy eszköz először feliratkozik a $iothub/twin/res/# témakörre, hogy választ kapjon az IoT Hubtól.

  2. Az eszköz egy üzenetet küld, amely tartalmazza az ikereszköz frissítését a $iothub/twin/PATCH/properties/reported/?$rid={request-id} témakörhöz. Ez az üzenet egy kérésazonosító-értéket tartalmaz.

  3. A szolgáltatás ezután egy válaszüzenetet küld, amely tartalmazza a témakör $iothub/twin/res/{status}/?$rid={request-id}jelentett tulajdonsággyűjteményének új ETag-értékét. Ez a válaszüzenet ugyanazt a kérésazonosítót használja, mint a kérés.

A kérelemüzenet törzse egy JSON-dokumentumot tartalmaz, amely új értékeket tartalmaz a jelentett tulajdonságokhoz. A JSON-dokumentum minden tagja frissül, vagy hozzáadja a megfelelő tagot az ikereszköz dokumentumához. Az a tag, amelyet null-ra állítanak, törlődik a tartalmazó objektumból. Például:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

A lehetséges állapotkódok a következők:

Státusz Leírás
204 Siker (nem ad vissza tartalmat)
400 Hibás kérés. Hibásan formázott JSON
429 Túl sok kérés (korlátozva), az IoT Hub kvótáinak és korlátozásának megfelelően
5** Kiszolgálóhibák

Az alábbi Python-kódrészlet bemutatja az ikrek jelentett tulajdonságainak frissítési folyamatát az MQTT-n keresztül a Paho MQTT-ügyfél használatával.

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

Ha az ikerpéldány által jelentett tulajdonságok frissítési folyamata sikeres, az IoT Hub egy üzenetet tesz közzé a következő témakörben: $iothub/twin/res/204/?$rid=1&$version=6, ahol 204 az állapotkód jelzi a sikerességet, $rid=1 megfelel az eszköz által a kódban megadott kérelemazonosítónak, és $version az ikerkészülékek jelentett tulajdonságok szakaszának verzióját jelzi a frissítés után.

További információért olvassa el a Eszköz ikerállapotok megértése és használata az IoT Hubban című részt.

Kívánt tulajdonságok frissítési értesítésének fogadása

Amikor egy eszköz csatlakozik, az IoT Hub értesítéseket küld a témakörnek $iothub/twin/PATCH/properties/desired/?$version={new-version}, amely tartalmazza a megoldás háttérrendszere által végrehajtott frissítés tartalmát. Például:

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

A tulajdonságfrissítések esetében az értékek azt jelentik, null hogy a JSON-objektumtag törölve van. Az $version jelzi az új verzióját a digitális ikermodell kívánt tulajdonságok szakaszának.

Fontos

Az IoT Hub csak akkor hoz létre változásértesítéseket, ha az eszközök csatlakoztatva vannak. Győződjön meg arról, hogy implementálja az eszköz újracsatlakozási folyamatát , hogy a kívánt tulajdonságok szinkronizálva maradjanak az IoT Hub és az eszközalkalmazás között.

További információért olvassa el a Eszköz ikerállapotok megértése és használata az IoT Hubban című részt.

Válasz közvetlen metódusra

Először egy eszköz előfizet a következőre $iothub/methods/POST/#: . Az IoT Hub metóduskérelmeket küld a $iothub/methods/POST/{method-name}/?$rid={request-id} témakörnek, vagy érvényes JSON vagy üres törzs használatával.

A válaszhoz az eszköz egy érvényes JSON-t vagy üres törzset tartalmazó üzenetet küld a témakörnek $iothub/methods/res/{status}/?$rid={request-id}. Ebben az üzenetben a kérelemazonosítónak meg kell egyeznie a kérelemüzenetben szereplő azonosítóval , az állapotnak pedig egész számnak kell lennie.

További információért lásd: Közvetlen metódusok megismerése és meghívása az IoT Hub segítségével.

Következő lépések

Az MQTT használatáról az alábbiakban olvashat bővebben: