Get started with Azure IoT Hub device twins - Azure IoT Hub

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
Update reported device twin properties
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

Fontos

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

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

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

Connect to the device using the CreateFromConnectionString method along with device connection string and the connection transport protocol.

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 egy átviteli protokollt használva 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:

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

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

Ez a példa a tanúsítvány bemeneti paraméterértékeit mutatja be helyi változóként az egyértelműség érdekében. Éles rendszerben a bizalmas bemeneti paramétereket környezeti változókban vagy más biztonságosabb tárolási helyen tárolhatja. For example, use Environment.GetEnvironmentVariable("HOSTNAME") to read the host name environment variable.

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:

Code samples

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

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 Twin, Properties, 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()}");

Update reported device twin properties

To update a twin reported property:

TwinCollection-objektum létrehozása a jelentett tulajdonságfrissítéshez
Egy vagy több jelentett tulajdonság frissítése az objektumon TwinCollection belül
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 TwinCollection formájában kerülnek átadásra a visszahívási módszernek, és mint struktúrák vizsgálhatók.

This example receives the desired property updates as a TwinCollection, then loops through and prints the KeyValuePair collection updates. Miután végighaladt a KeyValuePair gyűjteményen, a kód meghívja a UpdateReportedPropertiesAsync-t, hogy frissítse a DateTimeLastDesiredPropertyChangeReceived jelentett tulajdonságot, ezzel naprakészen tartva 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:

Read and update device twin fields
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

Fontos

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

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

Háttéralkalmazás csatlakoztatása egy eszközhöz a CreateFromConnectionString használatával. Az alkalmazásnak rendelkeznie kell a szolgáltatáskapcsolat engedéllyel az ikereszköz kívánt tulajdonságainak módosításához, és regiszter olvasási engedéllyel az identitásregiszter 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. Supply this shared access policy connection string as a parameter to 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 token egy IoT Hub-kapcsolati metódushoz van á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
Federated identity credential

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például a IoT Hub Twin Contributor szükséges az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

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

Hitelesítés DefaultAzureCredential használatával

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. 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 token, amelyet egy IoT Hub kapcsolati módszerhez továbbítanak hitelesítő adatként.

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

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

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

Ebben a példában a TokenCredential átadásra kerül a RegistryManager.Create részére egy RegistryManager objektum létrehozásához.

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

Code sample

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

Read and update device twin fields

You can retrieve current device twin fields into a Twin object by calling GetTwinAsync.

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. You can use the Twin object properties to update multiple twin fields before writing the updates to the device using UpdateTwinAsync.

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. Use try and catch logic coupled with an error handler to catch incorrectly formatted patch errors from UpdateTwinAsync.

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

Use the device twin Tags property to read and write device tag information.

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. IoT Hub parses and applies the patch if it is correctly formatted.

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);
}

View and update twin desired properties

Az ikereszköz TwinProperties.Desired tulajdonságával olvashatók és írhatóak az eszköz kívánt tulajdonságadatai. Update twin Desired properties using a JSON-formatted patch.

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:

Call ReplaceTwinAsync to replace the entire device twin.
Az UpdateTwins2Async hívásával frissítheti a rendszerben korábban létrehozott ikrek 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 CreateQuery metódust egy ikereszköz SQL-lekérdezés benyújtásához, és szerezze meg az IQuery interfészt. Igény szerint meghívhat CreateQuery egy második paramétert is, hogy oldalonként maximális számú elemet adjon meg.

Next call GetNextAsTwinAsync or GetNextAsJsonAsync method as many times as needed to retrieve all twin results.

GetNextAsTwinAsync to retrieve the next paged result as Twin objects.
GetNextAsJsonAsync to retrieve the next paged result as JSON strings.

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:

Retrieve and view a device twin
Update reported device twin properties
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.

Fontos

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

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

Fontos

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

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

Eszköz csatlakoztatása az IoT Hubhoz:

Az IotHubClientProtocol használatával válasszon egy átviteli protokollt. Példa:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```
Használja a DeviceClient konstruktort az eszköz elsődleges kapcsolati sztringjének és protokolljának hozzáadásához.
```
String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);
```
Nyissa meg az eszközt az IoT Hubhoz való csatlakozáshoz. If the client is already open, the method does nothing.
```
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:

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

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

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

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

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

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

Code samples

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

Retrieve and view a device twin

Az ügyfélkapcsolat megnyitása után hívja meg a getTwin függvényt, 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);

Update device twin reported properties

After retrieving the current twin, you can begin making reported property updates. 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. In that case, get the latest version by calling getTwin again.

Jelentett tulajdonságok frissítése:

Call getReportedProperties to fetch the twin reported properties into a TwinCollection object.
A Put használatával frissíthet egy jelentett tulajdonságot az objektumon TwinCollection belül. Call put for each reported property update.
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);

Hívja meg a subscribeToDesiredProperties funkciót 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. For more information, see Device Twin Sample.

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

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

Updates device twin tags
Eszközök lekérdezése szűrők segítségével a címkék és tulajdonságok alapján

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

Fontos

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

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

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 rendelkeznie kell a szolgáltatáskapcsolat engedéllyel az ikereszköz kívánt tulajdonságainak módosításához, és regiszter olvasási engedéllyel az identitásregiszter 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. Supply this shared access policy connection string as a parameter to 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 token egy IoT Hub-kapcsolati metódushoz van á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
Federated identity credential

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például a IoT Hub Twin Contributor szükséges az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

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

Hitelesítés DefaultAzureCredential használatával

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a Java Azure Identity ügyfélkódtárában található Hitelesítőadat-láncok című témakörben talál.

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

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

Ebben a példában a DefaultAzureCredentialBuilder megpróbál hitelesíteni egy kapcsolatot a DefaultAzureCredential által leírt listából. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági token hitelesítő adat, amelyet átadnak egy konstruktornak, például a ServiceClient számára.

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:

Code samples

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

Update device twin fields

To update device twin fields:

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

Ez a példa lekéri és kinyomtatja az eszköz ikermezőket:

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

Use a HashSet object to add a group of twin tag pairs
A setTags használatával egy objektumból tags származó címkepárok csoportját adhat hozzá egy DeviceTwinDevice objektumhoz

Use updateTwin to update the twin in the IoT hub

This example updates the region and plant device twin tags for a device twin:

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

Használja a createSqlQuery parancsot az ikerpéldányok SQL-lekérdezésének felépítéséhez
A lekérdezés végrehajtása a queryTwin használatával
A hasNextDeviceTwin használatával ellenőrizze, hogy van-e másik ikereszköz az eredményhalmazban
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. For more information, see Device Twin Sample.

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
Patch reported device twin properties

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

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

from azure.iot.device import IoTHubDeviceClient

Eszköz csatlakoztatása az IoT Hubhoz

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

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

Fontos

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

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

Eszköz csatlakoztatása az IoT Hubhoz:

Hívja meg a create_from_connection_string függvényt az eszköz elsődleges kapcsolatának karakterláncának hozzáadásához.
Hívja meg a connect-et az eszköz kliens csatlakoztatásához.

Példa:

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

# Connect the client
device_client.connect()

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

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

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

Ez a példa a tanúsítvány bemeneti paraméterértékeit mutatja be helyi változóként az egyértelműség érdekében. Éles rendszerben a bizalmas bemeneti paramétereket környezeti változókban vagy más biztonságosabb tárolási helyen tárolhatja. For example, use os.getenv("HOSTNAME") to read the host name environment variable.

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

Code samples

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 iker adatok egy olyan változóba kerülnek, amelyet ki lehet nyomtatni vagy meg lehet vizsgálni.

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

Patch reported device twin properties

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:

Assign a reported property JSON patch to a variable.
Call patch_twin_reported_properties to apply the JSON patch to reported properties. This is a synchronous call, meaning that this function does not return until the patch is sent to the service and acknowledged.

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:

Call replace_twin to replace device twin tags and desired properties.
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ési modulja

Call on_twin_desired_properties_patch_received to create a handler function or coroutine that is called when a twin desired properties patch is received. The handler takes one argument, which is the twin patch in the form of a JSON dictionary object.

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 fogadja és kinyomtatja a kívánt JSON tulajdonságfrissítéseket.

    # 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 - Update twin reported properties.
receive_twin_desired_properties - Receive and update desired properties.

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ők segítségével a címkék és tulajdonságok alapján

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

Fontos

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

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

Csatlakozzon az IoT Hubhoz from_connection_string használatával. Az alkalmazásnak rendelkeznie kell a szolgáltatáskapcsolat engedéllyel az ikereszköz kívánt tulajdonságainak módosításához, és regiszter olvasási engedéllyel az identitásregiszter 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. Supply this shared access policy connection string as a parameter to 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 token egy IoT Hub-kapcsolati metódushoz van á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
Federated identity credential

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például a IoT Hub Twin Contributor szükséges az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

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

Hitelesítés DefaultAzureCredential használatával

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. 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 DefaultAzureCredential használat előnyeiről és hátrányairól további információt a Pythonhoz készült Azure Identity ügyfélkönyvtá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 token, amelyet egy IoT Hub kapcsolati módszerhez továbbítanak hitelesítő adatként.

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-hoz való szolgáltatáskapcsolat létrehozásához Entra token hitelesítés használatával.
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 {Your Entra domain URL}.azure-devices.net formátumban https:// kell lennie. Például: MyAzureDomain.azure-devices.net.
Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure hitelesítő adatokat a DefaultAzureCredential használatával szerzi be. Az Azure-szolgáltatás URL-címét és hitelesítő adatait megadják a IoTHubRegistryManager.from_token_credential számára, hogy létrehozzák az IoT Hubhoz való kapcsolatot.

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)

Code samples

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.

Az eszköz ikerpárjának aktuális verziójának lekéréséhez hívja meg a get_twin függvényt.
Az Ikerosztály használatával JSON formátumban adhat hozzá címkéket és tulajdonságokat.
Call update_twin to apply the patch to the device twin. 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 a region és plant címkék információit, és beállít egy power_level kívánt tulajdonságot 1-re.

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.

To use a device twin query:

Sql-szerű lekérdezéskérés definiálásához használjon QuerySpecification objektumot.
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
Update reported device twin properties
Értesítés a kívánt tulajdonságmódosításról

Fontos

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

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

Fontos

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

Hitelesítés 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:

A fromConnectionString meghívásával adja hozzá az eszköz- vagy identitásmodul kapcsolati sztringet és az átviteli típust az Client objektumhoz. Adja hozzá a x509=true-t a kapcsolati sztringhez, hogy jelezze, hogy a DeviceClientOptions-hez tanúsítványt adtak hozzá. Példa:
- Egy eszköz kapcsolati karakterlánca:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- An identity module connection string:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Konfiguráljon egy JSON-változót tanúsítványadatokkal, és adja át a DeviceClientOptionsnak.
Hívja meg a setOptionst , hogy adjon hozzá egy X.509-tanúsítványt és kulcsot (és opcionálisan jelszót) az ügyfélátvitelhez.
Hívja meg az open függvényt az eszköz és az IoT Hub közötti kapcsolat megnyitásához.

Ez a példa egy JSON-változó tanúsítványkonfigurációs adatait mutatja be. A tanúsítványkonfigurációkat átadásra kerülnek clientOptionssetOptions-nak/nek, és a kapcsolat open használatával nyílik meg.

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

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

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

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

Code sample

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 - A Http példány ritkán ellenőrzi az IoT Hubtól érkező üzeneteket Client használata esetén (legalább 25 percenként).
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ívja meg fromConnectionString 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. Használja a .catch(err) kódot hiba észlelésére és kezelőkód végrehajtására.

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 getTwin függvényt, hogy lekérje az eszköz iker aktuális információit egy Twin objektumba.

Példa:

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

Update reported device twin properties

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

Ebben a példában a rendszer egy JSON formátumú ikereszköz-javítást tárol a patch változóban. The patch contains a device twin connectivity update value of cellular. 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 eseményfigyelőt, amely a kívánt tulajdonság módosulásakor hajtódik végre az eszközön. Ehhez adja át a visszahíváskezelő metódus nevét a "twin.on" metódusnak.

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
Receive an event if anything changes under a properties grouping
Receive an event for a single property change

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

You can create a listener to receive any desired property change.

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));
});

Receive an event if anything changes under a properties grouping

Létrehozhat egy figyelőt, amely eseményt fogad, ha megváltozik valami egy tulajdonságcsoportba tartozó elemnél.

Példa:

A minTemperature tulajdonságok és maxTemperature a tulajdonságok egy névvel ellátott properties.desired.climate changestulajdonságcsoport alatt találhatók.
Egy háttérszolgáltatás alkalmazás ezt a javítást alkalmazza a minTemperature és maxTemperature kívánt tulajdonságainak frissítésére.
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```

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);
    }
});

Receive an event for a single property change

Beállíthat egy figyelőt, amely figyelemmel kíséri egyetlen tulajdonság módosítását. 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.

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

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

The listener triggers only when the fanOn property changes:

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

Device SDK samples

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

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
Creates a device twin query

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

Fontos

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

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

A fromConnectionString használatával csatlakozhat az IoT Hubhoz. Az alkalmazásnak rendelkeznie kell a szolgáltatáskapcsolat engedéllyel az ikereszköz kívánt tulajdonságainak módosításához, és regiszter olvasási engedéllyel az identitásregiszter 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. Supply this shared access policy connection string as a parameter to 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 token egy IoT Hub-kapcsolati metódushoz van á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 Node.js SDK hitelesítésének á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
Federated identity credential

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például a IoT Hub Twin Contributor szükséges az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

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

Hitelesítés DefaultAzureCredential használatával

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. 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 token, amelyet egy IoT Hub kapcsolati módszerhez továbbítanak hitelesítő adatként.

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

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

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

fromTokenCredential két paramétert igényel:

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

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

Code samples

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.

To update a device twin:

Hívja meg a getTwin parancsot a "device twin" objektum lekéréséhez.

Format a patch that contains the device twin update. A javítás JSON formátumban van formázva a Twin osztály leírása 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.

Call update to update the device twin with the patch.

In this example, the device twin is retrieved for myDeviceId, then a patch is applied to the twins that contains location tag update of region: 'US', plant: 'Redmond43'.

     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, akkor a lekérdezési objektumban van egy logikai tulajdonság, amelyet ellenőrizhet, majd a hasMoreResults metódussal lekérheti a következő ikereredmény-oldalt annyiszor, ahányszor szükséges az összes eredmény eléréséhez. Azokhoz az eredményekhez, amelyek nem eszköz-ikrek, például az összesítő lekérdezések eredményeihez, elérhető egy next nevű metódus.

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 sample

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

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

Get started with device twins

Előfeltételek

Áttekintés

Eszközalkalmazás létrehozása

Szükséges eszköz NuGet-csomag

Eszköz csatlakoztatása az IoT Hubhoz

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

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

Code samples

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

Update reported device twin properties

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

SDK-eszközminta

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

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

Csatlakozás az IoT Hubhoz

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Code sample

Read and update device twin fields

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

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

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

View and update twin desired properties

Egyéb ikerfrissítési módszerek

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

SDK-szolgáltatásminta

Áttekintés

Eszközalkalmazás létrehozása

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

Eszköz csatlakoztatása az IoT Hubhoz

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

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

Code samples

Retrieve and view a device twin

Update device twin reported properties

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

SDK-eszközminta

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

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

Csatlakozás az IoT Hubhoz

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

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

Egyéb hitelesítési osztályok

Code samples

Update device twin fields

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

SDK-szolgáltatásminta

Áttekintés

Csomagok telepítése

Eszközalkalmazás létrehozása

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

Eszköz csatlakoztatása az IoT Hubhoz

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

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

Code samples

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

Patch reported device twin properties

Bejövő kívánt tulajdonságok javításkezelési modulja

SDK-eszközminták

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

Csatlakozás az IoT Hubhoz

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Code samples

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

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

SDK-szolgáltatásminta

Áttekintés

Eszközalkalmazás létrehozása

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

Eszköz csatlakoztatása az IoT Hubhoz