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

Ismerkedés az eszközfelügyelettel

  • Cikk

A háttéralkalmazások az Azure IoT Hub primitívjei, például az ikereszközök és a közvetlen metódusok használatával távolról indíthatják el és figyelhetik az eszközfelügyeleti műveleteket az eszközökön.

Egy háttéralkalmazás közvetlen metódusával kezdeményezhet eszközfelügyeleti műveleteket, például újraindítást, gyári alaphelyzetbe állítást és belső vezérlőprogram-frissítést.

Az eszköz felelős a következőért:

  • Az IoT Hubról küldött közvetlen metóduskérés kezelése
  • A megfelelő eszközspecifikus művelet kezdeményezése az eszközön
  • Állapotfrissítések biztosítása jelentett tulajdonságokon keresztül az IoT Hubnak

Ez a cikk bemutatja, hogyan működhet együtt egy háttéralkalmazás és egy eszközalkalmazás egy távoli eszközművelet közvetlen módszerrel történő kezdeményezéséhez és monitorozásához.

  • A szolgáltatásalkalmazás közvetlen metódust hív meg egy eszközalkalmazás IoT Hubon keresztüli újraindításához.
  • Az eszközalkalmazás egy közvetlen metódust kezel az eszköz újraindításához.

Feljegyzés

A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.

Feljegyzés

Ez a cikk az ebben a cikkben hivatkozott Azure IoT SDK-minták kiegészítésére szolgál. Az SDK-eszközökkel eszköz- és háttéralkalmazásokat is létrehozhat.

Előfeltételek

  • Egy IoT-központ

  • Regisztrált eszköz

  • Ha az alkalmazás az MQTT protokollt használja, győződjön meg arról, hogy a 8883-es port nyitva van a tűzfalon. Az MQTT protokoll a 8883-es porton keresztül kommunikál. Ez a port néhány vállalati és oktatási hálózati környezetben blokkolható. További információkért és a probléma megoldásának módjaiért lásd: Csatlakozás az IoT Hubhoz (MQTT).

  • Visual Studio-t igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan hozhat létre eszköz- és háttérszolgáltatás-alkalmazáskódot az eszközök közvetlen üzeneteihez az Azure IoT SDK for .NET használatával.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre közvetlen metódushívás-figyelőt eszközalkalmazás-kód használatával.

Szükséges eszköz NuGet-csomagok

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 a kapcsolatbiztonság ajánlott biztonsági eljárásait>.

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

A DeviceClient osztály az eszközről érkező eszközüzenetek használatához szükséges összes metódust elérhetővé teszi.

Csatlakozzon az eszközhöz a CreateFromConnectionString metódussal, valamint az eszköz kapcsolati sztring és a kapcsolat átviteli protokolljával.

A CreateFromConnectionStringTransportType átviteli protokoll paramétere a következő átviteli protokollokat támogatja:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

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:

Kódminták

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

Közvetlen metódus visszahívási figyelőjének létrehozása

A SetMethodHandlerAsync használatával inicializálhat egy közvetlen metódushívás-figyelőt. A figyelő egy metódusnév kulcsszóhoz van társítva, például "újraindítás". A metódus neve egy IoT Hubban vagy háttéralkalmazásban használható a visszahívási metódus aktiválásához az eszközön.

Ez a példa beállít egy visszahívás-figyelőt, amely onReboot aktiválódik az "újraindítás" közvetlen metódus neve meghívásakor.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

A példát folytatva a onReboot visszahívási metódus implementálja a közvetlen metódust az eszközön.

A kezelő függvény meghívja a MethodResponse-t , hogy válasz-visszaigazolást küldjön a hívó alkalmazásnak.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Feljegyzés

Az egyszerűség érdekében ez a cikk nem alkalmaz újrapróbálkozési szabályzatot. Az éles kódban újrapróbálkozási szabályzatokat (például exponenciális visszalépést) kell implementálnia az átmeneti hibakezelésben javasolt módon.

SDK-eszközminták

A .NET-hez készült Azure IoT SDK a közvetlen metódusfeladatokat kezelő eszközalkalmazások munkamintáit tartalmazza. További információk:

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

Ez a szakasz azt ismerteti, hogyan aktiválhat közvetlen metódust egy eszközön.

A ServiceClient osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges ahhoz, hogy közvetlen metódushívásokat küldjön az eszközökre.

Kötelező szolgáltatás NuGet-csomag

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

Adja hozzá ezeket az using utasításokat a szolgáltatástár használatához.

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

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őbiztonság ajánlott biztonsági eljárásait>.

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

Háttéralkalmazás csatlakoztatása a CreateFromConnectionString használatával.

Ha közvetlen metódust szeretne meghívni egy eszközön az IoT Hubon keresztül, a szolgáltatásnak szolgáltatáscsatlakozási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy megosztott hozzáférési szabályzattal jön létre, amely ezt az engedélyt biztosítja.

Paraméterként CreateFromConnectionStringadja meg a szolgáltatás megosztott hozzáférési szabályzatát. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy 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:

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.

Metódus meghívása az eszközön

Metódus meghívása egy eszközön:

  1. Hozzon létre egy CloudToDeviceMethod objektumot. Adja meg az eszköz közvetlen metódusának nevét paraméterként.
  2. Hívja meg az InvokeDeviceMethodAsync parancsot a metódus meghívásához az eszközön.

Ez a példa az "újraindítás" metódust hívja meg, hogy indítsa el az újraindítást az eszközön. Az "újraindítás" metódus a cikk Közvetlen metódus visszahívási figyelőjének létrehozása című szakaszában leírtak szerint van leképezve az eszközön egy figyelőre.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

SDK-szolgáltatásminták

A .NET-hez készült Azure IoT SDK az üzenetfeladatokat kezelő szolgáltatásalkalmazások munkamintáit tartalmazza. További információk:

  • A Java SE fejlesztői készlet 8-at igényel. A JDK 8 letöltéséhez győződjön meg arról, hogy a Hosszú távú támogatás alatt a Java 8-at választja.

Áttekintés

Ez a cikk azt ismerteti, hogyan hozhat létre eszköz- és háttérszolgáltatás-alkalmazáskódot az eszközök közvetlen metódusaihoz az Azure IoT SDK for Java használatával.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre közvetlen metódushívás-figyelőt eszközalkalmazás-kód használatával.

A DeviceClient osztály minden olyan metódust elérhetővé tesz, amely az eszközön található közvetlen metódusok használatához szükséges.

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 a kapcsolatbiztonság ajánlott biztonsági eljárásait>.

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

Az alábbi eszközimportálási utasítások segítségével érheti el a Java-hoz készült Azure IoT SDK-t.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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 a kapcsolatbiztonság ajánlott biztonsági eljárásait>.

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

Eszközhöz való csatlakozás:

  1. Az IotHubClientProtocol használatával válasszon egy átviteli protokollt. Példa:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. DeviceClient A konstruktor használatával adja hozzá az eszköz elsődleges kapcsolati sztring és protokollt.

    String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

  3. Nyissa meg az eszközt az IoT Hubhoz való csatlakozáshoz. Ha az ügyfél már meg van nyitva, a metódus nem tesz semmit.

    client.open(true);

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:

Kódminták

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

Közvetlen metódus visszahívási figyelőjének létrehozása

A subscribeToMethods használatával inicializálhat egy közvetlen metódushívás-figyelőt. subscribeToMethods figyeli a bejövő közvetlen metódusokat, amíg a kapcsolat meg nem szűnik. A metódus neve és hasznos adatai minden közvetlen metódushíváshoz érkeznek.

A figyelőnek meg kell hívnia a DirectMethodResponse-t , hogy metódusválasz-visszaigazolást küldjön a hívó alkalmazásnak.

Például:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Feljegyzés

Az egyszerűség érdekében ez a cikk nem alkalmaz újrapróbálkozési szabályzatot. Az éles kódban újrapróbálkozási szabályzatokat (például exponenciális visszalépést) kell implementálnia az átmeneti hibakezelésben javasolt módon.

SDK-eszközminták

A Java-hoz készült Azure IoT SDK tartalmaz egy működő mintát az eszközalkalmazás ebben a cikkben ismertetett fogalmainak teszteléséhez. További információ: Közvetlen metódusminta.

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

Ez a szakasz azt ismerteti, hogyan kezdeményezhet távoli újraindítást egy eszközön közvetlen módszerrel.

A ServiceClientDeviceMethod osztály olyan metódusokat tartalmaz, amelyekkel a szolgáltatások hozzáférhetnek a közvetlen metódusokhoz.

Szolgáltatásimportálási utasítások

Az alábbi szolgáltatásimportálási utasítások segítségével érheti el a Java-hoz készült Azure IoT SDK-t.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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őbiztonság ajánlott biztonsági eljárásait>.

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

A DeviceMethod konstruktor használatával adja hozzá a szolgáltatás elsődleges kapcsolati sztring, és csatlakozzon az IoT Hubhoz.

Ha közvetlen metódust szeretne meghívni egy eszközön az IoT Hubon keresztül, a szolgáltatásnak szolgáltatáscsatlakozási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy megosztott hozzáférési szabályzattal jön létre, amely ezt az engedélyt biztosítja.

A konstruktor paramétereként DeviceMethod adja meg a szolgáltatás megosztott hozzáférési szabályzatát. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(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 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:

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.

Metódus meghívása az eszközön

A DeviceMethod.invoke meghívásával meghívhat egy metódust egy eszközön, és visszaadhatja az eredmény állapotát.

A invoke hasznos adat paraméter nem kötelező. Akkor használja null , ha nincs megadva hasznos adat. A hasznos adatparaméter különböző adatűrlapokat vehet fel, például sztringet, bájttömböt és HashMapet. Példákat a Közvetlen módszertesztek című témakörben talál.

Ez a példa az "újraindítás" metódust hívja meg, hogy indítsa el az újraindítást az eszközön. Az "újraindítás" metódus a cikk Közvetlen metódus visszahívási figyelőjének létrehozása című szakaszában leírtak szerint van leképezve az eszközön egy figyelőre.

Példa:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

SDK-szolgáltatásminták

A Java-hoz készült Azure IoT SDK a közvetlen metódusfeladatokat kezelő szolgáltatásalkalmazások működő mintáját biztosítja. További információk:

  • Python SDK – A Python 3.7-es vagy újabb verziója ajánlott. Mindenképp a rendszernek megfelelő, 32 vagy 64 bites telepítést használja. Amikor a rendszer erre kéri, mindenképp adja hozzá a Pythont a platformspecifikus környezeti változóhoz.

Áttekintés

Ez a cikk azt ismerteti, hogyan hozhat létre eszköz- és háttérszolgáltatás-alkalmazáskódot a Közvetlen eszközökhöz készült Azure IoT SDK for Python használatával.

Csomagok telepítése

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

pip install azure-iot-device

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

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre közvetlen metódushívás-figyelőt eszközalkalmazás-kód használatával.

Az IoTHubDeviceClient osztály olyan metódusokat tartalmaz, amelyek a közvetlen metódusok használatához használhatók.

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

Adja hozzá ezt az importálási utasítást a hozzáféréshez IoTHubDeviceClient és MethodResponsea .

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Csatlakozás eszközhöz

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 a kapcsolatbiztonság ajánlott biztonsági eljárásait>.

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

Az create_from_connection_string használatával csatlakoztathat egy alkalmazást egy eszközhöz egy eszköz kapcsolati sztring használatával.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

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:

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.

Közvetlen metódus visszahívásának létrehozása

A on_method_request_received használatával hozzon létre egy kezelőfüggvényt vagy coroutint, amelyet közvetlen metódus fogadásakor hív meg. A figyelő egy metódusnév kulcsszóhoz van társítva, például "újraindítás". A metódus neve egy IoT Hubban vagy háttéralkalmazásban használható a visszahívási metódus aktiválásához az eszközön.

A kezelőfüggvénynek létre kell hoznia egy MethodResponse-t, és továbbítania kell azt a send_method_response , hogy közvetlen metódusválasz-visszaigazolást küldjön a hívó alkalmazásnak.

Ez a példa egy közvetlen metóduskezelőt állít be.method_request_handler

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

Ebben a példában a method_request_handler visszahívási metódus implementálja a közvetlen metódust az eszközön. A kód akkor lesz végrehajtva, ha a rendszer meghívja a "rebootDevice" közvetlen metódust egy szolgáltatásalkalmazásból. A metódus meghívja send_method_response a közvetlen metódus válaszának nyugtázását a hívó alkalmazásnak.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

SDK-eszközminták

A Pythonhoz készült Azure IoT SDK egy közvetlen metódusfeladatokat kezelő eszközalkalmazás működő mintáját biztosítja. További információ: Közvetlen fogadási módszer.

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

Ez a szakasz azt ismerteti, hogyan hívhat meg közvetlen metódust egy eszközön egy háttérszolgáltatás-alkalmazással.

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 ahhoz, hogy üzeneteket küldjön egy eszközre.

Szolgáltatásimportálási utasítások

Adja hozzá ezeket az importálási utasításokat az Iot Hubhoz való csatlakozáshoz, a felhőből az eszközre irányuló közvetlen metódusok küldéséhez és az eszköz közvetlen metódusválaszainak fogadásához.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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őbiztonság ajánlott biztonsági eljárásait>.

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

Csatlakozzon az IoT Hubhoz from_connection_string használatával.

Ha közvetlen metódust szeretne meghívni egy eszközön az IoT Hubon keresztül, a szolgáltatásnak szolgáltatáscsatlakozási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy megosztott hozzáférési szabályzattal jön létre, amely ezt az engedélyt biztosítja.

Paraméterként from_connection_stringadja meg a szolgáltatás megosztott hozzáférési szabályzatát. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

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 Python SDK-hitelesítés áttekintését lásd : Python-alkalmazások hitelesítése Az Azure-szolgáltatásokban a Pythonhoz készült Azure SDK használatával

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 PythonHoz 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 megköveteli ezt az importálási csomagot és a megfelelő import utasítást:

pip install azure-identity

from azure.identity import DefaultAzureCredential

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.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Az eredményül kapott AccessToken ezután átadható az from_token_credential IoT Hubhoz való csatlakozáshoz minden olyan SDK-ügyfélhez, amely elfogadja a Microsoft Entra hitelesítő adatait:

from_token_credential 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. Ezután megjelenik IoTHubRegistryManager.from_token_credential az Azure-szolgáltatás URL-címe és hitelesítő adatai az IoT Hubhoz való kapcsolat létrehozásához.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáit a Pythonhoz készült Microsoft Authentication Library (MSAL) című témakörben talál.

Metódus meghívása az eszközön

Az eszközön név alapján hívhat meg közvetlen metódust. A metódus neve azonosítja a metódust. A közvetlen metódus visszahívásának létrehozása című alábbi és előző eszközpéldában a közvetlen metódus neve "rebootDevice".

Közvetlen metódus meghívása egy eszközön:

  1. Hozzon létre egy CloudToDeviceMethod objektumot. Adja meg a metódus nevét és a hasznos adatokat paraméterekként.
  2. Hívja meg invoke_device_method , hogy közvetlen metódust hívjon meg egy eszközön. Adja meg az eszközazonosítót és CloudToDeviceMethod a hasznos adatobjektumot paraméterekként.

Ez a példa meghív CloudToDeviceMethod egy "rebootDevice" nevű közvetlen metódus meghívását egy eszközön. A közvetlen metódus sikeres meghívása után megjelenik a közvetlen metódus válasz hasznos adatai.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

SDK-szolgáltatásminták

A Pythonhoz készült Azure IoT SDK a közvetlen metódusfeladatokat kezelő szolgáltatásalkalmazások munkamintáit biztosítja. További információk:

  • Node.js 10.0.x vagy újabb verziót igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan használható az Azure IoT SDK for Node.js eszköz- és háttérszolgáltatás-alkalmazáskód létrehozására az eszköz közvetlen metódusaihoz.

Eszközalkalmazás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre közvetlen metódusvisszahívást eszközalkalmazás-kód használatával.

SDK-csomag 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

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 a kapcsolatbiztonság ajánlott biztonsági eljárásait>.

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:

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.

Ü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);
Az IoT Hubhoz való kapcsolat megnyitása

Az IoT-eszköz és az IoT Hub közötti kapcsolat megnyitásához használja a nyitott metódust.

Példa:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Közvetlen metódus visszahívásának létrehozása

Hívja meg az onDeviceMethodot , hogy hozzon létre egy visszahíváskezelő függvényt vagy coroutint, amelyet közvetlen metódus fogadásakor hív meg. A figyelő egy metódusnév kulcsszóhoz van társítva, például "újraindítás". A metódus neve egy IoT Hubban vagy háttéralkalmazásban használható a visszahívási metódus aktiválásához az eszközön.

A visszahíváskezelő függvénynek meg kell hívnia response.send , hogy válasz-nyugtázási üzenetet küldjön a hívó alkalmazásnak.

Ez a példa egy közvetlen metóduskezelőt állít be, amelynek neve onReboot az "újraindítás" közvetlen metódusnév használatakor lesz meghívva.

client.onDeviceMethod('reboot', onReboot);

Ebben a példában a onReboot visszahívási metódus implementálja a közvetlen metódust az eszközön. A kód akkor lesz végrehajtva, ha az "újraindítás" közvetlen metódust meghívják egy szolgáltatásalkalmazásból. A függvény meghívja response.send , hogy válasz-nyugtázási üzenetet küldjön a hívó alkalmazásnak.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

SDK-eszközminták

Az Azure IoT SDK for Node.js az eszközfelügyeleti feladatokat kezelő eszközalkalmazások munkamintáit tartalmazza. További információk:

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

Ez a szakasz azt ismerteti, hogyan hívhat meg közvetlen metódust egy eszközön.

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

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

npm install azure-iothub --save

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őbiztonság ajánlott biztonsági eljárásait>.

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

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

Ha közvetlen metódust szeretne meghívni egy eszközön az IoT Hubon keresztül, a szolgáltatásnak szolgáltatáscsatlakozási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy megosztott hozzáférési szabályzattal jön létre, amely ezt az engedélyt biztosítja.

Paraméterként CreateFromConnectionStringadja meg a szolgáltatás megosztott hozzáférési szabályzatát kapcsolati sztring. A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(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.

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

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:

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.

Metódus meghívása az eszközön

Az invokeDeviceMethod használatával meghívhat egy közvetlen metódust név szerint az eszközön. A metódusnév paraméter azonosítja a közvetlen metódust.

Ez a példa az "újraindítás" metódust hívja meg, hogy indítsa el az újraindítást az eszközön. Az "újraindítás" metódus az eszközön található visszahíváskezelő függvényre van leképezve a jelen cikk Közvetlen metódus visszahívási szakaszában leírtak szerint.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

SDK-szolgáltatásminták

Az Azure IoT SDK for Node.js az eszközfelügyeleti feladatokat kezelő szolgáltatásalkalmazások munkamintáit tartalmazza. További információk: