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

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 kódhurok (például hurokwhile) for 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

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 sztring és eszközazonosítóját DeviceClient a 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 - A különböző átviteli beállítások DeviceClientModuleClientmeghatározására használt interfész és . 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 az átviteli protokoll használatával csatlakozik egy Mqtt 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:

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

2. 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 a gazdagépnév környezeti változójának olvasására használható Environment.GetEnvironmentVariable("HOSTNAME") .

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:

• Identitások hitelesítése X.509-tanúsítványokkal
• Oktatóanyag: Tanúsítványok létrehozása és feltöltése teszteléshez

Kódminták

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

• Csatlakozás X.509-tanúsítvánnyal
• DeviceClientX509AuthenticationE2ETests
• Irányított projekt – IoT-eszközök biztonságos és nagy léptékű kiépítése az IoT Hub Device Provisioning Service-vel

Visszahívási

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.

ReceiveAsync Az alábbi űrlapokat hívhatja meg:

• 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özsorból egy lemondási jogkivonat 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. Ha további HTTP 1-et ad ki, az IoT Hub szabályozza 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ése

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

• A AbandonAsync meghívásával hagyjon fel egy ü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.

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.

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 időtúllépési értékkel vagy alapértelmezett időtúllépéssel használja ReceiveAsync , a ciklusban minden hívás ReceiveAsync 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 ReceiveAsync át kell adni a CompleteAsyncnek. 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 ();
}

Ü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

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 jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. 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
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. 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 rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetó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ő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

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:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Ebben a példában a TokenCredential serviceClient kapcsolati objektum létrehozásához szükséges átadás ServiceClient.Create történik.

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

Ebben a példában a rendszer átadja a TokenCredential RegistryManager objektum létrehozásához.RegistryManager.Create

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

Kódminta

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 - Nem kötelező 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 informatika, újrapróbálkozás 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 a kettőről, mind Positive 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áljon egy 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érnull, ReceiveAsync é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. Egy hívás törli CompleteAsync a megadott elküldött üzenetet az üzenetsorból a Task paraméter alapján.
• Szükség esetén a fogadási kód meghívhatja a AbandonAsync-et , hogy küldjön üzenetet 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ás/kvóta túllépte a kivételt, figyelje és/vagy módosítsa a kérések küldésének gyakoriságát, vagy frissítse a központi 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 minta

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

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 sztring. 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 elutasí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:

1. Hozza létre az SSLContext objektumot a buildSSLContext használatával.
2. Adja hozzá az SSLContext adatokat egy ClientOptions-objektumhoz .
3. 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:

• Identitások hitelesítése X.509-tanúsítványokkal
• Oktatóanyag: Tanúsítványok létrehozása és feltöltése teszteléshez

Kódminták

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

• Küldési-fogadási x509-minta
• Esemény küldése x509

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. nullLehet .
• context - Nem kötelező típusú objectkörnyezet. Ha nincs meghatározva, használja null .

Ebben a példában a rendszer egy callback környezeti paraméter nélküli metódust MessageCallback ad át a rendszer.setMessageCallback

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 érkező nagyszámú bejövő üzenetet sikeresen kell fogadni, és ennek eredménye IotHubMessageResult.COMPLETElehet, előfordulhat, hogy fel kell hagynia vagy el kell utasítania 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 üzenetben. Az IoT Hub újra lekérdezi, és később újra elküldi.
  • IotHubMessageResult.REJECT üzenetben. Az IoT Hub nem kérdezi le újra az üzenetet, és véglegesen eltávolítja az üzenetet az üzenetsorból.
• Az ügyfelek üzeneteket használnakMQTT, vagy MQTT_WS nem tudnak vagy REJECT nemABANDON.

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.

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.

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 rendszer a kapcsolat állapotváltozásának visszahívási módszereké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 connectionStatusChangeContext.getCause() meg 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

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 az enumerálást AMQPSAMQPS_WS fogadja el.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

A ServiceClient objektum létrehozása

Hozza létre a ServiceClient objektumot, amely biztosítja az Iot Hub kapcsolati sztring és a protokollt.

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 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 jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. 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 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

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
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. 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 rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetó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 létrehozás után adja át a TokenCredential ServiceClientnek vagy más szerkesztőnek 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 jogkivonat hitelesítő adatai, amelyet a rendszer átad egy konstruktornak, például a ServiceClientnek.

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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

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

A FeedbackReceiver használatával üzenetet küldhet az IoT Hubnak. Az A FeedbackReceiver egy speciális fogadó, amelynek Receive metódusa egy helyett Messageegy FeedbackBatch .

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.

A setDeliveryAcknowledgement használatával kérheti, hogy kézbesítve vagy ne kézbesítve legyen az IoT Hub üzenetsorának nyugtázása. Ebben a példában a kért nyugtázás kézbesítve vagy Fullnem 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ást . 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 fogadót és meghívja a FeedbackBatch getEnqueuedTimeUtc-t, és kinyomtatja az üzenet lekéréses 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

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

Eszköz csatlakoztatása az IoT Hubhoz:

1. Hívja meg create_from_connection_string az eszköz elsődleges kapcsolati sztring hozzáadásához.
2. Csatlakozás hívása az eszközügyfél 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:

1. Az X.509-tanúsítványparaméterek hozzáadása a create_from_x509_certificate használatával
2. Csatlakozás hívása az eszközügyfél 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 a gazdagépnév környezeti változójának olvasására használható os.getenv("HOSTNAME") .

# 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:

• Identitások hitelesítése X.509-tanúsítványokkal
• Oktatóanyag: Tanúsítványok létrehozása és feltöltése teszteléshez

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 message_handler üzenet érkezésekor hívjuk meg. Az üzenettulajdonságok (.items) hurkot használva kerülnek 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

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 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 jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. 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
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. 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 rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetó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ő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

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:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Ebben a példában a TokenCredential serviceClient kapcsolati objektum létrehozásához szükséges átadás ServiceClient.Create történik.

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

Ebben a példában a rendszer átadja a TokenCredential RegistryManager objektum létrehozásához.RegistryManager.Create

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

Kódminta

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 minta

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

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:

1. AConnectionString hívásával adja hozzá az eszköz- vagy identitásmodul kapcsolati sztring, és adja hozzá az Client objektum átviteli típusát. Adja hozzá x509=true a kapcsolati sztring, hogy jelezze, hogy a rendszer tanúsítványt ad hozzáDeviceClientOptions. Példa:

   • Eszköz kapcsolati sztring:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • Identitásmodul kapcsolati sztring:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. Konfiguráljon egy JSON-változót tanúsítványadatokkal, és adja át a DeviceClientOptionsnak.

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

4. Nyissa meg a hívást 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 rendszer átadja a tanúsítványkonfigurációt clientOptionssetOptions, és a kapcsolat a következő használatával opennyí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:

• Identitások hitelesítése X.509-tanúsítványokkal
• Tanúsítványok létrehozása és feltöltése teszteléshez

Kódminta

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 - Használat Httpesetén a példány ritkán (legalább 25 percenként) ellenőrzi az Client 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.

Újramegfeleltetési kísérletek

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.

Ü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ívás aConnectionStringtől 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 felhívja client.complete az IoT Hubot, hogy feldolgozta az üzenetet, és biztonságosan eltávolítható az eszközsorból. Az MQTT-átvitel használata esetén a hívás complete nem szükséges, é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 a konzol leválasztási hibaüzenetét jeleníti meg és jeleníti meg.

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 osztályával azure-iothub .

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

'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

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 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 jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. 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.

Az SDK-hitelesítés Node.js áttekintése:

• A felhasználói hitelesítés első lépései az Azure-ban
• Azure Identity-ügyfélkódtár JavaScripthez

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
• Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. 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 rövid útmutatóban talál: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetó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 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 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ő adatai, amelyet egy IoT Hub-kapcsolati módszernek ad át.

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:

• Registry
• Ügyfél
• JobClient

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 https:// formátumban {Your Entra domain URL}.azure-devices.net kell lennie. Például: MyAzureDomain.azure-devices.net.
• Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure-hitelesítő adatokat a rendszer a használatával szerzi be 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.

Adja hozzá az üzenet törzsét az üzenetobjektum példányosításakor. 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

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 informatika, újrapróbálkozás 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.

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 fullvan állítva, hogy egyszerre küldjön és ne küldjön üzenetkézbesítési visszajelzést egy üzenethez.

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 kézbesítési visszajelzési üzenetet fogad és nyomtat ki 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 szolgáltatásobjektummal Client a használatával getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Üzenetkiegészítési eredménykezelő 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 Kész függvény két argumentummal van meghívva:
  • Hibaobjektum (lehet null).
  • 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 minta

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.