Ikereszközök – első lépések

• 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 ikereszközökhöz készült Azure IoT SDK for .NET használatával.

Eszközalkalmazás létrehozása

Az eszközalkalmazások olvashatják és írhatnak ikerjelentésű tulajdonságokat, és értesítést kaphatnak a háttéralkalmazás vagy az IoT Hub által beállított kívánt ikertulajdonság-módosításokról.

Ez a szakasz azt ismerteti, hogyan használhatja az eszközalkalmazás kódját a következőre:

• Ikereszköz lekérése és jelentett tulajdonságok vizsgálata
• Jelentett ikereszköz-tulajdonságok frissítése
• Kívánt tulajdonságfrissítési visszahíváskezelő létrehozása

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á ezt az using utasítást az eszköztár használatához.

using Microsoft.Azure.Devices.Client;

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 az eszköz ikereszközeivel való interakció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

Az Http1 ikereszköz-frissítések esetében a protokoll nem támogatott.

Ez a példa az átviteli protokoll használatával csatlakozik egy Mqtt eszközhöz.

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

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

Ikereszköz lekérése és tulajdonságok vizsgálata

Hívja meg a GetTwinAsync-et az aktuális ikereszköz-tulajdonságok lekéréséhez. Számos Ikerobjektum-tulajdonságot használhat a JSON-adatok meghatározott területeinek eléréséhez, beleértve Propertiesa Twin , Status, Tagsés .Version

Ez a példa lekéri az ikereszköz tulajdonságait, és JSON formátumban nyomtatja ki az ikerértékeket.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Jelentett ikereszköz-tulajdonságok frissítése

Iker jelentett tulajdonság frissítése:

1. TwinCollection-objektum létrehozása a jelentett tulajdonságfrissítéshez
2. Egy vagy több jelentett tulajdonság frissítése az objektumon TwinCollection belül
3. Az UpdateReportedPropertiesAsync használatával küldje le a jelentett tulajdonságmódosításokat az IoT Hub szolgáltatásba

Példa:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Kívánt tulajdonságfrissítési visszahíváskezelő létrehozása

Hozzon létre egy kívánt tulajdonságfrissítési visszahíváskezelőt, amely akkor hajtja végre a kívánt tulajdonság módosítását az ikereszközben, ha a visszahíváskezelő metódus nevét a SetDesiredPropertyUpdateCallbackAsync értékre továbbítja.

Ez a hívás például úgy állítja be a rendszert, hogy értesítse a kívánt tulajdonság módosításakor elnevezettOnDesiredPropertyChangedAsync metódust.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Az ikertulajdonságok TwinCollectionként kerülnek átadásra a visszahívási metódusnak, és struktúrákként KeyValuePair vizsgálhatók.

Ez a példa fogadja a kívánt tulajdonságfrissítéseket, TwinCollectionmajd végighalad a gyűjteményfrissítéseken, és kinyomtatja.KeyValuePair A gyűjtemény végigcsukása KeyValuePair után a kód meghívja UpdateReportedPropertiesAsync a DateTimeLastDesiredPropertyChangeReceived jelentett tulajdonság frissítését, hogy naprakészen tartsa az utolsó frissítési időt.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK-eszközminta

A .NET-hez készült Azure IoT SDK egy ikereszköz-feladatokat kezelő eszközalkalmazás működő mintáját biztosítja. További információ: TwinSample.

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

A háttéralkalmazások az IoT Hubon keresztül csatlakoznak egy eszközhöz, és beolvashatják az eszköz jelentett és kívánt tulajdonságait, megírhatják az eszköz kívánt tulajdonságait, és lefuttathatják az eszköz lekérdezéseit.

Ez a szakasz azt ismerteti, hogyan hozhat létre háttéralkalmazás-kódot a következőre:

• Ikereszközmezők olvasása és frissítése
• Ikereszköz-lekérdezés létrehozása

A RegistryManager osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a szolgáltatásból származó ikereszközökkel való interakcióhoz.

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. Az alkalmazásnak szolgáltatáscsatlakozási engedélyre van szüksége az ikereszköz kívánt tulajdonságainak módosításához, és a beállításjegyzék olvasási engedélyére van szüksége az identitásjegyzék lekérdezéséhez. Nincs olyan alapértelmezett megosztott hozzáférési szabályzat, amely csak ezt a két engedélyt tartalmazza, ezért létre kell hoznia egyet, ha még nem létezik. Adja meg ezt a megosztott hozzáférési szabályzatot, kapcsolati sztring paraméterként.fromConnectionString 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.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.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.

Ikereszközmezők olvasása és frissítése

A GetTwinAsync meghívásával lekérheti az aktuális ikereszköz-mezőket egy ikerobjektumba.

Az Twin osztály tartalmazza az ikereszköz egyes szakaszainak megfelelő tulajdonságokat . Twin Az osztály tulajdonságaival megtekintheti és frissítheti az ikereszköz-mezőket. Az objektumtulajdonságok használatával Twin több ikermezőt is frissíthet, mielőtt a frissítéseket az eszközre UpdateTwinAsyncíranál.

Az ikermező-frissítések elvégzése után hívja meg az UpdateTwinAsync-et , hogy írja Twin vissza az objektummező frissítéseit egy eszközre. Hibakezelővel párosított logika és catch használat try a hibásan formázott javításhibák UpdateTwinAsyncelfogásához.

Ikereszköz-címkék olvasása és frissítése

Az ikereszközök címkéinek adatainak olvasásához és írásához használja az ikereszközcímkék tulajdonságot.

Címkék frissítése ikerobjektum használatával

Ez a példa létrehoz egy címkejavítást location , hozzárendeli az Twin objektumhoz a Tags tulajdonság használatával, majd alkalmazza a javítást a tulajdonság használatával UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Címkék frissítése JSON-sztring használatával

JSON formátumú ikereszköz-információfrissítési javítást hozhat létre és alkalmazhat. Az IoT Hub elemzi és alkalmazza a javítást, ha megfelelően van formázva.

Ez a példa meghívja GetTwinAsync az aktuális ikereszköz-mezők objektumba Twin való lekérését, létrehoz egy JSON formátumú javítást tag régió- és növényhelyadatokkal, majd meghívja UpdateTwinAsync a javítás alkalmazását az ikereszköz frissítéséhez. Ha nem sikerült, hibaüzenet jelenik meg UpdateTwinAsync .

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Ikerpéldány kívánt tulajdonságainak megtekintése és frissítése

Az ikereszköz TwinProperties.Desired tulajdonságával olvashatók és írhatóak az eszköz kívánt tulajdonságadatai. Ikertulajdonságok Desired frissítése JSON-formátumú javítással.

Ez a példa meghívja GetTwinAsync az aktuális ikereszköz-mezők egy Twin objektumba való lekérését, frissíti az ikerpéldány speed kívánt tulajdonságát, majd meghívja UpdateTwinAsync az Twin objektum alkalmazását az ikereszköz frissítésére.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Egyéb ikerfrissítési módszerek

Az ikerfrissítéseket az alábbi SDK-módszerekkel is alkalmazhatja:

• A ReplaceTwinAsync hívásával cserélje le a teljes ikereszközt.
• Az UpdateTwins2Async hívásával frissítheti a rendszerben korábban létrehozott ikerpéldányok listáját.

Ikereszköz-lekérdezés létrehozása

Ez a szakasz két ikereszköz-lekérdezést mutat be. Az ikereszköz-lekérdezések OLYAN SQL-szerű lekérdezések, amelyek az ikereszköz-eredményhalmazt adnak vissza.

Ikereszköz-lekérdezés létrehozásához hívja meg a CreateQueryt , hogy küldjön be egy ikerpéldány SQL-lekérdezést, és szerezzen be egy IQuery-felületet . Igény szerint meghívhat CreateQuery egy második paramétert is, hogy oldalonként maximális számú elemet adjon meg.

A következő hívás GetNextAsTwinAsync vagy GetNextAsJsonAsync metódus a szükséges számú alkalommal az összes ikereredmény lekéréséhez.

• GetNextAsTwinAsync a következő lapozott eredmény ikerobjektumkéntvaló lekéréséhez.
• GetNextAsJsonAsync a következő lapszámozott eredmény JSON-sztringekként való lekéréséhez.

Az IQuery interfész tartalmaz egy HasMoreResults logikai tulajdonságot, amellyel ellenőrizheti, hogy több ikereredményt szeretne-e lekérni.

Ez a példa lekérdezés csak a Redmond43-üzemben található eszközök ikereszközeit választja ki.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Ez a példa lekérdezés pontosítja az első lekérdezést, amely csak a mobilhálózaton keresztül csatlakozó eszközöket választja ki.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

SDK-szolgáltatásminta

A .NET-hez készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely ikereszköz-feladatokat kezel. További információ: Registry Manager-minta.

• 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 ikereszközökhöz készült Azure IoT SDK for Java használatával.

Eszközalkalmazás létrehozása

Az eszközalkalmazások olvashatják és írhatnak ikerjelentésű tulajdonságokat, és értesítést kaphatnak a háttéralkalmazás vagy az IoT Hub által beállított kívánt ikertulajdonság-módosításokról.

Ez a szakasz azt ismerteti, hogyan hozhat létre eszközalkalmazás-kódot a következő módon:

• Ikereszköz lekérése és megtekintése
• Jelentett ikereszköz-tulajdonságok frissítése
• Feliratkozás a kívánt tulajdonságmódosításokra

A DeviceClient osztály az eszköz ikereszközeivel való interakcióhoz szükséges összes metódust elérhetővé teszi.

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.DeviceTwin.*;

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

• 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

Ikereszköz lekérése és megtekintése

Az ügyfélkapcsolat megnyitása után hívja meg a getTwint , hogy lekérje az aktuális ikertulajdonságokat egy Twin objektumba.

Példa:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Ikereszköz jelentett tulajdonságainak frissítése

Az aktuális ikerpéldány beolvasása után megkezdheti a jelentett tulajdonságfrissítéseket. A jelentett tulajdonságfrissítéseket az aktuális ikerpéldány lekérése nélkül is elvégezheti, ha a megfelelő jelentett tulajdonságverzióval rendelkezik. Ha jelentést küld a tulajdonságokról, és "az előfeltétel meghiúsult" hibaüzenetet kap, akkor a jelentett tulajdonságok verziója elavult. Ebben az esetben kérje le újra a legújabb verziót getTwin .

Jelentett tulajdonságok frissítése:

1. Hívja meg a getReportedProperties parancsot, hogy lekérje az iker jelentett tulajdonságait egy TwinCollection objektumba.

2. A Put használatával frissíthet egy jelentett tulajdonságot az objektumon TwinCollection belül. Minden jelentett tulajdonságfrissítés hívása put .

3. Az updateReportedProperties használatával alkalmazza a metódussal frissített jelentett tulajdonságok csoportjátput.

Példa:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Feliratkozás a kívánt tulajdonságmódosításokra

A subscribeToDesiredProperties meghívása a kívánt tulajdonságmódosításokra való feliratkozáshoz. Ez az ügyfél minden alkalommal visszahívást kap egy Twin objektummal, amikor egy kívánt tulajdonság frissül. A visszahívás vagy a teljes kívánt tulajdonságkészletet tartalmazza, vagy csak a frissített kívánt tulajdonságot a kívánt tulajdonság módosításának módjától függően.

Ez a példa feliratkozik a kívánt tulajdonságmódosításokra. A kívánt tulajdonságmódosításokat a rendszer egy nevesített DesiredPropertiesUpdatedHandlerkezelőnek továbbítja.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

Ebben a példában a kívánt tulajdonságmódosítási visszahíváskezelő meghívja a DesiredPropertiesUpdatedHandler getDesiredProperties parancsot a tulajdonságmódosítások lekérésére, majd kinyomtatja a frissített ikertulajdonságokat.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

SDK-eszközminta

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ó: Ikereszköz-minta.

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

Ez a szakasz a következő háttéralkalmazások létrehozását ismerteti:

• Ikereszközök címkéinek frissítése
• Eszközök lekérdezése szűrőkkel a címkéken és tulajdonságokon

A ServiceClientDeviceTwin osztály olyan metódusokat tartalmaz, amelyekkel a szolgáltatások hozzáférhetnek az ikereszközökhöz.

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.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

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 DeviceTwin konstruktor használatával hozza létre a kapcsolatot az IoT Hubbal. Az DeviceTwin objektum kezeli az IoT Hubbal folytatott kommunikációt.

Az alkalmazásnak szolgáltatáscsatlakozási engedélyre van szüksége az ikereszköz kívánt tulajdonságainak módosításához, és a beállításjegyzék olvasási engedélyére van szüksége az identitásjegyzék lekérdezéséhez. Nincs olyan alapértelmezett megosztott hozzáférési szabályzat, amely csak ezt a két engedélyt tartalmazza, ezért létre kell hoznia egyet, ha még nem létezik. Adja meg ezt a megosztott hozzáférési szabályzatot, kapcsolati sztring paraméterként.fromConnectionString 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.

A DeviceTwinDevice objektum az ikereszközt jelöli annak tulajdonságaival és címkéivel.

Példa:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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.

Ikereszköz-mezők frissítése

Az ikereszköz mezőinek frissítése:

1. Az ikereszköz aktuális mezőinek lekérése a getTwin használatával

   Ez a példa lekéri és kinyomtatja az ikereszköz-mezőket:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. HashSet Objektum add használata ikercímkepárok csoportjához

3. A setTags használatával egy objektumból tags származó címkepárok csoportját adhat hozzá egy DeviceTwinDevice objektumhoz

4. Az ikerpéldány frissítése az IoT Hubon az updateTwin használatával

   Ez a példa frissíti az ikereszköz régió- és üzemi ikereszköz-címkéinek frissítését:

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Ikereszköz-lekérdezés létrehozása

Ez a szakasz két ikereszköz-lekérdezést mutat be. Az ikereszköz-lekérdezések OLYAN SQL-szerű lekérdezések, amelyek az ikereszköz-eredményhalmazt adnak vissza.

A Lekérdezés osztály olyan metódusokat tartalmaz, amelyekkel SQL-stílusú lekérdezéseket hozhat létre ikerpéldányok, feladatok, eszközfeladatok vagy nyers adatok esetén az IoT Hubba.

Eszköz-lekérdezés létrehozása:

1. Az ikerpéldányok SQL-lekérdezésének létrehozása a createSqlQuery használatával

2. A lekérdezés végrehajtása a queryTwin használatával

3. A hasNextDeviceTwin használatával ellenőrizze, hogy van-e másik ikereszköz az eredményhalmazban

4. A getNextDeviceTwin használatával kérje le a következő ikereszközt az eredményhalmazból

Az alábbi példa lekérdezések legfeljebb 100 eszközt adnak vissza.

Ez a példa lekérdezés csak a Redmond43-üzemben található eszközök ikereszközeit választja ki.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Ez a példa lekérdezés pontosítja az első lekérdezést, amely csak a mobilhálózaton keresztül csatlakozó eszközöket választja ki.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

SDK-szolgáltatásminta

A Java-hoz készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely ikereszköz-feladatokat kezel. További információ: Ikereszköz-minta.

• 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 az ikereszközökhöz az 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

Az eszközalkalmazások olvashatják és írhatnak ikerjelentésű tulajdonságokat, és értesítést kaphatnak a háttéralkalmazás vagy az IoT Hub által beállított kívánt ikertulajdonság-módosításokról.

Az IoTHubDeviceClient osztály olyan metódusokat tartalmaz, amelyek az ikereszközökkel való együttműködéshez használhatók.

Ez a szakasz azt ismerteti, hogyan hozhat létre olyan eszközalkalmazás-kódot, amely:

• Lekéri az ikereszközt, és megvizsgálja a jelentett tulajdonságokat
• Az eszköz ikereszköz-tulajdonságainak javítása

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.

Ikereszköz lekérése és jelentett tulajdonságok vizsgálata

Lekérheti és megvizsgálhatja az ikereszköz adatait, beleértve a címkéket és a tulajdonságokat. A lekért ikereszköz-információk megegyeznek az ikereszköz JSON-formátumú adataival, amelyeket az Azure Portalon tekinthet meg egy eszköz számára.

Hívja meg get_twin , hogy lekérje az ikereszközt az Azure IoT Hub szolgáltatásból. Az ikeradatok egy nyomtatható vagy vizsgálható változóba kerülnek.

Ez a példa lekéri az ikereszközt, és a print paranccsal JSON formátumban jeleníti meg az ikereszközt.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Az eszköz ikereszköz-tulajdonságainak javítása

Az eszköz által jelentett tulajdonságok JSON formátumban történő frissítéséhez javítást alkalmazhat.

Javítás alkalmazása a jelentett tulajdonságok frissítéséhez:

1. Hozzárendelhet egy jelentett tulajdonság JSON-javítást egy változóhoz.
2. Hívja meg patch_twin_reported_properties , hogy alkalmazza a JSON-javítást a jelentett tulajdonságokra. Ez egy szinkron hívás, ami azt jelenti, hogy ez a függvény addig nem tér vissza, amíg a javítást el nem küldi a szolgáltatásnak, és nyugtázza.

Ha patch_twin_reported_properties hibát ad vissza, ez a függvény a megfelelő hibát eredményezi.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Ezeket a metódusokat is meghívhatja az ikereszközök frissítéséhez:

• Hívja meg replace_twin az ikereszköz-címkék és a kívánt tulajdonságok cseréjéhez.
• Hívja meg update_twin az ikereszközök címkéinek és a kívánt tulajdonságoknak a frissítéséhez.

Bejövő kívánt tulajdonságok javításkezelője

Hívja meg a on_twin_desired_properties_patch_received , hogy hozzon létre egy kezelőfüggvényt vagy koroutint, amelyet ikertulajdonság-javítás fogadásakor hív meg. A kezelő egy argumentumot vesz fel, amely az ikerjavítás JSON-szótárobjektum formájában.

Ez a példa beállít egy kívánt tulajdonságjavítás-kezelőt.twin_patch_handler

Példa:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

A twin_patch_handler JSON kívánt tulajdonságfrissítéseinek fogadása és nyomtatása.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

SDK-eszközminták

A Pythonhoz készült Azure IoT SDK a következő mintákat tartalmazza:

• get_twin – Csatlakozzon egy eszközhöz, és kérje le az ikeradatokat.
• update_twin_reported_properties – Az ikerpéldány jelentett tulajdonságainak frissítése.
• receive_twin_desired_properties – A kívánt tulajdonságok fogadása és frissítése.

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

A háttéralkalmazások az IoT Hubon keresztül csatlakoznak egy eszközhöz, és beolvashatják az eszköz jelentett és kívánt tulajdonságait, megírhatják az eszköz kívánt tulajdonságait, és lefuttathatják az eszköz lekérdezéseit.

Ez a szakasz azt ismerteti, hogyan hozhat létre háttéralkalmazást a következőre:

• Ikercímkék és kívánt tulajdonságok frissítése
• Eszközök lekérdezése szűrőkkel a címkéken és tulajdonságokon

Az IoTHubRegistryManager osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a szolgáltatás ikereszközeivel való interakcióhoz.

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. Az alkalmazásnak szolgáltatáscsatlakozási engedélyre van szüksége az ikereszköz kívánt tulajdonságainak módosításához, és a beállításjegyzék olvasási engedélyére van szüksége az identitásjegyzék lekérdezéséhez. Nincs olyan alapértelmezett megosztott hozzáférési szabályzat, amely csak ezt a két engedélyt tartalmazza, ezért létre kell hoznia egyet, ha még nem létezik. Adja meg ezt a megosztott hozzáférési szabályzatot, kapcsolati sztring paraméterként.fromConnectionString 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:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

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

• IoTHubRegistryManager az IoT Hub szolgáltatáskapcsolatának létrehozásához Entra-jogkivonat hitelesítő adataival.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

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.

Ikercímkék és kívánt tulajdonságok frissítése

Egyszerre frissítheti az ikereszköz-címkéket és a kívánt tulajdonságokat egy háttéralkalmazásból a update_twin használatával.

1. Az ikereszköz aktuális verziójának lekéréséhez hívja meg a get_twin
2. Az Ikerosztály használatával JSON formátumban adhat hozzá címkéket és tulajdonságokat.
3. Hívja meg update_twin , hogy alkalmazza a javítást az ikereszközre. A replace_twin is használhatja az ikereszköz kívánt tulajdonságainak és címkéinek cseréjére.

Ez a példa frissíti region és plant címkézi az adatokat, és beállít egy power_level kívánt tulajdonságot a következőre 1: .

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Ikereszköz-lekérdezés létrehozása

Ikereszköz-lekérdezésekkel lekérdezheti az ikereszköz adatait. Az ikereszköz-lekérdezések OLYAN SQL-szerű lekérdezések, amelyek az ikereszköz-eredményhalmazt adnak vissza.

Ikereszköz-lekérdezés használata:

1. Sql-szerű lekérdezéskérés definiálásához használjon QuerySpecification objektumot.

2. Az query_iot_hub használatával lekérdezhet egy IoTHubot, és lekérheti az ikereszköz adatait az SQL-hez hasonló lekérdezési specifikáció használatával.

Ez a példa két lekérdezést futtat. Az első csak az üzemen belüli Redmond43 eszközök ikereszközeit választja ki, a második pedig pontosítja a lekérdezést, hogy csak azokat az eszközöket válassza ki, amelyek szintén mobilhálózaton keresztül csatlakoznak. Az eredmények minden lekérdezés után megjelennek.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

SDK-szolgáltatásminta

A Pythonhoz készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely ikereszköz-feladatokat kezel. További információt a Registry Manager lekérdezésmintájában talál.

• 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 ikereszközökhöz.

Eszközalkalmazás létrehozása

Az eszközalkalmazások olvashatják és írhatnak ikerjelentésű tulajdonságokat, és értesítést kaphatnak a háttéralkalmazás vagy az IoT Hub által beállított kívánt ikertulajdonság-módosításokról.

Ez a szakasz azt ismerteti, hogyan használható az azure-iot-device csomag az Azure IoT SDK-ban Node.js eszközalkalmazás létrehozásához a következő célokra:

• Ikereszköz lekérése és jelentett tulajdonságok vizsgálata
• Jelentett ikereszköz-tulajdonságok frissítése
• Értesítés a kívánt tulajdonságmódosításról

Eszköz SDK-csomagjának telepítése

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

Az azure-iot-device csomag olyan objektumokat tartalmaz, amelyek IoT-eszközökhöz illesztenek. Az ikerosztály ikerspecifikus objektumokat tartalmaz. Ez a szakasz az ikereszköz-adatok olvasására és írására használt osztálykódot ismerteti Client .

Á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 Mqtt :

npm install azure-iot-device-mqtt --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élmodul létrehozása

Modul létrehozása Client a telepített csomag használatával.

Példa:

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

Protokollmodul létrehozása

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

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

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

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 – Egy olyan kapcsolati sztring, amely egy IoT Hub "eszközcsatlakoztatási" engedélyeit foglalja magában. A kapcsolati sztring a következő formátumban tartalmazza a gazdagépnevet, az eszközazonosítót és a megosztott hozzáférési kulcsot: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor – A szállítási protokoll.

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

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

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 .catch(err) észlelése és kezelőkód végrehajtása.

Példa:

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

Ikereszköz lekérése és jelentett tulajdonságok vizsgálata

Hívja meg a getTwint az ikereszköz aktuális információinak ikerobjektumba való lekéréséhez.

Példa:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Jelentett ikereszköz-tulajdonságok frissítése

Az eszköz jelentett tulajdonságainak frissítéséhez használja a frissítést . A metódus második paramétereként adjon meg egy JSON formátumú javítást az első paraméter és a függvény végrehajtási állapotának visszahívási módszereként.

Ebben a példában a rendszer egy JSON formátumú ikereszköz-javítást tárol a patch változóban. A javítás a következő ikereszköz-frissítési connectivitycellularértéket tartalmazza: . A rendszer átadja a javítás- és hibakezelőt a update metódusnak. Hiba esetén megjelenik egy konzol hibaüzenete.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Értesítés a kívánt tulajdonságmódosításról

Hozzon létre egy kívánt tulajdonságfrissítési eseményfigyelőt, amely a visszahíváskezelő metódus nevének twin.on-ra való átadásával hajtja végre a kívánt tulajdonság módosításakor az eszközön.

A kívánt tulajdonságesemény-figyelő az alábbi űrlapok egyikét használhatja:

• Az összes javítás fogadása egyetlen eseménykezelővel
• Esemény fogadása, ha valami megváltozik a tulajdonságok csoportosítása alatt
• Esemény fogadása egyetlen tulajdonságmódosításhoz

Az összes javítás fogadása egyetlen eseménykezelővel

Létrehozhat egy figyelőt a kívánt tulajdonságmódosítások fogadásához.

Ez a példakód a szolgáltatástól kapott tulajdonságokat adja ki.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Esemény fogadása, ha valami megváltozik a tulajdonságok csoportosítása alatt

Létrehozhat egy figyelőt, hogy eseményt fogadjon, ha a tulajdonságcsoportba tartozó bármi megváltozik.

Példa:

1. A minTemperature tulajdonságok és maxTemperature a tulajdonságok egy névvel ellátott properties.desired.climate changestulajdonságcsoport alatt találhatók.

2. Egy háttérszolgáltatás-alkalmazás alkalmazza ezt a javítást a frissítésre minTemperature és maxTemperature a kívánt tulajdonságokra:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Ez a kód beállít egy kívánt tulajdonságmódosítási eseményfigyelőt, amely aktiválja a properties.desired.climate tulajdonságcsoporton belüli összes módosítást. Ha a csoporton belül a kívánt tulajdonság megváltozik, a konzolon megjelenő minimális és maximális hőmérséklet-változási üzenetek:

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Esemény fogadása egyetlen tulajdonságmódosításhoz

Beállíthat egy figyelőt egyetlen tulajdonságmódosításhoz. Ebben a példában az esemény kódja csak akkor lesz végrehajtva, ha a fanOn logikai érték a javítás része. A kód az új kívánt fanOn állapotot adja ki, amikor a szolgáltatás frissíti.

1. Egy háttéralkalmazás alkalmazza ezt a kívánt tulajdonságjavítást:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. A figyelő csak akkor aktiválódik, ha a fanOn tulajdonság megváltozik:

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Eszköz SDK-minták

Az Azure IoT SDK for Node.js két ikereszköz-mintát tartalmaz:

• Egyszerű mintaeszköz ikereszköze

• Egyszerű mintaeszköz ikereszköz SAS-vel

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

A háttéralkalmazások az IoT Hubon keresztül csatlakoznak egy eszközhöz, és beolvashatják az eszköz jelentett és kívánt tulajdonságait, megírhatják az eszköz kívánt tulajdonságait, és lefuttathatják az eszköz lekérdezéseit.

Ez a szakasz a következő háttéralkalmazások létrehozását ismerteti:

• Ikereszköz lekérése és frissítése
• Ikereszköz-lekérdezés létrehozása

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

A Beállításjegyzék-osztály minden olyan metódust elérhetővé tesz, amely az ikereszközökkel való interakcióhoz szükséges egy háttéralkalmazásból.

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. Az alkalmazásnak szolgáltatáscsatlakozási engedélyre van szüksége az ikereszköz kívánt tulajdonságainak módosításához, és a beállításjegyzék olvasási engedélyére van szüksége az identitásjegyzék lekérdezéséhez. Nincs olyan alapértelmezett megosztott hozzáférési szabályzat, amely csak ezt a két engedélyt tartalmazza, ezért létre kell hoznia egyet, ha még nem létezik. Adja meg ezt a megosztott hozzáférési szabályzatot, kapcsolati sztring paraméterként.fromConnectionString 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.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.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 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.

Ikereszköz lekérése és frissítése

Létrehozhat egy javítást, amely egy ikereszköz címkéjét és kívánt tulajdonságfrissítéseit tartalmazza.

Ikereszköz frissítése:

1. Hívja meg a getTwint az ikereszköz-objektum lekéréséhez.

• Formázza az ikereszköz frissítését tartalmazó javítást. A javítás JSON formátumban van formázva az ikerosztályban leírtak szerint. A háttérszolgáltatás-javítások tartalmazhatnak címke- és kívánt tulajdonságfrissítéseket. További információ a javításformátumról: Címkék és tulajdonságok formátuma.

1. Hívja meg a frissítést az ikereszköz frissítéséhez a javítással.

Ebben a példában a rendszer lekéri az ikereszköztmyDeviceId, majd egy javítást alkalmaz a rendszer az ikerpéldányokra, amelyek a címkefrissítést region: 'US', plant: 'Redmond43'tartalmazzáklocation.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Ikereszköz-lekérdezés létrehozása

SQL-szerű eszköz lekérdezéseket hozhat létre az ikereszközökről származó információk gyűjtéséhez.

A createQuery használatával olyan lekérdezést hozhat létre, amely egy IoT Hub-példányon futtatható, és információkat kereshet az eszközökről vagy feladatokról.

createQuery két paramétert tartalmaz:

• sqlQuery – SQL-sztringként írt lekérdezés.
• pageSize – A kívánt találatok száma oldalanként (nem kötelező. alapértelmezett: 1000, max: 10000).

Ha a pageSize paraméter meg van adva, a lekérdezési objektum tartalmaz egy hasMoreResults logikai tulajdonságot, amelyet a metódussal ellenőrizheti és használhat a nextAsTwin következő ikereredmény-lap lekéréséhez, amennyire csak szükséges, az összes eredmény lekéréséhez. Az olyan eredményekhez, amelyek nem ikereszközök, például az összesítő lekérdezések eredményei, meghívható egy metódus next .

Ez a példa lekérdezés csak az üzemben található Redmond43 eszközök ikereszközeit választja ki.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Ez a példa lekérdezés pontosítja az első lekérdezést, amely csak a mobilhálózaton keresztül csatlakozó eszközöket választja ki.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Service SDK-minta

A Node.js-hez készült Azure IoT SDK egy olyan szolgáltatásalkalmazás működő mintáját biztosítja, amely ikereszköz-feladatokat kezel. További információ: Device Twin Backend Service – Ez a projekt egy adott eszköz ikereszköz-frissítéseinek küldéséhez használható.