Felhőből eszközre irányuló üzenetek küldése és fogadása

Az Azure IoT Hub egy teljes mértékben felügyelt szolgáltatás, amely lehetővé teszi a kétirányú kommunikációt, beleértve a felhőből az eszközre irányuló (C2D) üzeneteket a megoldás hátoldaláról több millió eszközre.

Ez a cikk az Azure IoT SDK-k használatát ismerteti a következő típusú alkalmazások létrehozásához:

Olyan eszközalkalmazások, amelyek egy IoT Hub üzenetsorból fogadják és kezelik a felhőből az eszközre irányuló üzeneteket.
Háttéralkalmazások, amelyek egy IoT Hub üzenetsoron keresztül küldenek felhőből eszközre irányuló üzeneteket egyetlen eszközre.

Ez a cikk az ebben a cikkben hivatkozott futtatható SDK-mintákat hivatott kiegészíteni.

Feljegyzés

A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők 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.

Áttekintés

Ahhoz, hogy egy eszközalkalmazás fogadhassa a felhőből az eszközre irányuló üzeneteket, csatlakoznia kell az IoT Hubhoz, majd be kell állítania egy üzenetkezelőt a bejövő üzenetek feldolgozásához. Az Azure IoT Hub eszközoldali SDK-jai osztályokat és metódusokat biztosítanak, amelyekkel az eszköz fogadhat és kezelhet üzeneteket a szolgáltatásból. Ez a cikk az üzeneteket fogadó eszközalkalmazások legfontosabb elemeit ismerteti, többek között a következőket:

Eszközügyfél-objektum deklarálása
Csatlakozás az IoT Hubhoz
Üzenetek lekérése az IoT Hub üzenetsorából
Az üzenet feldolgozása és nyugtázás küldése az IoT Hubnak
Fogadási üzenet újrapróbálkozására vonatkozó szabályzat konfigurálása

Ahhoz, hogy egy háttéralkalmazás felhőből eszközre irányuló üzeneteket küldjön, csatlakoznia kell egy IoT Hubhoz, és üzeneteket kell küldenie egy IoT Hub üzenetsoron keresztül. Az Azure IoT Hub szolgáltatás SDK-jai osztályokat és metódusokat biztosítanak, amelyekkel az alkalmazások üzeneteket küldhetnek az eszközöknek. Ez a cikk minden olyan alkalmazás fő elemeit ismerteti, amelyek üzeneteket küldenek az eszközöknek, beleértve a következőket:

Szolgáltatásügyfél-objektum deklarálása
Csatlakozás az IoT Hubhoz
Az üzenet létrehozása és elküldése
Kézbesítési visszajelzések fogadása
Üzenetküldési újrapróbálkozési szabályzat konfigurálása

Az üzenetsor ismertetése

A felhőalapú üzenetküldés megértéséhez fontos megérteni az IoT Hub eszközüzenet-üzenetsorainak működésével kapcsolatos alapvető tudnivalókat.

A megoldás háttéralkalmazásából az IoT-eszközre küldött felhőalapú üzenetek az IoT Hubon keresztül lesznek átirányítva. Nincs közvetlen társközi üzenetkommunikáció a megoldás háttéralkalmazása és a céleszköz között. Az IoT Hub a bejövő üzeneteket az üzenetsorba helyezi, és készen áll a cél IoT-eszközök általi letöltésre.

Az IoT Hub az üzenetek legalább egyszer történő kézbesítésének biztosítása érdekében az eszközenkénti üzenetsorokban továbbra is megőrzi a felhőből az eszközre irányuló üzeneteket. Az eszközöknek kifejezetten el kell fogadniuk az üzenet befejezését, mielőtt az IoT Hub eltávolítja az üzenetet az üzenetsorból. Ez a megközelítés garantálja a csatlakozási és eszközhibákkal szembeni rugalmasságot.

Amikor az IoT Hub egy üzenetsorba helyez egy üzenetet, az üzenet állapotát Enqueued értékre állítja. Amikor egy eszközszál üzenetet fogad az üzenetsorból, az IoT Hub zárolja az üzenetet úgy, hogy az üzenet állapotát láthatatlanra állítja. Ez az állapot megakadályozza, hogy az eszközön lévő többi szál ugyanazt az üzenetet tudják feldolgozni. Ha egy eszközszál sikeresen befejezi egy üzenet feldolgozását, értesíti az IoT Hubot, majd az IoT Hub befejezett állapotúra állítja az üzenet állapotát.

Egy olyan eszközalkalmazás, amely sikeresen fogad és feldolgoz egy üzenetet, azt mondja, hogy fejezze be az üzenetet. Szükség esetén azonban az eszköz a következőket is megteheti:

Utasítsa el az üzenetet, ami miatt az IoT Hub a Dead (Halott) betűs állapotra állítja. A Message Queuing Telemetry Transport (MQTT) protokollon keresztül csatlakozó eszközök nem utasíthatják el a felhőből az eszközre irányuló üzeneteket.
Hagyja abba az üzenetet, ami miatt az IoT Hub visszaállítja az üzenetet az üzenetsorba, és az üzenet állapota Enqueued értékre van állítva. Az MQTT protokollon keresztül csatlakozó eszközök nem hagyhatják fel a felhőből az eszközre irányuló üzeneteket.

A felhőből az eszközre irányuló üzenet életciklusáról és arról, hogy az IoT Hub hogyan dolgozza fel a felhőből az eszközre irányuló üzeneteket, olvassa el a felhőből az eszközre irányuló üzenetek küldése az IoT Hubról című témakört.

Eszközalkalmazás létrehozása

Ez a szakasz a felhőből az eszközre irányuló üzenetek fogadását ismerteti.

Az eszközügyfél-alkalmazás kétféleképpen fogadhat üzeneteket:

Visszahívás: Az eszközalkalmazás beállít egy aszinkron üzenetkezelő metódust, amelyet azonnal meghív egy üzenet érkezésekor.
Lekérdezés: Az eszközalkalmazás egy while vagy for kódhurok használatával ellenőrzi az új IoT Hub-üzeneteket. A hurok folyamatosan fut, és üzeneteket keres.

Szükséges eszköz NuGet-csomag

A C# nyelven írt eszközügyfél-alkalmazásokhoz a Microsoft.Azure.Devices.Client NuGet-csomag szükséges.

Adja hozzá ezeket az using utasításokat az eszköztár használatához.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Eszköz csatlakoztatása az IoT Hubhoz

Az eszközalkalmazások az alábbi módszerekkel végezhetnek hitelesítést az IoT Hubon:

Megosztott hozzáférési kulcs
X.509-tanúsítvány

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>.

Hitelesítés megosztott hozzáférési kulccsal

A DeviceClient osztály elérhetővé teszi az eszközön az üzenetek fogadásához szükséges összes metódust.

Adja meg az IoT Hub elsődleges kapcsolati sztringjét és az eszközazonosítót DeviceClient a(z) CreateFromConnectionString metódus használatához. A szükséges elsődleges IoT Hub-kapcsolati sztring mellett a CreateFromConnectionString metódus túlterhelhető az alábbi választható paraméterekkel:

transportType - A átviteli protokoll: a HTTP 1-es, AMQP- vagy MQTT-verziói. A AMQP az alapértelmezett formátum. Az összes elérhető érték megtekintéséhez lásd : TransportType Enum.
transportSettings - Az DeviceClient és ModuleClient különböző átvitelspecifikus beállításainak meghatározására használt interfész. További információ: ITransportSettings Interface.
ClientOptions – Az eszköz vagy modul ügyfélpéldányának inicializálás során történő konfigurálását lehetővé tevő beállítások.

Ez a példa a Mqtt szállítási protokoll használatával csatlakozik egy eszközhöz.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Hitelesítés X.509-tanúsítvánnyal

Eszköz csatlakoztatása az IoT Hubhoz X.509-tanúsítvány használatával:

A DeviceAuthenticationWithX509Certificate használatával olyan objektumot hozhat létre, amely eszköz- és tanúsítványinformációkat tartalmaz. DeviceAuthenticationWithX509Certificate második paraméterként lesz átadva DeviceClient.Create (2. lépés).
A DeviceClient.Create használatával X.509-tanúsítvány használatával csatlakoztathatja az eszközt az IoT Hubhoz.

Ebben a példában az eszköz- és tanúsítványinformációk ki lesznek töltve a authDeviceAuthenticationWithX509Certificate továbbított DeviceClient.Createobjektumban.

Ez a példa a tanúsítvány bemeneti paraméterértékeit mutatja be helyi változóként az egyértelműség érdekében. Éles rendszerben a bizalmas bemeneti paramétereket környezeti változókban vagy más biztonságosabb tárolási helyen tárolhatja. Például használja a Environment.GetEnvironmentVariable("HOSTNAME")-t a gazdagépnév környezeti változójának olvasásához.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

További információ a tanúsítványhitelesítésről:

Kódminták

Az X.509-tanúsítványhitelesítés munkamintáiért lásd:

Visszahívás

Ha visszahívási felhőből eszközre irányuló üzeneteket szeretne fogadni az eszközalkalmazásban, az alkalmazásnak csatlakoznia kell az IoT Hubhoz, és be kell állítania egy visszahívási figyelőt a bejövő üzenetek feldolgozásához. Az eszközre érkező üzenetek az IoT Hub üzenetsorából érkeznek.

A visszahívás használatával az eszközalkalmazás beállít egy üzenetkezelő metódust a SetReceiveMessageHandlerAsync használatával. A rendszer meghívja az üzenetkezelőt, majd egy üzenet érkezik. Ha visszahívási módszert hoz létre az üzenetek fogadásához, azzal nem szükséges folyamatosan lekérdezni a fogadott üzeneteket.

A visszahívás csak az alábbi protokollok használatával érhető el:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only

A Http1 protokollbeállítás nem támogatja a visszahívásokat, mivel az SDK-metódusoknak egyébként is le kell keresni a fogadott üzeneteket, ami a visszahívási elvet is legyőzi.

Ebben a példában SetReceiveMessageHandlerAsync beállít egy hívásvisszahívás-kezelő metódust, amelynek neve OnC2dMessageReceivedAsyncminden egyes üzenet fogadásakor meg lesz hívva.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

ciklikus lekérdezések

A lekérdezés a ReceiveAsync használatával ellenőrzi az üzeneteket.

A ReceiveAsync hívása az alábbi módokon történhet:

ReceiveAsync() – A folytatás előtt várja meg az üzenet alapértelmezett időtúllépési időtartamát.
ReceiveAsync (Timespan) – Üzenet fogadása az eszközsorból egy adott időtúllépéssel.
ReceiveAsync (CancellationToken) – Üzenet fogadása az eszközsorban egy törlési token használatával. Lemondási jogkivonat használata esetén a rendszer nem használja az alapértelmezett időtúllépési időszakot.

Ha MQTT vagy AMQP helyett HTTP 1 átviteli típust használ, a ReceiveAsync metódus azonnal visszatér. A HTTP 1-et használó felhőalapú üzenetek támogatott mintája időszakosan csatlakoztatott eszközök, amelyek ritkán (legalább 25 percenként) ellenőrzik az üzeneteket. További HTTP 1 kibocsátása esetén az IoT Hub korlátozza a kéréseket. Az MQTT, az AMQP és a HTTP 1 támogatás közötti különbségekről további információt a felhőalapú kommunikációs útmutatóban és a Kommunikációs protokoll kiválasztása című témakörben talál.

CompleteAsync metódus

Miután az eszköz megkapta az üzenetet, az eszközalkalmazás meghívja a CompleteAsync metódust, hogy értesítse az IoT Hubot az üzenet sikeres feldolgozásáról, és hogy az üzenet biztonságosan eltávolítható az IoT Hub eszközsorából. Az eszköznek ezt a metódust akkor kell meghívnia, ha a feldolgozás sikeresen befejeződik, függetlenül attól, hogy milyen átviteli protokollt használ.

Üzenet elhagyása, elutasítása vagy időtúllépés

Az AMQP és a HTTP 1-es verziójú protokollokkal, de az MQTT protokolllal nem, az eszköz a következőket is megteheti:

AbandonAsync meghívásával hagyja el az üzenetet. Ez azt eredményezi, hogy az IoT Hub megtartja az üzenetet az eszközsorban későbbi felhasználás céljából.
Üzenet elvetése a RejectAsync meghívásával. Ezzel véglegesen eltávolítja az üzenetet az eszközsorból.

Ha olyan esemény történik, amely megakadályozza az eszköz számára az üzenet befejezését, elhagyását vagy elutasítását, az IoT Hub egy rögzített időtúllépési időszak után újra sorba állítja az üzenetet kézbesítés céljából. Ezért az eszközalkalmazás üzenetfeldolgozási logikájának idempotensnek kell lennie, hogy ugyanazt az üzenetet többször megkapva ugyanazt az eredményt hozza létre.

Lekérdezési ciklus

A lekérdezések használatával egy alkalmazás kódhurkot használ, amely ismételten meghívja a ReceiveAsync metódust, hogy új üzeneteket keressen, amíg le nem áll.

Ha ReceiveAsync-t időtúllépési értékkel vagy alapértelmezett időtúllépéssel használ, a ciklusban minden egyes hívás a ReceiveAsync-hoz a megadott időtúllépési időszakra vár. Ha ReceiveAsync túllépi az időkorlátot, a függvény visszaad egy null értéket, és a ciklus folytatódik.

Üzenet érkezésekor a rendszer egy feladatobjektumot ad vissza, amelyet át kell adni a CompleteAsyncnekReceiveAsync. Egy hívás, amely értesíti az CompleteAsync IoT Hubot, hogy a paraméter alapján törölje a megadott üzenetet az Task üzenetsorból.

Ebben a példában a hurok addig hív ReceiveAsync , amíg egy üzenet nem érkezik, vagy a lekérdezési ciklus le nem áll.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Az üzenet újrapróbálkozási szabályzatának fogadása

Az eszközügyfél-üzenet újrapróbálkozási szabályzata a DeviceClient.SetRetryPolicy használatával határozható meg.

Az üzenet újrapróbálkozási időtúllépése a DeviceClient.OperationTimeoutInMilliseconds tulajdonságban van tárolva.

SDK-üzenetminta fogadása

A .NET/C# SDK tartalmaz egy üzenet fogadási mintát, amely tartalmazza az ebben a szakaszban ismertetett fogadási üzenet metódusokat.

Háttéralkalmazás létrehozása

Ez a szakasz azokat az alapvető kódot ismerteti, amelyek egy megoldás háttéralkalmazásából üzenetet küldenek egy IoT-eszközre az Azure IoT SDK for .NET ServiceClient osztályával. Ahogy korábban említettem, egy megoldás háttéralkalmazása csatlakozik egy IoT Hubhoz, és üzeneteket küld a céleszközzel kódolt IoT Hubnak. Az IoT Hub a bejövő üzeneteket az üzenetsorba tárolja, az üzenetek pedig az IoT Hub üzenetsorából érkeznek a céleszközre.

A megoldás háttéralkalmazásai az üzenetsoron keresztül az eszközkézbesítésre szánt IoT Hubnak küldött üzenet kézbesítési visszajelzését is kérhetik és fogadhatják.

Szolgáltatás NuGet-csomag hozzáadása

A háttérszolgáltatás-alkalmazásokhoz a Microsoft.Azure.Devices NuGet-csomag szükséges.

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Ez a cikk a szolgáltatáshoz való csatlakozás lépéseit tartalmazza közös hozzáférésű jogosultságkód használatával. Ez a hitelesítési módszer a teszteléshez és a kiértékeléshez kényelmes, de biztonságosabb módszer a Microsoft Entra-azonosítóval vagy felügyelt identitásokkal történő hitelesítés egy szolgáltatáshoz. További információkért tekintse meg a felhőalapú biztonság > IoT-megoldások biztonsági legjobb gyakorlatait.

Csatlakozás megosztott hozzáférési szabályzattal

Háttéralkalmazás csatlakoztatása egy eszközhöz a CreateFromConnectionString használatával. A szükséges elsődleges IoT Hub-kapcsolati sztring mellett a CreateFromConnectionString metódus túlterhelhető az alábbi választható paraméterekkel:

transportType - Amqp vagy Amqp_WebSocket_Only.
transportSettings - A szolgáltatásügyfél AMQP- és HTTP-proxybeállításai.
ServiceClientOptions – Azok a beállítások, amelyek lehetővé teszik a szolgáltatásügyfél-példány konfigurálását az inicializálás során. További információ: ServiceClientOptions.

Ez a példa az ServiceClient IoT Hub kapcsolati sztring és az alapértelmezett Amqp átvitel használatával hozza létre az objektumot.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a token az IoT Hub-kapcsolati metódusnak átadódik. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

Titkos ügyfélkód
Tanúsítvány
Federált identitás hitelesítő adat

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikermodul közreműködői például szükségesek az IoT Hub-eszközök és modulikrek olvasási és írási hozzáférésének engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információt a Gyorsútmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon című részben találhat.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbb módja egy háttéralkalmazás hitelesítésének a DefaultAzureCredential használata, de ajánlott egy másik módszert választani éles környezetben, beleértve egy adott TokenCredential vagy egyszerűsített ChainedTokenCredential metódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a DefaultAzureCredential használati útmutatója tartalmaz.

DefaultAzureCredential támogatja a különböző hitelesítési mechanizmusokat, és meghatározza a megfelelő hitelesítőadat-típust az általa futtatott környezet alapján. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra megköveteli ezeket a NuGet-csomagokat és a hozzájuk tartozó using utasításokat:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfélkulcsa, ügyfél-azonosítója és bérlőazonosítója hozzáadódik a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat hitelesítő adat, amelyet továbbítanak egy IoT Hub-kapcsolati módszerhez.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Az eredményül kapott TokenCredential ezután átadható egy IoT Hub-metódushoz való csatlakozásnak minden olyan SDK-ügyfél esetében, amely elfogadja a Microsoft Entra hitelesítő adatait:

Ebben a példában a TokenCredential átadásra kerül a ServiceClient.Create számára, hogy létrehozzon egy ServiceClient kapcsolati objektumot.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Ebben a példában a TokenCredentialRegistryManager.Create-hoz kerül átadásra, hogy létrehozzon egy RegistryManager objektumot.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Kódrészlet

A Microsoft Entra szolgáltatáshitelesítés működő mintájáért tekintse meg a szerepköralapú hitelesítési mintát.

Aszinkron felhőből eszközre irányuló üzenet küldése

A sendAsync használatával aszinkron üzenetet küldhet egy alkalmazásból a felhőn (IoT Hub) keresztül az eszközre. A hívás az AMQP protokoll használatával történik.

sendAsync a következő paramétereket használja:

deviceID - A céleszköz sztringazonosítója.
message - A felhőből az eszközre irányuló üzenet. Az üzenet üzenet típusú, és ennek megfelelően formázható.
timeout - Egy opcionális időtúllépési érték. Az alapértelmezett érték egy perc, ha nincs meghatározva.

Ez a példa egy 10 másodperces időtúllépési értékkel rendelkező tesztüzenetet küld a céleszköznek.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Kézbesítési visszajelzések fogadása

A küldő programok az IoT Hubtól kérhetnek kézbesítési (vagy lejárati) visszaigazolást minden felhőből eszközre irányuló üzenethez. Ez a beállítás lehetővé teszi, hogy a küldő program informálást, újrapróbálkozási vagy kompenzációs logikát használjon. Az üzenetvisszajelzési műveletek és tulajdonságok teljes leírását az Üzenetvisszajelzés című témakörben olvashatja.

Üzenetkézbesítési visszajelzés fogadása:

Az feedbackReceiver objektum létrehozása
Üzenetek küldése a Ack paraméterrel
Várjon, amíg visszajelzést kap

A feedbackReceiver objektum létrehozása

Hívja meg a GetFeedbackReceivert egy FeedbackReceiver objektum létrehozásához. FeedbackReceiver olyan metódusokat tartalmaz, amelyekkel a szolgáltatások visszajelzési fogadási műveleteket hajthatnak végre.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Üzenetek küldése az Ack paraméterrel

Minden üzenetnek tartalmaznia kell egy értéket a kézbesítési visszaigazolás Ack tulajdonságához a kézbesítési visszajelzés fogadásához. A Ack tulajdonság az alábbi értékek egyike lehet:

nincs (alapértelmezett): nincs visszajelzési üzenet.
Positive: visszajelzést kap, ha az üzenet befejeződött.
Negative: visszajelzést kap, ha az üzenet lejárt (vagy elérte a maximális kézbesítési számot) anélkül, hogy az eszköz befejezte volna.
Full: visszajelzés mind Positive és az Negative eredményekről.

Ebben a példában a Ack tulajdonság úgy van beállítva, hogy Fullpozitív vagy negatív üzenetkézbesítési visszajelzést kérjen egy üzenethez.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Várjon, amíg visszajelzést kap

Definiálja a CancellationToken. Ezután egy ciklusban hívja meg többször a ReceiveAsync-et , és ellenőrizze a kézbesítési visszajelzési üzeneteket. Minden hívás az ReceiveAsync objektumhoz megadott időtúllépési ServiceClient időszakra vár.

Ha egy ReceiveAsync időtúllépés üzenet nélkül lejár, visszatérReceiveAsync, null és a ciklus folytatódik.
Ha visszajelzési üzenet érkezik, a rendszer egy feladatobjektumot ad vissza, amelyet ReceiveAsync át kell adni a CompleteAsyncnek a lemondási jogkivonattal együtt. A CompleteAsync hívás törli az üzenetsor megadott elküldött üzenetét a Task paraméter alapján.
Szükség esetén a fogadási kód meghívhatja az AbandonAsync-et, hogy egy üzenetet visszahelyezzen az üzenetsorba.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

Ez a példa egy metódust mutat be, amely ezeket a lépéseket tartalmazza.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

Vegye figyelembe, hogy ez a visszajelzés fogadási mintája hasonló az eszközalkalmazásban a felhőből az eszközre irányuló üzenetek fogadásához használt mintához.

Szolgáltatásügyfél újracsatlakoztatása

Kivétel észlelése esetén a szolgáltatásügyfél továbbítja ezeket az információkat a hívó alkalmazásnak. Ezen a ponton javasoljuk, hogy vizsgálja meg a kivétel részleteit, és hajtsa végre a szükséges lépéseket.

Példa:

Ha hálózati kivételről van szó, újrapróbálhatja a műveletet.
Ha ez biztonsági kivétel (jogosulatlan kivétel), ellenőrizze a hitelesítő adatait, és győződjön meg arról, hogy naprakészek.
Ha ez egy szabályozási/kvóta túllépésével kapcsolatos kivételek, figyelje és/vagy módosítsa a kérések küldésének gyakoriságát, vagy frissítse a hub példány méretezési egységét. Részletekért lásd az IoT Hub kvótáit és szabályozását .

Üzenet újrapróbálkozési szabályzatának küldése

Az ServiceClient üzenet újrapróbálkozási szabályzata a ServiceClient.SetRetryPolicy használatával határozható meg.

SDK-üzenetküldési példa

A .NET/C# SDK szolgáltatásügyfél-mintát tartalmaz, amely tartalmazza az ebben a szakaszban ismertetett küldési üzenet metódusokat.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan fogadhat felhőből eszközre irányuló üzeneteket a DeviceClient osztály használatával a Java-hoz készült Azure IoT SDK-ból.

Ahhoz, hogy egy Java-alapú eszközalkalmazás fogadhassa a felhőből az eszközre irányuló üzeneteket, csatlakoznia kell az IoT Hubhoz, majd be kell állítania egy visszahívásfigyelőt és üzenetkezelőt az IoT Hubról érkező bejövő üzenetek feldolgozásához.

Azure IoT Java SDK-kódtárak importálása

A cikkben hivatkozott kód ezeket az SDK-kódtárakat használja.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

Eszköz csatlakoztatása az IoT Hubhoz

Az eszközalkalmazások az alábbi módszerekkel végezhetnek hitelesítést az IoT Hubon:

Megosztott hozzáférési kulcs
X.509-tanúsítvány

Fontos

Hitelesítés megosztott hozzáférési kulccsal

A DeviceClient objektum példányosításához a következő paraméterek szükségesek:

connString – Az IoT-eszköz kapcsolati karaktersorozata. A kapcsolati sztring kulcs-érték párok készlete, amelyeket ";" választ el egymástól, a kulcsokat és az értékeket pedig "=" választja el egymástól. A következő kulcsok értékeit kell tartalmaznia: HostName, DeviceId, and SharedAccessKey.
Átviteli protokoll – A DeviceClient kapcsolat az alábbi IoTHubClientProtocol átviteli protokollok egyikét használhatja. AMQP a legsokoldalúbb, lehetővé teszi az üzenetek gyakori ellenőrzését, és lehetővé teszi az üzenetek elutasítását és megszakítását. Az MQTT nem támogatja az üzenetek visszautasítását vagy elhagyását:
- AMQPS
- AMQPS_WS
- HTTPS
- MQTT
- MQTT_WS

Példa:

static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Hitelesítés X.509-tanúsítvánnyal

Eszköz csatlakoztatása az IoT Hubhoz X.509-tanúsítvány használatával:

Hozza létre az SSLContext objektumot a buildSSLContext használatával.
Adja hozzá az SSLContext adatokat egy ClientOptions-objektumhoz .
Hívja meg a DeviceClientet az ClientOptions információk használatával az eszköz–IoT Hub kapcsolat létrehozásához.

Ez a példa a tanúsítvány bemeneti paraméterértékeit mutatja be helyi változóként az egyértelműség érdekében. Éles rendszerben a bizalmas bemeneti paramétereket környezeti változókban vagy más biztonságosabb tárolási helyen tárolhatja. Például egy nyilvános kulcsú tanúsítványsztring környezeti változójának olvasására használható Environment.GetEnvironmentVariable("PUBLICKEY") .

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

További információ a tanúsítványhitelesítésről:

Kódminták

Az X.509-tanúsítványhitelesítés munkamintáiért lásd:

Az üzenetvisszahívási módszer beállítása

A setMessageCallback metódussal definiálhat egy üzenetkezelő metódust, amely az IoT Hubtól érkező üzenet érkezésekor értesítést kap.

setMessageCallback a következő paramétereket tartalmazza:

callback - A visszahívási metódus neve. Lehet null.
context - Opcionális típusú környezet. Ha nincs meghatározva, használja null .

Ebben a példában egy callback metódust, amelynek a neve MessageCallback és nincs kontextusparamétere, átadunk a setMessageCallback-nak.

client.setMessageCallback(new MessageCallback(), null);

Üzenetvisszahívás-kezelő létrehozása

A visszahívási üzenetkezelő fogadja és feldolgozza az IoT Hub üzenetsorából továbbított bejövő üzenetet.

Ebben a példában az üzenetkezelő feldolgoz egy bejövő üzenetet, majd visszaadja az IotHubMessageResult.COMPLETE értéket. A IotHubMessageResult.COMPLETE visszatérési érték értesíti az IoT Hubot, hogy az üzenet feldolgozása sikeresen megtörtént, és az üzenet biztonságosan eltávolítható az eszközsorból. Az eszköznek a feldolgozás sikeres befejezésekor vissza kell térnie IotHubMessageResult.COMPLETE , és értesítenie kell az IoT Hubot arról, hogy az üzenetet el kell távolítani az üzenetsorból, függetlenül attól, hogy milyen protokollt használ.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Az üzenet elhagyási és elutasítási lehetőségei

Bár az eszközre nagyszámú üzenet érkezik, amelyeket sikeresen kell fogadni, ami IotHubMessageResult.COMPLETE eredményezhet, előfordulhat, hogy el kell vetni vagy el kell utasítani egy üzenetet.

Az AMQP és a HTTPS használatával, de az MQTT-vel nem, az alkalmazások a következőt tehetik:
- IotHubMessageResult.ABANDON az üzenet. Az IoT Hub újra lekérdezi, és később újra elküldi.
- IotHubMessageResult.REJECT az üzenet. Az IoT Hub nem kérdezi le újra az üzenetet, és véglegesen eltávolítja az üzenetet az üzenetsorból.
Az ügyfelek, akik MQTT vagy MQTT_WS használják, nem tudnak ABANDON vagy REJECT üzeneteket.

Feljegyzés

Ha az MQTT vagy AMQP helyett HTTPS-t használ átvitelként, a DeviceClient-példány ritkán (legalább 25 percenként) ellenőrzi az IoT Hubtól érkező üzeneteket. Az MQTT, az AMQP és a HTTPS-támogatás közötti különbségekről további információt a felhőalapú kommunikációs útmutatóban és a Kommunikációs protokoll kiválasztása című témakörben talál.

Az üzenetállapot visszahívási módszerének létrehozása

Az alkalmazások a registerConnectionStatusChangeCallback használatával regisztrálhatnak egy visszahívási metódust, amelyet akkor kell végrehajtani, amikor az eszköz kapcsolati állapota megváltozik. Így az alkalmazás észlelheti a leállásos üzeneteket, és megpróbálhat újracsatlakozni.

Ebben a példában IotHubConnectionStatusChangeCallbackLogger a kapcsolat állapotváltozásának visszahívási függvényeként van regisztrálva.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

A visszahívás aktiválódik, és átad egy ConnectionStatusChangeContext objektumot.

Hívás connectionStatusChangeContext.getNewStatus() az aktuális kapcsolat állapotának lekéréséhez.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

A visszaadott kapcsolati állapot az alábbi értékek egyike lehet:

IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED

Hívás connectionStatusChangeContext.getNewStatusReason() a kapcsolat állapotváltozásának okának lekéréséhez.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Hívja fel connectionStatusChangeContext.getCause()-t, hogy megtudja a kapcsolat állapotváltozásának okát. getCause() akkor térhet vissza null , ha nem áll rendelkezésre információ.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

A jelen cikk SDK-beli üzenetminta szakaszában szereplő HandleMessages-mintábantalál egy teljes mintát, amely bemutatja, hogyan nyerheti ki az állapotváltozás visszahívási módszer kapcsolatának állapotát, az eszköz állapotának változásának okát és a környezetet.

Az eszköz és az IoT Hub közötti kapcsolat megnyitása

Nyissa meg az eszköz és az IoT Hub közötti kapcsolatot. Az eszköz mostantól aszinkron módon küldhet és fogadhat üzeneteket egy IoT Hubba és onnan. Ha az ügyfél már meg van nyitva, a metódus nem tesz semmit.

client.open(true);

SDK-üzenetminta fogadása

HandleMessages: a Java-hoz készült Microsoft Azure IoT SDK-hoz tartozó mintaeszköz-alkalmazás, amely csatlakozik az IoT Hubhoz, és felhőből eszközre irányuló üzeneteket fogad.

Háttéralkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan küldhet felhőből eszközre üzenetet a Java Azure IoT SDK ServiceClient osztályával. A megoldás háttéralkalmazása csatlakozik egy IoT Hubhoz, és az üzeneteket egy céleszközzel kódolt IoT Hubba küldi. Az IoT Hub a bejövő üzeneteket az üzenetsorba tárolja, az üzenetek pedig az IoT Hub üzenetsorából érkeznek a céleszközre.

A megoldás háttéralkalmazásai az üzenetsoron keresztül az eszközkézbesítésre szánt IoT Hubnak küldött üzenet kézbesítési visszajelzését is kérhetik és fogadhatják.

A függőségi utasítás hozzáadása

Adja hozzá a függőséget az iothub-java-service-client csomag használatához az alkalmazásban az IoT Hub szolgáltatással való kommunikációhoz:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Importálási utasítások hozzáadása

Adja hozzá ezeket az importálási utasításokat az Azure IoT Java SDK és a kivételkezelő használatához.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Csatlakozás megosztott hozzáférési szabályzattal

A kapcsolati protokoll definiálása

Az IotHubServiceClientProtocol használatával definiálhatja a szolgáltatásügyfél által az IoT Hubbal való kommunikációhoz használt alkalmazásréteg protokollt.

IotHubServiceClientProtocol csak a AMQPS vagy AMQPS_WS enumokat fogadja el.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

A ServiceClient objektum létrehozása

Hozza létre a ServiceClient objektumot, megadva az IoT Hub kapcsolatát és protokollját.

String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);

Az alkalmazás és az IoT Hub közötti kapcsolat megnyitása

nyissa meg az AMQP-küldő kapcsolatot. Ez a módszer létrehozza az alkalmazás és az IoT Hub közötti kapcsolatot.

serviceClient.open();

Csatlakozás a Microsoft Entra használatával

A Java SDK-hitelesítés áttekintéséhez tekintse meg a Java és az Azure Identity használatával történő Azure-hitelesítést.

Az egyszerűség kedvéért ez a szakasz az ügyféltitkos hitelesítés leírására összpontosít.

A Microsoft Entra alkalmazás konfigurálása

Titkos ügyfélkód
Tanúsítvány
Federált identitás hitelesítő adat

A Microsoft Entra-alkalmazások beállításáról további információt a Gyorsútmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon című részben találhat.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbb módja egy háttéralkalmazás hitelesítésének a DefaultAzureCredential használata, de ajánlott egy másik módszert választani éles környezetben, beleértve egy adott TokenCredential vagy egyszerűsített ChainedTokenCredential metódust is. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a Java Azure Identity ügyfélkódtárában található Hitelesítőadat-láncok című témakörben talál.

A DefaultAzureCredential különböző hitelesítési mechanizmusokat támogat, és meghatározza a megfelelő hitelesítőadat-típust a környezet alapján, amelyben végrehajtja. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra alkalmazás hitelesítő adatait a DefaultAzureCredentialBuilder használatával hitelesítheti. Mentse a kapcsolati paramétereket, például az ügyfél titkos bérlőazonosítóját, az ügyfélazonosítót és az ügyfél titkos kódértékeit környezeti változóként. A TokenCredential létrehozása után passzolja a ServiceClient vagy más építő számára hitelesítő adat paraméterként.

Ebben a példában DefaultAzureCredentialBuilder megpróbál hitelesíteni egy kapcsolatot a DefaultAzureCredential szakaszban leírt listából. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági token hitelesítő adata, amelyet a rendszer átad egy konstruktornak, például a ServiceClient konstruktorának.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Hitelesítés a ClientSecretCredentialBuilder használatával

A ClientSecretCredentialBuilder használatával létrehozhat egy hitelesítő adatot az ügyfél titkos adataival. Ha sikeres, ez a metódus egy TokenCredential értéket ad vissza, amely átadható a ServiceClientnek vagy más szerkesztőnek hitelesítőadat-paraméterként.

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosító-értékeit hozzáadtuk a környezeti változókhoz. Ezeket a környezeti változókat a hitelesítő adatok létrehozásához használják ClientSecretCredentialBuilder .

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Egyéb hitelesítési osztályok

A Java SDK az alábbi osztályokat is tartalmazza, amelyek egy háttéralkalmazást hitelesítenek a Microsoft Entra használatával:

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáiért lásd a szerepköralapú hitelesítési mintát.

Visszajelzés-fogadó megnyitása üzenetkézbesítési visszajelzésekhez

Az IoT Hub visszajelzéseinek fogadásához használhatja a FeedbackReceiver eszközt az elküldött üzenetek kézbesítéséhez. Az FeedbackReceiver egy specializált vevő, amelynek Receive módszere FeedbackBatch helyett Message-t ad vissza.

Ebben a példában az FeedbackReceiver objektum létrejön, és az open() utasítás meghívásával várjuk a visszajelzést.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Üzenettulajdonságok hozzáadása

Igény szerint a setProperties használatával is hozzáadhat üzenettulajdonságokat. Ezek a tulajdonságok szerepelnek az eszköznek küldött üzenetben, és az eszközalkalmazás a kézhezvételkor kinyerheti őket.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Aszinkron üzenet létrehozása és küldése

Az Üzenet objektum tárolja az elküldendő üzenetet. Ebben a példában egy "Felhőből eszközre üzenet" jelenik meg.

Használja a setDeliveryAcknowledgement függvényt, hogy kérje az IoT Hub üzenetsorának kézbesítési/nem kézbesítési nyugtázását. Ebben a példában a kért nyugtázás Full kézbesítve vagy nincs kézbesítve.

A SendAsync használatával aszinkron üzenetet küldhet az ügyfélről az eszközre. Másik lehetőségként használhatja a (nem aszinkron Send ) metódust, de ez a függvény belsőleg van szinkronizálva, így egyszerre csak egy küldési művelet engedélyezett. Az üzenet az alkalmazásból az IoT Hubra érkezik. Az IoT Hub az üzenetet az üzenetsorba helyezi, készen arra, hogy a céleszközre kézbesítse.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Üzenetkézbesítési visszajelzések fogadása

Miután az alkalmazás üzenetet küldött, az alkalmazás időtúllépési értékkel vagy anélkül hívhatja meg a fogad függvényt. Ha nincs megadva időtúllépési érték, a rendszer az alapértelmezett időtúllépést használja. Ez egy VisszajelzésBatch objektumot ad vissza, amely megvizsgálható üzenetkézbesítési visszajelzési tulajdonságokat tartalmaz.

Ez a példa létrehozza a FeedbackBatch fogadót, meghívja a getEnqueuedTimeUtc függvényt, és kinyomtatja az üzenet beérkezési idejét.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

Az SDK üzenetmintákat küld

Két üzenetminta van:

Szolgáltatásügyfél-minta – Üzenetküldési példa, #1.
Szolgáltatásügyfél-minta – Üzenetküldési példa, #2.

Eszközalkalmazás létrehozása

Ez a szakasz a felhőből az eszközre irányuló üzenetek fogadását ismerteti.

Az IoTHubDeviceClient osztály olyan módszereket tartalmaz, amellyel szinkron kapcsolatot hozhat létre egy eszközről egy Azure IoT Hubra, és üzeneteket fogadhat az IoT Hubról.

Az azure-iot-device kódtárat telepíteni kell az eszközalkalmazások létrehozásához.

pip install azure-iot-device

Ahhoz, hogy egy Python-alapú eszközalkalmazás fogadhassa a felhőből az eszközre irányuló üzeneteket, csatlakoznia kell az IoT Hubhoz, majd be kell állítania egy visszahívási üzenetkezelőt az IoT Hubról érkező bejövő üzenetek feldolgozásához.

Eszközimportálási utasítás

Adja hozzá ezt a kódot a függvények IoTHubDeviceClient azure.iot.device SDK-ból való importálásához.

from azure.iot.device import IoTHubDeviceClient

Eszköz csatlakoztatása az IoT Hubhoz

Az eszközalkalmazások az alábbi módszerekkel végezhetnek hitelesítést az IoT Hubon:

Megosztott hozzáférési kulcs
X.509-tanúsítvány

Fontos

Hitelesítés megosztott hozzáférési kulccsal

Eszköz csatlakoztatása az IoT Hubhoz:

Az eszköz elsődleges kapcsolati sztringjének hozzáadásához hívja meg a create_from_connection_string funkciót.
Hívja meg a connect-et a kliens eszköz csatlakoztatásához.

Példa:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Hitelesítés X.509-tanúsítvánnyal

Eszköz csatlakoztatása az IoT Hubhoz X.509-tanúsítvány használatával:

Az X.509-tanúsítványparaméterek hozzáadása a create_from_x509_certificate használatával
Hívja a connect-et az eszköz kliens csatlakoztatásához

Ez a példa a tanúsítvány bemeneti paraméterértékeit mutatja be helyi változóként az egyértelműség érdekében. Éles rendszerben a bizalmas bemeneti paramétereket környezeti változókban vagy más biztonságosabb tárolási helyen tárolhatja. Például használja a os.getenv("HOSTNAME")-t a gazdagépnév környezeti változójának olvasásához.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

További információ a tanúsítványhitelesítésről:

Kódminták

Az X.509-tanúsítványhitelesítés működő mintáit az Async Hub-forgatókönyvekben az x509-ben végződő fájlnevek példáiban tekinti meg.

Újracsatlakozás kezelése

IoTHubDeviceClient alapértelmezés szerint megpróbálja újra létrehozni az elvetett kapcsolatot. Az újracsatlakozási viselkedést a IoTHubDeviceClientconnection_retry és connection_retry_interval a paraméterek szabályozzák.

Üzenetkezelő létrehozása

Hozzon létre egy üzenetkezelő függvényt az eszközre érkező bejövő üzenetek feldolgozásához. Ezt a visszahívási on_message_received üzenetkezelő (következő lépés) fogja hozzárendelni.

Ebben a példában a message_handler függvényt akkor hívjuk meg, amikor egy üzenet érkezik. Az üzenettulajdonságok (.items) egy ciklus használatával kerülnek kinyomtatásra a konzolra.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Az üzenetkezelő hozzárendelése

Az üzenetkezelő metódus hozzárendeléséhez használja a on_message_received metódust.

Ebben a példában egy elnevezett message_handler üzenetkezelő metódus van csatolva az IoTHubDeviceClientclient objektumhoz. Az client objektum egy IoT Hubról vár egy felhőből eszközre irányuló üzenet fogadására. Ez a kód legfeljebb 300 másodpercet (5 percet) vár egy üzenetre, vagy a billentyűzetbillentyű lenyomása esetén kilép.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK-üzenetminta fogadása

Üzenet fogadása – Az Azure IoT Hubról egy eszközre küldött felhőbeli (C2D) üzenetek fogadása.

Háttéralkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan küldhet felhőből eszközre üzenetet. A megoldás háttéralkalmazása csatlakozik egy IoT Hubhoz, és az üzeneteket egy céleszközzel kódolt IoT Hubba küldi. Az IoT Hub a bejövő üzeneteket az üzenetsorba tárolja, az üzenetek pedig az IoT Hub üzenetsorából érkeznek a céleszközre.

Az IoTHubRegistryManager osztály minden olyan módszert elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a szolgáltatás felhőből eszközre irányuló üzeneteivel való interakcióhoz. A háttérszolgáltatás-alkalmazások létrehozásához telepíteni kell az azure-iot-hub kódtárat.

pip install azure-iot-hub

Az IoTHubRegistryManager objektum importálása

Adja hozzá a következő import utasítást. Az IoTHubRegistryManager api-kat tartalmaz az IoT Hub Registry Manager-műveletekhez.

from azure.iot.hub import IoTHubRegistryManager

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozzon az IoT Hubhoz from_connection_string használatával.

Példa:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Titkos ügyfélkód
Tanúsítvány
Federált identitás hitelesítő adat

A Microsoft Entra-alkalmazások beállításáról további információt a Gyorsútmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon című részben találhat.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra megköveteli ezeket a NuGet-csomagokat és a hozzájuk tartozó using utasításokat:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Az eredményül kapott TokenCredential ezután átadható egy IoT Hub-metódushoz való csatlakozásnak minden olyan SDK-ügyfél esetében, amely elfogadja a Microsoft Entra hitelesítő adatait:

Ebben a példában a TokenCredential átadásra kerül a ServiceClient.Create számára, hogy létrehozzon egy ServiceClient kapcsolati objektumot.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Ebben a példában a TokenCredentialRegistryManager.Create-hoz kerül átadásra, hogy létrehozzon egy RegistryManager objektumot.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Kódrészlet

A Microsoft Entra szolgáltatáshitelesítés működő mintájáért tekintse meg a szerepköralapú hitelesítési mintát.

Üzenet létrehozása és küldése

A send_c2d_message használatával üzenetet küldhet a felhőben (IoT Hub) az eszközre.

send_c2d_message a következő paramétereket használja:

deviceID - A céleszköz sztringazonosítója.
message - A felhőből az eszközre irányuló üzenet. Az üzenet típusa str (sztring).
properties- Választható típusú tulajdonságok dictgyűjteménye. A tulajdonságok alkalmazástulajdonságokat és rendszertulajdonságokat tartalmazhatnak. Az alapértelmezett érték {}.

Ez a példa egy tesztüzenetet küld a céleszköznek.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK-üzenetküldési példa

A Pythonhoz készült Azure IoT SDK egy szolgáltatásalkalmazás működő mintáját biztosítja, amely bemutatja, hogyan küldhet felhőből eszközre üzenetet. További információ: send_message.py bemutatja, hogyan küldhet felhőből eszközre üzenetet.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan fogadhat felhőből eszközre irányuló üzeneteket az Azure IoT SDK azure-ioT SDK-ban Node.js használatával.

Ahhoz, hogy egy Node.js-alapú eszközalkalmazás fogadhassa a felhőből az eszközre irányuló üzeneteket, csatlakoznia kell az IoT Hubhoz, majd be kell állítania egy visszahívási figyelőt és üzenetkezelőt az IoT Hubról érkező bejövő üzenetek feldolgozásához. Az eszközalkalmazásnak képesnek kell lennie a leválasztások észlelésére és kezelésére is, ha az eszköz–IoT Hub üzenetkapcsolat megszakad.

SDK-csomagok telepítése

Az azure-iot-device csomag olyan objektumokat tartalmaz, amelyek IoT-eszközökhöz illesztenek. Futtassa ezt a parancsot az azure-iot-device SDK telepítéséhez a fejlesztői gépen:

npm install azure-iot-device --save

Eszköz csatlakoztatása az IoT Hubhoz

Az eszközalkalmazások az alábbi módszerekkel végezhetnek hitelesítést az IoT Hubon:

X.509-tanúsítvány
Megosztott hozzáférési kulcs

Fontos

Hitelesítés X.509-tanúsítvánnyal

Az X.509-tanúsítvány az eszköz–IoT Hub kapcsolatátvitelhez van csatolva.

Eszköz–IoT Hub kapcsolat konfigurálása X.509-tanúsítvány használatával:

fromConnectionString hívásával adja hozzá az eszköz- vagy identitásmodul kapcsolati karakterláncát, valamint az átviteli típust az Client objektumhoz. Adja hozzá x509=true a kapcsolati sztringhez annak jelzésére, hogy egy tanúsítvány van hozzáadva DeviceClientOptions. Példa:
- Eszköz kapcsolati karaktersor:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Az identitásmodul kapcsolat karakterlánc:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Konfiguráljon egy JSON-változót tanúsítványadatokkal, és adja át a DeviceClientOptionsnak.
Hívja meg a setOptionst , hogy adjon hozzá egy X.509-tanúsítványt és kulcsot (és opcionálisan jelszót) az ügyfélátvitelhez.
Hívja meg a open parancsot az eszköz és az IoT Hub közötti kapcsolat megnyitásához.

Ez a példa egy JSON-változó tanúsítványkonfigurációs adatait mutatja be. A tanúsítványkonfigurációkat clientOptionssetOptions átadják, és a kapcsolat open használatával nyílik meg.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

További információ a tanúsítványhitelesítésről:

Kódrészlet

Az X.509-tanúsítványhitelesítés működő mintájáért tekintse meg az X.509 egyszerű mintaeszközt.

Hitelesítés megosztott hozzáférési kulccsal

Átviteli protokoll kiválasztása

Az Client objektum a következő protokollokat támogatja:

Amqp
Http - A Http használata esetén a Client példány ritkán (legalább 25 percenként) ellenőrzi az IoT Hubtól érkező üzeneteket.
Mqtt
MqttWs
AmqpWs

Telepítse a szükséges átviteli protokollokat a fejlesztői gépen.

Ez a parancs például telepíti a protokollt Amqp :

npm install azure-iot-device-amqp --save

Az MQTT, az AMQP és a HTTPS-támogatás közötti különbségekről további információt a felhőalapú kommunikációs útmutatóban és a Kommunikációs protokoll kiválasztása című témakörben talál.

Ez a példa az AMQP protokollt egy Protocol változóhoz rendeli. Ezt a protokollváltozót a Client.fromConnectionString cikk Kapcsolati sztring hozzáadása szakaszában adja át a metódusnak.

const Protocol = require('azure-iot-device-mqtt').Amqp;

Üzenetkiegészítési, elutasítási és lemondási képességek

Az üzenetkiegészítési, elutasítási és lemondási módszerek a választott protokolltól függően használhatók.

AMQP és HTTP

Az AMQP- és HTTP-átvitelek befejezhetnek, elutasíthatnak vagy elhagyhatnak egy üzenetet:

Kész – Az üzenet befejezéséhez a felhőből az eszközre üzenetet küldő szolgáltatás értesítést kap az üzenet fogadásáról. Az IoT Hub eltávolítja az üzenetet az üzenetsorból. A metódus a következő formáját veszi fel client.complete(message, callback function): .
Elutasítás – Az üzenet elutasításához a felhőből az eszközre üzenetet küldő szolgáltatás értesítést kap arról, hogy az üzenetet nem dolgozza fel az eszköz. Az IoT Hub véglegesen eltávolítja az üzenetet az eszközsorból. A metódus a következő formáját veszi fel client.reject(message, callback function): .
Elhagyás – Ha fel szeretne hagyni egy üzenetet, az IoT Hub azonnal megpróbálja újra elküldeni. Az IoT Hub megőrzi az üzenetet az eszközsorban a jövőbeli felhasználás céljából. A metódus a következő formáját veszi fel client.abandon(message, callback function): .

MQTT

Az MQTT nem támogatja az üzenetek kiegészítését, elutasítását vagy elhagyását. Ehelyett az MQTT alapértelmezés szerint elfogad egy üzenetet, és az üzenet el lesz távolítva az IoT Hub üzenetsorából.

Újrakézbesítési kísérletek

Ügyfélobjektum létrehozása

Hozzon létre egy objektumot Client a telepített csomag használatával.

Példa:

const Client = require('azure-iot-device').Client;

Protokollobjektum létrehozása

Objektum létrehozása Protocol telepített átviteli csomag használatával.

Ez a példa az AMQP protokollt rendeli hozzá:

const Protocol = require('azure-iot-device-amqp').Amqp;

Az eszköz kapcsolati sztring és átviteli protokolljának hozzáadása

Hívja meg a fromConnectionString függvényt az eszközkapcsolati paraméterek megadásához:

connStr – Az eszköz kapcsolati sztring.
transportCtor – A szállítási protokoll.

Ez a példa az átviteli protokollt Amqp használja:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Bejövő üzenetkezelő létrehozása

A rendszer minden bejövő üzenethez meghívja az üzenetkezelőt.

Az üzenet sikeres fogadása után, ha AMQP- vagy HTTP-átvitelt használ, hívja meg a metódust, hogy tájékoztassa az client.complete IoT Hubot arról, hogy az üzenet eltávolítható az üzenetsorból.

Ez az üzenetkezelő például kinyomtatja az üzenetazonosítót és az üzenettörzset a konzolon, majd meghívja a client.complete függvényt, hogy értesítse az IoT Hubot arról, hogy feldolgozta az üzenetet, így az biztonságosan eltávolítható a készüléksorából. Az complete hívás nem szükséges, ha az MQTT-átvitelt használja, és kihagyható. Az AMQP- vagy HTTPS-átvitelhez híváscomplete szükséges.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Kapcsolatleválasztási kezelő létrehozása

A kapcsolat megszakadásakor a rendszer meghívja a kapcsolatleválasztási kezelőt. A kapcsolatleválasztási kezelő hasznos az újracsatlakozási kód implementálásakor.

Ez a példa elkapja és megjeleníti a leválasztási hibaüzenetet a konzolon.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Eseményfigyelők hozzáadása

Ezeket az eseményfigyelőket a .on metódussal adhatja meg.

Kapcsolatkezelő
Hibakezelő
Leválasztási kezelő
Üzenetkezelő

Ez a példa tartalmazza a korábban definiált üzenet- és kapcsolatleválasztási kezelőket.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

Az IoT Hubhoz való kapcsolat megnyitása

A nyitott metódussal megnyithat egy kapcsolatot egy IoT-eszköz és az IoT Hub között. Hiba és híváskezelő kód befogására használható .catch(err) .

Példa:

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

SDK-eszközminták

A Node.js-hez készült Azure IoT SDK egy olyan eszközalkalmazás működő mintáját biztosítja, amely kezeli az üzenetek fogadását. További információk:

simple_sample_device – Az IoT Hubhoz csatlakozó és felhőből eszközre irányuló üzeneteket fogadó eszközalkalmazás.

Háttéralkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan küldhet felhőből eszközre üzenetet. Ahogy korábban említettem, egy megoldás háttéralkalmazása csatlakozik egy IoT Hubhoz, és üzeneteket küld a céleszközzel kódolt IoT Hubnak. Az IoT Hub a bejövő üzeneteket az üzenetsorba tárolja, az üzenetek pedig az IoT Hub üzenetsorából érkeznek a céleszközre.

A megoldás háttéralkalmazásai az üzenetsoron keresztül az eszközkézbesítésre szánt IoT Hubnak küldött üzenet kézbesítési visszajelzését is kérhetik és fogadhatják.

Szolgáltatás SDK-csomag telepítése

Az Azure-iotHub-csomag olyan objektumokat tartalmaz, amelyek az IoT Hubhoz illesztenek. Ez a cikk azokat az osztálykódot ismerteti Client , amelyek egy alkalmazásból üzenetet küldenek egy eszköznek az IoT Hubon keresztül.

Futtassa ezt a parancsot az Azure-iotHub fejlesztői gépen való telepítéséhez:

npm install azure-iothub --save

Az ügyfél- és üzenetmodulok betöltése

Deklaráljon egy Client objektumot a Client csomag azure-iothub osztályával.

Deklaráljon egy Message objektumot a Message csomag azure-iot-common osztályával.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Csatlakozás megosztott hozzáférési szabályzattal

A fromConnectionString használatával csatlakozhat az IoT Hubhoz.

Ebben a példában az objektum az serviceClient átviteli típussal Amqp jön létre.

var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Az ügyfélkapcsolat megnyitása

Hívja meg a Clientnyitott metódust egy alkalmazás és az IoT Hub közötti kapcsolat megnyitásához.

open meghívható egy visszahívási függvény megadásával vagy anélkül, amelyet a open művelet befejezésekor hívunk meg.

Ebben a példában a open metódus tartalmaz egy választható err nyitott kapcsolat visszahívási függvényt. Nyitott hiba esetén a függvény egy hibaobjektumot ad vissza. Ha a nyitott kapcsolat sikeres, a rendszer visszahívási null értéket ad vissza.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

Csatlakozás a Microsoft Entra használatával

A Node.js SDK autentikáció áttekintése:

A Microsoft Entra alkalmazás konfigurálása

Titkos ügyfélkód
Tanúsítvány
Federált identitás hitelesítő adat

A Microsoft Entra-alkalmazások beállításáról további információt a Gyorsútmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon című részben találhat.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbb módja egy háttéralkalmazás hitelesítésének a DefaultAzureCredential használata, de ajánlott egy másik módszert választani éles környezetben, beleértve egy adott TokenCredential vagy egyszerűsített ChainedTokenCredential metódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a JavaScripthez készült Azure Identity ügyfélkódtár hitelesítőadat-láncai című témakörben talál .

A Microsoft Entra a következő csomagot igényli:

npm install --save @azure/identity

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosítóját hozzáadtuk a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat hitelesítő adat, amelyet továbbítanak egy IoT Hub-kapcsolati módszerhez.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Az eredményül kapott hitelesítő jogkivonat ezután átadható a FromTokenCredential-nak , hogy csatlakozzon az IoT Hubhoz minden olyan SDK-ügyfélhez, amely elfogadja a Microsoft Entra hitelesítő adatait:

fromTokenCredential két paramétert igényel:

Az Azure-szolgáltatás URL-címe – Az Azure-szolgáltatás URL-címének előtag nélküli {Your Entra domain URL}.azure-devices.net formátumban https:// kell lennie. Például: MyAzureDomain.azure-devices.net.
Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure-hitelesítő adatok a következővel szerezhetők meg: DefaultAzureCredential. A rendszer ezután az Azure-tartomány URL-címét és hitelesítő adatait adja meg Registry.fromTokenCredential az IoT Hubhoz való kapcsolat létrehozásához.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáit az Azure-identitásra vonatkozó példákban talál.

Üzenet létrehozása

Az üzenetobjektum tartalmazza az aszinkron felhőből eszközre irányuló üzenetet. Az üzenetfunkció ugyanúgy működik az AMQP, az MQTT és a HTTP protokollon keresztül.

Az üzenetobjektum számos tulajdonságot támogat, köztük ezeket a tulajdonságokat is. A teljes lista üzenettulajdonságainak megtekintése.

ack - Kézbesítési visszajelzés. A következő szakaszban ismertetjük.
properties - Olyan térkép, amely sztringkulcsokat és értékeket tartalmaz az egyéni üzenettulajdonságok tárolásához.
messageId – Kétirányú kommunikáció korrelációja.

Amikor az üzenetobjektumot példányosítja, adja hozzá az üzenet szövegtörzsét. Ebben a példában egy 'Cloud to device message.' üzenet jelenik meg.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Kézbesítés visszaigazolása

Minden üzenetnek, amely visszajelzést szeretne kapni, tartalmaznia kell egy értéket a kézbesítés visszaigazolása ack tulajdonsághoz. A ack tulajdonság az alábbi értékek egyike lehet:

nincs (alapértelmezett): nincs visszajelzési üzenet.
sent: visszajelzést kap, ha az üzenet befejeződött.
: visszajelzést kap, ha az üzenet lejárt (vagy elérte a maximális kézbesítési számot) anélkül, hogy az eszköz befejezte volna.
full: visszajelzés az elküldött és nem elküldött eredményekről.

Ebben a példában a ack tulajdonság a következőre full van állítva, ami azt kéri, hogy legyen visszajelzés mind a küldött, mind a nem küldött üzenetek kézbesítéséről egy üzenet esetében.

message.ack = 'full';

Az üzenetvisszajelzés fogadójának csatolása

Az üzenetvisszajelzés fogadójának visszahívási függvénye a Client getFeedbackReceiver használatával van összekapcsolva.

Az üzenetvisszajelzés fogadója két argumentumot kap:

Hibaobjektum (null értékű lehet)
AmqpReceiver objektum – Eseményeket bocsát ki, amikor az ügyfél új visszajelzési üzeneteket kap.

Ez a példafüggvény egy kézbesítési visszajelzési üzenetet fogad, és azt ki is nyomtatja a konzolon.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Ez a kód összekapcsolja a receiveFeedback visszajelzési visszahívási függvényt a Client szolgáltatás objektummal a getFeedbackReceiver használatával.

serviceClient.getFeedbackReceiver(receiveFeedback);

Üzenet befejezési eredményfeldolgozó definiálása

Az üzenetküldés befejező visszahívási függvénye az egyes üzenetek elküldése után lesz meghívva.

Ez a példafüggvény az üzenetművelet send eredményeit a konzolra nyomtatja. Ebben a példában a printResultFor függvény paraméterként lesz megadva a send következő szakaszban leírt függvénynek.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Üzenet küldése

A küldési függvény használatával aszinkron felhőből eszközre irányuló üzenetet küldhet az eszközalkalmazásnak az IoT Hubon keresztül.

send a következő paramétereket támogatja:

deviceID – A céleszköz eszközazonosítója.
üzenet – Az eszközre küldendő üzenet törzse.
kész – A művelet befejezésekor meghívandó opcionális függvény. A Done függvény két argumentummal lett meghívva:
- Hibaobjektum (ami lehet null értékű).
- a naplózáshoz vagy hibakereséshez hasznos átvitelspecifikus válaszobjektum.

Ez a kód meghívja send , hogy küldjön egy felhőből eszközre irányuló üzenetet az eszközalkalmazásnak az IoT Hubon keresztül. Az előző szakaszban definiált visszahívási függvény printResultFor megkapja a kézbesítés visszaigazolási adatait.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

Ez a példa bemutatja, hogyan küldhet üzenetet az eszköznek, és hogyan kezelheti a visszajelzési üzenetet, amikor az eszköz nyugtázza a felhőből az eszközre irányuló üzenetet:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

SDK-üzenetküldési példa

A Node.js-hez készült Azure IoT SDK az üzenetküldési feladatokat kezelő szolgáltatásalkalmazás munkamintáit tartalmazza. További információk:

send_c2d_message.js – C2D-üzenetek küldése egy eszközre az IoT Hubon keresztül.

Kapcsolat újracsatlakozási szabályzata

Ez a cikk nem mutatja be az eszköz újrapróbálkozási szabályzatát az IoT Hub-kapcsolatra vagy az IoT Hub-kapcsolat külső alkalmazására vonatkozóan. Az éles kódban a kapcsolat újrapróbálkozási szabályzatait az eszközök újracsatlakozásának kezelése című cikkben leírtak szerint kell implementálnia, hogy rugalmas alkalmazásokat hozhasson létre.

Üzenetmegőrzési idő, újrapróbálkozási kísérletek és a kézbesítések maximális száma

A felhőalapú üzenetek küldése az IoT Hubról című cikkben leírtak szerint az alábbi üzenetértékek alapértelmezett értékeit tekintheti meg és konfigurálhatja a portál IoT Hub konfigurációs beállításai vagy az Azure CLI használatával. Ezek a konfigurációs beállítások hatással lehetnek az üzenetek kézbesítésére és a visszajelzésre.

Alapértelmezett TTL (élettartam) – Az az időtartam, amíg egy eszköz felhasználhat egy üzenetet, mielőtt azt az IoT Hub lejárttá nyilvánítja.
Visszajelzések megőrzési ideje – Az IoT Hub mennyi ideig őrzi meg a visszajelzést a felhőből az eszközre irányuló üzenetek lejáratához vagy kézbesítéséhez.
Az IoT Hub hányszor kísérel meg felhőből eszközre üzenetet továbbítani egy eszközre.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-01-06

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

Felhőből eszközre irányuló üzenetek küldése és fogadása

Áttekintés

Az üzenetsor ismertetése

Eszközalkalmazás létrehozása

Szükséges eszköz NuGet-csomag

Eszköz csatlakoztatása az IoT Hubhoz

Hitelesítés megosztott hozzáférési kulccsal

Hitelesítés X.509-tanúsítvánnyal

Kódminták

Visszahívás

ciklikus lekérdezések

CompleteAsync metódus

Üzenet elhagyása, elutasítása vagy időtúllépés

Lekérdezési ciklus

Az üzenet újrapróbálkozási szabályzatának fogadása

SDK-üzenetminta fogadása

Háttéralkalmazás létrehozása

Szolgáltatás NuGet-csomag hozzáadása

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Kódrészlet

Aszinkron felhőből eszközre irányuló üzenet küldése

Kézbesítési visszajelzések fogadása

A feedbackReceiver objektum létrehozása

Üzenetek küldése az Ack paraméterrel

Várjon, amíg visszajelzést kap

Szolgáltatásügyfél újracsatlakoztatása

Üzenet újrapróbálkozési szabályzatának küldése

SDK-üzenetküldési példa

Eszközalkalmazás létrehozása

Azure IoT Java SDK-kódtárak importálása

Eszköz csatlakoztatása az IoT Hubhoz

Hitelesítés megosztott hozzáférési kulccsal

Hitelesítés X.509-tanúsítvánnyal

Kódminták

Az üzenetvisszahívási módszer beállítása

Üzenetvisszahívás-kezelő létrehozása

Az üzenet elhagyási és elutasítási lehetőségei

Az üzenetállapot visszahívási módszerének létrehozása

Az eszköz és az IoT Hub közötti kapcsolat megnyitása

SDK-üzenetminta fogadása

Háttéralkalmazás létrehozása

A függőségi utasítás hozzáadása

Importálási utasítások hozzáadása

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

A kapcsolati protokoll definiálása

A ServiceClient objektum létrehozása

Az alkalmazás és az IoT Hub közötti kapcsolat megnyitása

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Hitelesítés a ClientSecretCredentialBuilder használatával

Egyéb hitelesítési osztályok

Kódminták

Visszajelzés-fogadó megnyitása üzenetkézbesítési visszajelzésekhez

Üzenettulajdonságok hozzáadása

Aszinkron üzenet létrehozása és küldése

Üzenetkézbesítési visszajelzések fogadása

Az SDK üzenetmintákat küld

Eszközalkalmazás létrehozása

Eszközimportálási utasítás

Eszköz csatlakoztatása az IoT Hubhoz

Hitelesítés megosztott hozzáférési kulccsal

Hitelesítés X.509-tanúsítvánnyal

Kódminták

Újracsatlakozás kezelése

Üzenetkezelő létrehozása

Az üzenetkezelő hozzárendelése

SDK-üzenetminta fogadása

Háttéralkalmazás létrehozása

Az IoTHubRegistryManager objektum importálása

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása