Sdílet prostřednictvím

Začínáme s dvojníky zařízení

Sada SDK zařízení a sada SDK služby Azure IoT Hub slouží k vývoji aplikací, které zpracovávají běžné úlohy dvojčete zařízení. Dvojčata zařízení jsou dokumenty JSON, které ukládají informace o stavu zařízení, včetně metadat, konfigurací a podmínek. IoT Hub zachová dvojče zařízení pro každé zařízení, které se k němu připojí.

Dvojčata zařízení můžete použít k:

  • Ukládání metadat zařízení z back-endu řešení
  • Hlášení aktuálních informací o stavu, jako jsou dostupné možnosti a podmínky, například použitá metoda připojení, z aplikace zařízení
  • Synchronizace stavu dlouhotrvajících pracovních postupů, jako jsou aktualizace firmwaru a konfigurace, mezi aplikací zařízení a back-endovou aplikací
  • Dotazování na metadata, konfiguraci nebo stav zařízení

Další informace o dvojčatech zařízení, včetně toho, kdy používat dvojčata zařízení, najdete v tématu Principy a používání dvojčat zařízení ve službě IoT Hub.

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

V tomto článku se dozvíte, jak vyvíjet dva typy aplikací:

  • Aplikace zařízení můžou zpracovávat požadavky na aktualizaci požadovaných vlastností a reagovat na změny ohlášených vlastností.
  • Aplikace služeb můžou aktualizovat značky digitálních dvojčat, nastavit nové požadované vlastnosti a dotazovat zařízení na základě hodnot digitálních dvojčat.

Poznámka:

Tento článek je určen k doplnění ukázek z Azure IoT SDK, na které se odkazuje v tomto článku. Nástroje sady SDK můžete použít k sestavení zařízení i back-endových aplikací.

Požadavky

  • IoT centrum

  • Zaregistrované zařízení

  • Pokud vaše aplikace používá protokol MQTT, ujistěte se, že je v bráně firewall otevřený port 8883. Protokol MQTT komunikuje přes port 8883. Tento port může být blokovaný v některých podnikových a vzdělávacích síťových prostředích. Další informace a způsoby řešení tohoto problému najdete v tématu Připojení ke službě IoT Hub (MQTT).

  • Vyžaduje Visual Studio.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro .NET vytvořit kód aplikace zařízení a back-endové služby pro dvojčata zařízení.

Vytvoření aplikace zařízení

Aplikace zařízení můžou číst a zapisovat ohlášené vlastnosti dvojčete a dostávat oznámení o změnách požadovaných vlastností dvojčete, které jsou nastavené back-endovou aplikací nebo službou IoT Hub.

Tato část popisuje, jak používat kód aplikace zařízení k:

  • Načtení dvojčete zařízení a prozkoumání ohlášených vlastností
  • Aktualizace ohlášených vlastností dvojčete zařízení
  • Vytvoření obslužné rutiny pro aktualizaci požadované vlastnosti pomocí zpětného volání

Požadovaný NuGet balíček zařízení

Klientské aplikace zařízení napsané v jazyce C# vyžadují balíček NuGet Microsoft.Azure.Devices.Client .

Přidejte tento using příkaz pro použití knihovny zařízení.

using Microsoft.Azure.Devices.Client;

Připojení zařízení ke službě IoT Hub

Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:

  • Sdílený přístupový klíč
  • Certifikát X.509

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Ověřování pomocí sdíleného přístupového klíče

Třída DeviceClient zpřístupňuje všechny metody potřebné k interakci s digitálními dvojčaty zařízení ze zařízení.

Připojte se k zařízení pomocí metody CreateFromConnectionString spolu s připojovací řetězec zařízení a protokolem přenosu připojení.

Parametr CreateFromConnectionStringtransportních protokolů TransportType podporuje následující přenosové protokoly:

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

Protokol Http1 není podporován pro aktualizace dvojčete zařízení.

Tento příklad se připojí k zařízení pomocí přenosového Mqtt protokolu.

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

Ověřování pomocí certifikátu X.509

Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:

  1. Pomocí DeviceAuthenticationWithX509Certificate vytvořte objekt, který obsahuje informace o zařízení a certifikátu. DeviceAuthenticationWithX509Certificate je předán jako druhý parametr do DeviceClient.Create (krok 2).

  2. Pomocí DeviceClient.Create připojte zařízení ke službě IoT Hub pomocí certifikátu X.509.

V tomto příkladu jsou informace o zařízení a certifikátu vyplněny v objektu authDeviceAuthenticationWithX509Certificate , který je předán DeviceClient.Create.

Tento příklad ukazuje hodnoty vstupních parametrů certifikátu jako místní proměnné pro přehlednost. V produkčním systému uložte citlivé vstupní parametry do proměnných prostředí nebo do jiného bezpečnějšího umístění úložiště. Použijte Environment.GetEnvironmentVariable("HOSTNAME") například ke čtení proměnné prostředí s názvem hostitele.

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

Další informace o ověřování certifikátů najdete tady:

Ukázky kódu

Pracovní ukázky ověřování certifikátů X.509 zařízení najdete tady:

Načtení digitálního dvojčete zařízení a zkoumání vlastností

Zavolejte GetTwinAsync a načtěte aktuální vlastnosti dvojice zařízení. Existuje mnoho vlastností objektu Twin, které můžete použít pro přístup ke konkrétním oblastem Twin dat JSON, včetně Properties, Status, Tagsa Version.

Tento příklad načte vlastnosti dvojčete zařízení a zobrazí hodnoty vlastností dvojčete ve formátu JSON.

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

Aktualizace ohlášených vlastností dvojčete zařízení

Aktualizovat ohlášený atribut digitálního dvojčete:

  1. Vytvoření objektu TwinCollection pro aktualizaci ohlášené vlastnosti
  2. Aktualizace jedné nebo více ohlášených vlastností v rámci objektu TwinCollection
  3. Použijte UpdateReportedPropertiesAsync k odeslání změn ohlášených vlastností do služby IoT hub.

Příklad:

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

Vytvořte obslužnou rutinu zpětného volání pro aktualizaci požadované vlastnosti

Vytvořte obslužnou rutinu zpětného volání aktualizace požadované vlastnosti, která se spustí při změně požadované vlastnosti ve dvojčeti zařízení předáním názvu metody zpětného volání do SetDesiredPropertyUpdateCallbackAsync.

Například toto volání nastaví systém tak, aby byla metoda pojmenovaná OnDesiredPropertyChangedAsync upozorněna při každé změně požadované vlastnosti.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Dvojité vlastnosti se předají metodě zpětného volání jako TwinCollection a dají se zkoumat jako KeyValuePair struktury.

Tento příklad obdrží aktualizace požadované vlastnosti jako TwinCollection, poté prochází smyčku a vytiskne aktualizace kolekce KeyValuePair. Po procházení kolekce KeyValuePair kód zavolá UpdateReportedPropertiesAsync k aktualizaci ohlášené vlastnosti DateTimeLastDesiredPropertyChangeReceived tak, aby čas poslední aktualizace zůstal aktuální.

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

Ukázka zařízení sady SDK

Azure IoT SDK pro .NET poskytuje funkční ukázku aplikace pro zařízení, která zpracovává úlohy spojené s dvojčetem zařízení. Další informace najdete v tématu TwinSample.

Vytvoření back-endové aplikace

Back-endová aplikace se připojí k zařízení přes IoT Hub a může číst hlášené a požadované vlastnosti zařízení, zapisovat požadované vlastnosti zařízení a spouštět dotazy na zařízení.

Tato část popisuje, jak vytvořit back-endový kód aplikace pro:

  • Čtení a aktualizace polí dvojčat zařízení
  • Vytvořte dotaz dvojčete zařízení

Třída RegistryManager zveřejňuje všechny metody potřebné k vytvoření back-endové aplikace pro interakci s dvojčaty zařízení ze služby.

Přidání služby balíčku NuGet

Aplikace back-endových služeb vyžadují balíček NuGet Microsoft.Azure.Devices .

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Připojte back-endovou aplikaci k zařízení pomocí createFromConnectionString. Vaše aplikace potřebuje oprávnění k připojení služby ke změně požadovaných vlastností dvojčete zařízení a potřebuje oprávnění ke čtení registru pro dotazování registru identit. Neexistují žádné výchozí zásady sdíleného přístupu, které obsahují pouze tato dvě oprávnění, takže pokud ještě neexistuje, musíte ho vytvořit. Zadejte tento připojovací řetězec zásady sdíleného přístupu jako parametr pro fromConnectionString. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Údaje o federované identitě

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k zařízení a modulovým dvojčatům služby IoT Hub je například vyžadován IoT Hub Twin Contributor. Další informace naleznete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential. Nicméně se doporučuje v produkčním prostředí použít jiný způsob, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití naleznete v pokynech k použití DefaultAzureCredentialpro DefaultAzureCredential.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tyto balíčky NuGet a odpovídající using příkazy:

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

V tomto příkladu se do proměnných prostředí přidá klientské tajemství, klientské ID a ID tenanta z registrace aplikace Microsoft Entra. Proměnné prostředí použité DefaultAzureCredential slouží k autentizaci aplikace. Výsledkem úspěšného ověřování Microsoft Entra jsou přihlašovací údaje bezpečnostního tokenu, které jsou předávány způsobu připojení IoT Hubu.

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

Výsledný tokenCredential se pak dá předat metodě připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

V tomto příkladu je TokenCredential předán do ServiceClient.Create k vytvoření objektu připojení ServiceClient.

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

V tomto příkladu je TokenCredential předán do RegistryManager.Create k vytvoření objektu RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Ukázka kódu

Ukázkový příklad ověřování služby Microsoft Entra najdete v ukázce ověřování na základě rolí.

Čtení a aktualizace polí dvojčat zařízení

Aktuální pole zařízení twin můžete načíst do objektu Twin zavoláním GetTwinAsync.

Třída Twin obsahuje vlastnosti , které odpovídají každé části dvojčete zařízení. Použijte vlastnosti třídy Twin k zobrazení a aktualizaci polí dvojčat zařízení. Vlastnosti objektu Twin můžete použít k aktualizaci více polí dvojčete před zápisem aktualizací do zařízení pomocí UpdateTwinAsync.

Po provedení aktualizací pole typu twin zavolejte UpdateTwinAsync a zapište Twin aktualizace polí objektu zpět do zařízení. Použití logiky try a catch spojené s chybovým zpracováním k zachycení nesprávně formátovaných chyb oprav z UpdateTwinAsync.

Čtení a aktualizace značek dvojčat zařízení

Ke čtení a zápisu informací o značkách zařízení použijte vlastnost značky digitálního dvojčete.

Aktualizace značek pomocí objektu dvojčete

Tento příklad vytvoří location opravu tagu, přiřadí ji k objektu Twin pomocí vlastnosti Tags, a pak použije opravu pomocí 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);
}
Aktualizace značek pomocí řetězce JSON

Můžete vytvořit a použít opravu aktualizace informací o dvojčeti zařízení ve formátu JSON. IoT Hub parsuje a použije opravu, pokud je správně naformátovaná.

Tento příklad volá GetTwinAsync pro načtení aktuálních polí dvojčete zařízení do objektu Twin, vytvoří záplatu ve formátu JSON s informacemi o lokalitě a místě zařízení a poté volá tag k aplikaci záplaty na aktualizaci dvojčete zařízení. Pokud selhala UpdateTwinAsync , zobrazí se chybová zpráva.

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

Zobrazení a aktualizace požadovaných vlastností dvojčete

Ke čtení a zápisu informací o požadovaných vlastnostech zařízení použijte vlastnost dvojčete TwinProperties.Desired. Aktualizujte vlastnosti dvojčete Desired pomocí opravy ve formátu JSON.

Tento příklad volá GetTwinAsync k načtení aktuálních polí dvojčete zařízení do objektu Twin, aktualizuje požadovanou vlastnost dvojčete speed a potom volá UpdateTwinAsync, které aplikují objekt Twin k aktualizaci dvojčete zařízení.

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

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

Jiné metody aktualizace dvojčat

Aktualizace dvojčat můžete použít také pomocí těchto metod sady SDK:

Vytvořte dotaz dvojčete zařízení

Tato část ukazuje dva dotazy dvojčete zařízení. Dotazy dvojčete zařízení jsou dotazy podobné SQL, které vracejí sadu výsledků dvojčat zařízení.

Pokud chcete vytvořit dotaz na dvojče zařízení, zavolejte CreateQuery, odešlete SQL dotaz na dvojčata zařízení a získejte rozhraní IQuery. Volitelně můžete volat CreateQuery pomocí druhého parametru a zadat maximální počet položek na stránku.

Poté volejte metody GetNextAsTwinAsync nebo GetNextAsJsonAsync tolikrát, kolikrát je potřeba k načtení všech výsledků dvoučlenného objektu.

Rozhraní IQuery zahrnuje HasMoreResults booleanovou vlastnost, kterou můžete použít ke kontrole, zda je možné načíst více dvojčata výsledků.

Tento příklad dotazu vybere pouze dvojčata zařízení umístěná v závodu Redmond43 .

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

Tento ukázkový dotaz zpřesní první dotaz tak, aby vybral jenom zařízení připojená přes mobilní síť.

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

Ukázka služby SDK

Sada Azure IoT SDK pro .NET poskytuje funkční ukázku služební aplikace, která zpracovává úkoly dvojčat zařízení. Další informace naleznete v tématu Ukázka Správce registru.

  • Vyžaduje Java SE Development Kit 8. Ujistěte se, že jste v části Dlouhodobá podpora vybrali Javu 8 a přejděte ke stažení sady JDK 8.

Přehled

Tento článek popisuje, jak s využitím sady Azure IoT SDK pro Javu vytvořit aplikační kód pro přístrojové dvojčata a backendové služby.

Vytvoření aplikace zařízení

Aplikace zařízení můžou číst a zapisovat ohlášené vlastnosti dvojčete a dostávat oznámení o změnách požadovaných vlastností dvojčete, které jsou nastavené back-endovou aplikací nebo službou IoT Hub.

Tato část popisuje, jak vytvořit kód aplikace zařízení pro:

  • Načtení a zobrazení dvojčete zařízení
  • Aktualizace ohlášených vlastností dvojčete zařízení
  • Přihlášení k odběru změn požadovaných vlastností

Třída DeviceClient zveřejňuje všechny metody, které potřebujete k interakci s digitálními dvojčaty zařízení ze zařízení.

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Příkazy importu zařízení

Pro přístup k sadě Azure IoT SDK pro Javu použijte následující příkazy importu zařízení.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Připojení zařízení ke službě IoT Hub

Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:

  • Sdílený přístupový klíč
  • Certifikát X.509

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Ověřování pomocí sdíleného přístupového klíče

Připojení zařízení ke službě IoT Hub:

  1. K výběru přenosového protokolu použijte IotHubClientProtocol . Příklad:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Pomocí konstruktoru DeviceClient přidejte primární připojovací řetězec a protokol zařízení.

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

  3. K připojení zařízení k IoT Hubu použijte open . Pokud je klient již otevřený, metoda nic nedělá.

    client.open(true);

Ověřování pomocí certifikátu X.509

Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:

  1. Sestavte objekt SSLContext pomocí buildSSLContext.
  2. SSLContext Přidejte informace do objektu ClientOptions.
  3. Zavolejte DeviceClient pomocí ClientOptions informací a vytvořte připojení typu device-to-IoT Hub.

Tento příklad ukazuje hodnoty vstupních parametrů certifikátu jako místní proměnné pro přehlednost. V produkčním systému uložte citlivé vstupní parametry do proměnných prostředí nebo do jiného bezpečnějšího umístění úložiště. Například použijte Environment.GetEnvironmentVariable("PUBLICKEY") ke čtení proměnné prostředí obsahující řetězec certifikátu veřejného klíče.

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

Další informace o ověřování certifikátů najdete tady:

Ukázky kódu

Pracovní ukázky ověřování certifikátů X.509 zařízení najdete tady:

Načtení a zobrazení dvojčete zařízení

Po otevření připojení klienta zavolejte getTwin, abyste načetli aktuální vlastnosti dvojčete do objektu Twin.

Příklad:

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

Aktualizace ohlášených vlastností dvojčete zařízení

Po načtení aktuálního stavu dvojčete můžete začít provádět aktualizace nahlášených vlastností. Můžete také provádět aktualizace ohlášených vlastností bez získání aktuálního dvojčete, pokud máte správnou verzi ohlášených vlastností. Pokud odešlete ohlášené vlastnosti a zobrazí se chyba "předběžná podmínka selhala", znamená to, že verze vašich ohlášených vlastností je zastaralá. V takovém případě získáte nejnovější verzi opětovným voláním getTwin .

Aktualizace ohlášených vlastností:

  1. Pro volání getReportedProperties pro načtení ohlášených vlastností dvojčete do objektu TwinCollection.

  2. Použijte put k aktualizaci ohlášené vlastnosti v rámci objektuTwinCollection. Zavolejte put pro každou ohlášenou aktualizaci vlastností

  3. Pomocí updateReportedProperties použijte skupinu ohlášených vlastností, které byly aktualizovány pomocí put metody.

Příklad:

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

Přihlášení k odběru změn požadovaných vlastností

Zavolejte subscribeToDesiredProperties , abyste se přihlásili k odběru změn požadovaných vlastností. Tento klient obdrží zpětné volání s objektem Twin při každé aktualizaci požadované vlastnosti. Toto zpětné volání buď obsahuje úplnou sadu požadovaných vlastností, nebo pouze aktualizovanou požadovanou vlastnost v závislosti na tom, jak byla požadovaná vlastnost změněna.

Tento příklad se registruje pro sledování změn požadovaných vlastností. Všechny změny požadované vlastnosti jsou předány obslužné rutině s názvem DesiredPropertiesUpdatedHandler.

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

V tomto příkladu obslužná rutina pro změnu požadované vlastnosti volá DesiredPropertiesUpdatedHandler, aby načetla změny vlastností, a poté vytiskne aktualizované vlastnosti zařízení.

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

Ukázka zařízení sady SDK

Sada Azure IoT SDK pro Javu obsahuje funkční ukázku pro testování konceptů aplikací zařízení popsaných v tomto článku. Další informace naleznete v tématu Ukázka zařízení Twin.

Vytvoření back-endové aplikace

Tato část popisuje, jak vytvořit back-endovou aplikaci, která:

  • Aktualizace značek digitálního dvojčete zařízení.
  • Dotazuje se na zařízení pomocí filtrů se štítky a vlastnostmi.

Třída ServiceClientDeviceTwin obsahuje metody, které mohou služby použít pro přístup k dvojčatům zařízení.

Příkazy importu služby

Pro přístup k sadě Azure IoT SDK pro Javu použijte následující příkazy importu služby.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Pomocí konstruktoru DeviceTwin vytvořte připojení k IoT Hubu. Objekt DeviceTwin zpracovává komunikaci s centrem IoT.

Vaše aplikace potřebuje oprávnění k připojení služby ke změně požadovaných vlastností dvojčete zařízení a potřebuje oprávnění ke čtení registru pro dotazování registru identit. Neexistují žádné výchozí zásady sdíleného přístupu, které obsahují pouze tato dvě oprávnění, takže pokud ještě neexistuje, musíte ho vytvořit. Zadejte tento připojovací řetězec zásady sdíleného přístupu jako parametr pro fromConnectionString. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

DeviceTwinDevice objekt představuje dvojče zařízení s jeho vlastnostmi a značkami.

Příklad:

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Přehled ověřování s Javou v Azure SDK najdete v tématu Ověřování Azure s využitím Javy a Identity Azure.

Pro zjednodušení se tato část zaměřuje na popis ověřování pomocí tajného klíče klienta.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Údaje o federované identitě

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k zařízení a modulovým dvojčatům služby IoT Hub je například vyžadován IoT Hub Twin Contributor. Další informace naleznete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential. Nicméně se doporučuje v produkčním prostředí použít jiný způsob, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro Javu.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Přihlašovací údaje aplikace Microsoft Entra můžete ověřit pomocí defaultAzureCredentialBuilder. Uložte parametry připojení, například tenantID, klientID a hodnoty klientských tajných kódů, jako proměnné prostředí. Jakmile je TokenCredential vytvořen, předejte ho jako parametr 'credential' do ServiceClient nebo jiného tvůrce.

V tomto příkladu DefaultAzureCredentialBuilder se pokusí ověřit připojení ze seznamu popsaného v části DefaultAzureCredential. Výsledkem úspěšného ověřování Microsoft Entra je token zabezpečení, který je předán konstruktoru, jako ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Ověřování pomocí ClientSecretCredentialBuilder

Pomocí ClientSecretCredentialBuilder můžete vytvořit přihlašovací údaje pomocí tajných informací klienta. Pokud je tato metoda úspěšná, vrátí tokenCredential , který lze předat ServiceClient nebo jinému tvůrci jako parametr credential.

V tomto příkladu byly hodnoty tajného klíče klienta, ID klienta a ID tenanta přidány do proměnných prostředí v rámci registrace aplikace Microsoft Entra. Tyto proměnné prostředí ClientSecretCredentialBuilder se používají k sestavení přihlašovacích údajů.

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();
Jiné třídy ověřování

Sada Java SDK také obsahuje tyto třídy, které ověřují back-endovou aplikaci pomocí Microsoft Entra:

Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra najdete v ukázce ověřování na základě rolí.

Aktualizace polí dvojčat zařízení

Aktualizace polí dvojčat zařízení:

  1. Použijte getTwin pro načtení aktuálních polí dvojčete zařízení.

    Tento příklad načte a vytiskne pole dvojčat zařízení:

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

  2. Použijte objekt HashSet pro add skupinu párových značek dvojčat.

  3. Použití setTags k přidání skupiny párů značek z objektu tags do objektu DeviceTwinDevice

  4. Použití updateTwin k aktualizaci dvojčete v IoT Hubu

    Tento příklad aktualizuje značky zařízení dvojče pro region a zařízení dvojče.

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

Vytvořte dotaz dvojčete zařízení

Tato část ukazuje dva dotazy dvojčete zařízení. Dotazy dvojčete zařízení jsou dotazy podobné SQL, které vracejí sadu výsledků dvojčat zařízení.

Třída Query obsahuje metody, které lze použít k vytváření dotazů ve stylu SQL ve službě IoT Hub pro dvojčata, úlohy, úlohy zařízení nebo nezpracovaná data.

Chcete-li vytvořit dotaz zařízení:

  1. Použijte createSqlQuery k sestavení SQL dotazu dvojčat

  2. Spuštění dotazu pomocí queryTwin

  3. Pomocí hasNextDeviceTwin zkontrolujte, jestli ve sadě výsledků existuje další dvojče zařízení.

  4. Použijte getNextDeviceTwin k získání dalšího dvojčete zařízení ze sady výsledků.

Následující příklady dotazů vrátí maximálně 100 zařízení.

Tento příklad dotazu vybere pouze dvojčata zařízení umístěná v závodu Redmond43 .

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

Tento ukázkový dotaz zpřesní první dotaz tak, aby vybral jenom zařízení připojená přes mobilní síť.

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

Ukázka služby SDK

Sada Azure IoT SDK pro Java poskytuje funkční ukázku aplikace služby, která zpracovává úlohy digitálních dvojčat zařízení. Další informace naleznete v tématu Ukázka zařízení Twin.

  • Python SDK – Doporučuje se Python verze 3.7 nebo novější . Ujistěte se, že používáte 32bitovou, nebo 64bitovou instalaci podle požadavků vašeho nastavení. Po zobrazení výzvy v průběhu instalace nezapomeňte přidat Python do proměnné prostředí pro danou platformu.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Python vytvořit aplikaci zařízení a kód back-endové služby pro digitální dvojčata zařízení.

Instalace balíčků

Aby bylo možné vytvářet aplikace zařízení, musí být nainstalovaná knihovna azure-iot-device .

pip install azure-iot-device

Aby bylo možné vytvářet aplikace back-endové služby, musí být nainstalovaná knihovna azure-iot-hub .

pip install azure-iot-hub

Vytvoření aplikace zařízení

Aplikace zařízení můžou číst a zapisovat ohlášené vlastnosti dvojčete a dostávat oznámení o změnách požadovaných vlastností dvojčete, které jsou nastavené back-endovou aplikací nebo službou IoT Hub.

Třída IoTHubDeviceClient obsahuje metody, které lze použít k práci s dvojčaty zařízení.

Tato část popisuje, jak vytvořit kód aplikace zařízení, který:

  • Načte dvojče zařízení a prozkoumá ohlášené vlastnosti.
  • Oprava ohlášených vlastností dvojčete zařízení

Příkaz importu zařízení

Přidejte tento kód pro import IoTHubDeviceClient funkcí ze sady AZURE.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

Připojení zařízení ke službě IoT Hub

Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:

  • Sdílený přístupový klíč
  • Certifikát X.509

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Ověřování pomocí sdíleného přístupového klíče

Připojení zařízení ke službě IoT Hub:

  1. Voláním create_from_connection_string přidejte primární připojovací řetězec zařízení.
  2. Zavolejte connect k připojení klienta zařízení.

Příklad:

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

Ověřování pomocí certifikátu X.509

Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:

  1. Přidání parametrů certifikátu X.509 pomocí create_from_x509_certificate
  2. Zavolat connect pro připojení klienta zařízení

Tento příklad ukazuje hodnoty vstupních parametrů certifikátu jako místní proměnné pro přehlednost. V produkčním systému uložte citlivé vstupní parametry do proměnných prostředí nebo do jiného bezpečnějšího umístění úložiště. Použijte os.getenv("HOSTNAME") například ke čtení proměnné prostředí s názvem hostitele.

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

Další informace o ověřování certifikátů najdete tady:

Ukázky kódu

Pracovní ukázky ověřování certifikátů X.509 zařízení najdete v příkladech, jejichž názvy souborů končí na x509 ve scénářích Asynchronního centra.

Získat dvojče zařízení a prozkoumat nahlášené vlastnosti

Můžete načíst a prozkoumat informace o digitálních dvojčatech zařízení, včetně štítků a vlastností. Načtené informace o dvojčeti zařízení odpovídají datům ve formátu JSON dvojčete zařízení, která můžete zobrazit pro zařízení na webu Azure Portal.

Voláním get_twin získejte dvojče zařízení ze služby Azure IoT Hub. Informace o dvojčeti se umístí do proměnné, která se dá vytisknout nebo prozkoumat.

Tento příklad načte dvojče zařízení a pomocí print příkazu zobrazí dvojče zařízení ve formátu JSON.

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

Oprava ohlášených vlastností dvojčete zařízení

Opravu můžete použít k aktualizaci ohlášených vlastností zařízení ve formátu JSON.

Použití opravy pro aktualizaci ohlášených vlastností:

  1. Přiřaďte k proměnné opravu JSON ohlášené vlastnosti.
  2. Volání patch_twin_reported_properties , aby se oprava JSON použila na ohlášené vlastnosti. Toto je synchronní volání, což znamená, že tato funkce nevrací, dokud se oprava neodesílají do služby a nepotvrdí.

Pokud patch_twin_reported_properties vrátí chybu, tato funkce vyvolá odpovídající chybu.

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

Můžete také volat tyto metody pro aktualizaci dvojčat zařízení:

  • Voláním replace_twin nahraďte značky dvojčete zařízení a požadované vlastnosti.
  • Voláním update_twin aktualizujte značky dvojčat zařízení a požadované vlastnosti.

Obslužná rutina aktualizace požadovaných příchozích vlastností

Voláním on_twin_desired_properties_patch_received vytvořte obslužnou funkci nebo korutinu, která se volá při přijetí aktualizace požadovaných vlastností dvojčete. Zpracovatel přijímá jeden argument, což je aktualizační dvojče ve formě objektu slovníku JSON.

Tento příklad nastaví obslužnou rutinu opravy požadovaných vlastností s názvem twin_patch_handler.

Příklad:

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

twin_patch_handler přijímá aktualizace požadovaných vlastností JSON a vytiskne je.

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

Ukázky zařízení sady SDK

Sada Azure IoT SDK pro Python obsahuje následující ukázky:

  • get_twin – Připojte se k zařízení a načtěte informace o dvojčeti.
  • update_twin_reported_properties – Aktualizace ohlášených vlastností dvojčete
  • receive_twin_desired_properties – Příjem a aktualizace požadovaných vlastností

Vytvoření back-endové aplikace

Back-endová aplikace se připojí k zařízení přes IoT Hub a může číst hlášené a požadované vlastnosti zařízení, zapisovat požadované vlastnosti zařízení a spouštět dotazy na zařízení.

Tato část popisuje, jak vytvořit back-endovou aplikaci pro:

  • Aktualizace značek dvojčat a požadovaných vlastností
  • Dotazuje se na zařízení pomocí filtrů podle značek a vlastností.

Třída IoTHubRegistryManager zveřejňuje všechny metody potřebné k vytvoření back-endové aplikace pro interakci s dvojčaty zařízení ze služby.

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Připojte se ke službě IoT Hub pomocí from_connection_string. Vaše aplikace potřebuje oprávnění k připojení služby ke změně požadovaných vlastností dvojčete zařízení a potřebuje oprávnění ke čtení registru pro dotazování registru identit. Neexistují žádné výchozí zásady sdíleného přístupu, které obsahují pouze tato dvě oprávnění, takže pokud ještě neexistuje, musíte ho vytvořit. Zadejte tento připojovací řetězec zásady sdíleného přístupu jako parametr pro fromConnectionString. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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)

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Přehled ověřování sady Python SDK najdete v tématu Ověřování aplikací Pythonu ve službách Azure pomocí sady Azure SDK pro Python.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Údaje o federované identitě

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k zařízení a modulovým dvojčatům služby IoT Hub je například vyžadován IoT Hub Twin Contributor. Další informace naleznete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential. Nicméně se doporučuje v produkčním prostředí použít jiný způsob, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro Python.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tento balíček importu a odpovídající import příkaz:

pip install azure-identity

from azure.identity import DefaultAzureCredential

V tomto příkladu byly do proměnných prostředí přidány tajný klíč klienta z registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí používá DefaultAzureCredential pro ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra jsou přihlašovací údaje bezpečnostního tokenu, které jsou předávány způsobu připojení IoT Hubu.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Výsledný AccessToken se pak dá předat pro from_token_credential připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

from_token_credential vyžaduje dva parametry:

  • Adresa URL služby Azure – Adresa URL služby Azure by měla být ve formátu {Your Entra domain URL}.azure-devices.net bez předpony https:// . Například MyAzureDomain.azure-devices.net.
  • Token přihlašovacích údajů Azure

V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential. Adresa URL a přihlašovací údaje služby Azure jsou pak zadány pro IoTHubRegistryManager.from_token_credential, aby se vytvořilo připojení ke službě IoT Hub.

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)
Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra naleznete v tématu Microsoft Authentication Library (MSAL) pro Python.

Aktualizace značek dvojčat a požadovaných vlastností

Z back-endové aplikace můžete pomocí update_twin současně aktualizovat jak značky dvojčat zařízení, tak požadované vlastnosti.

  1. Zavolejte get_twin a získejte aktuální verzi dvojčete zařízení.
  2. Pomocí třídy Twin můžete přidat značky a vlastnosti ve formátu JSON.
  3. Zavolejte update_twin pro aplikaci aktualizace na dvojče zařízení. Také můžete použít replace_twin k nahrazení požadovaných vlastností a značek dvojčete zařízení.

Tento příklad aktualizuje informace značek region a plant a nastaví požadovanou vlastnost power_level na 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)

Vytvořit dotaz dvojčete zařízení

Informace o dvojčeti zařízení můžete získat pomocí dotazů na dvojče zařízení. Dotazy dvojčete zařízení jsou dotazy podobné SQL, které vracejí sadu výsledků dvojčat zařízení.

Jak použít dotaz na dvojče zařízení:

  1. K definování požadavku dotazu podobného SQL použijte objekt QuerySpecification.

  2. Pomocí query_iot_hub můžete dotazovat IoTHub a načíst informace o dvojčeti zařízení pomocí specifikace dotazu podobného SQL.

Tento příklad spouští dva dotazy. První vybere pouze dvojčata zařízení umístěná v Redmond43 továrně a druhý dotaz zpřesní, aby vybral pouze zařízení připojená přes mobilní síť. Výsledky se vytisknou po každém dotazu.

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

Ukázka služby SDK

Sada Azure IoT SDK pro Python poskytuje funkční příklad servisní aplikace, která zpracovává úlohy související s dvojčaty zařízení. Další informace naleznete v tématu Ukázka dotazu Správce registru.

  • Vyžaduje Node.js verze 10.0.x nebo novější.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Node.js vytvořit kód aplikace zařízení a back-endové služby pro dvojčata zařízení.

Vytvoření aplikace zařízení

Aplikace zařízení můžou číst a zapisovat ohlášené vlastnosti dvojčete a dostávat oznámení o změnách požadovaných vlastností dvojčete, které jsou nastavené back-endovou aplikací nebo službou IoT Hub.

Tato část popisuje, jak pomocí balíčku azure-iot-device v sadě Azure IoT SDK pro Node.js vytvořit aplikaci zařízení pro:

  • Načtení dvojčete zařízení a prozkoumání ohlášených vlastností
  • Aktualizace ohlášených vlastností dvojčete zařízení
  • Oznámení o změnách požadovaných na nemovitosti

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Instalace balíčku sady SDK pro zařízení

Spuštěním tohoto příkazu nainstalujte sadu SDK zařízení azure-iot-device na vývojový počítač:

npm install azure-iot-device --save

Připojení zařízení ke službě IoT Hub

Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:

  • Certifikát X.509
  • Sdílený přístupový klíč

Důležité

Tento článek obsahuje postup připojení zařízení pomocí sdíleného přístupového podpisu, označovaného také jako ověřování symetrického klíče. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování zařízení pomocí certifikátů X.509 je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení pro zabezpečení připojení řešení > IoT.

Ověřování pomocí certifikátu X.509

Certifikát X.509 je připojený k přenosu připojení typu device-to-IoT Hub.

Konfigurace připojení typu device-to-IoT Hub pomocí certifikátu X.509:

  1. Voláním fromConnectionString přidejte k objektu Client připojovací řetězec modulu zařízení nebo identity a typ přenosu. Přidejte x509=true do připojovacího řetězce, aby naznačilo, že se do DeviceClientOptions souboru přidá certifikát. Příklad:

    • Připojovací řetězec zařízení:

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

    • Modul identity připojovací řetězec:

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

  2. Nakonfigurujte proměnnou JSON s podrobnostmi o certifikátu a předejte ji do DeviceClientOptions.

  3. Zavolejte setOptions, abyste přidali certifikát a klíč X.509 (a volitelně i přístupové heslo) do klientského přenosu.

  4. Voláním otevřete připojení ze zařízení ke službě IoT Hub.

Tento příklad ukazuje informace o konfiguraci certifikátu v rámci proměnné JSON. Konfigurace clientOptions certifikace se předává setOptionsa připojení se otevře pomocí open.

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

Další informace o ověřování certifikátů najdete tady:

Ukázka kódu

Funkční ukázku ověřování certifikátů zařízení X.509 naleznete v tématu Jednoduchý ukázkový příklad zařízení X.509.

Ověřování pomocí sdíleného přístupového klíče

Balíček azure-iot-device obsahuje objekty, které komunikují se zařízeními IoT. Třída Twin obsahuje objekty specifické pro dvojčete. Tato část popisuje kód třídy Client, který slouží ke čtení a zápisu dat zařízení dvojčete.

Volba přenosového protokolu

Objekt Client podporuje tyto protokoly:

  • Amqp
  • Http– Při použití HttpClient instance kontroluje zprávy ze služby IoT Hub zřídka (minimálně každých 25 minut).
  • Mqtt
  • MqttWs
  • AmqpWs

Nainstalujte na svůj vývojový počítač potřebné přenosové protokoly.

Tento příkaz například nainstaluje Mqtt protokol:

npm install azure-iot-device-mqtt --save

Další informace o rozdílech mezi podporou MQTT, AMQP a HTTPS najdete v pokynech ke komunikaci typu Cloud-zařízení a volba komunikačního protokolu.

Vytvoření klientského modulu

Vytvořte Client modul pomocí nainstalovaného balíčku.

Příklad:

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

Vytvoření modulu protokolu

Vytvořte Protocol modul pomocí nainstalovaného přenosového balíčku.

Tento příklad přiřadí protokol MQTT:

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

Přidat připojovací řetězec zařízení a přenosový protokol

Zavolejte fromConnectionString pro zadání parametrů připojení zařízení.

  • connStr – připojovací řetězec, který zapouzdřuje oprávnění „device connect“ pro centrum IoT. Připojovací řetězec obsahuje název hostitele, ID zařízení a sdílený přístupový klíč v tomto formátu: HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
  • transportCtor - transportní protokol.

V tomto příkladu se používá přenosový Mqtt protokol:

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

Otevření připojení ke službě IoT Hub

Pomocí otevřené metody otevřete připojení mezi zařízením IoT a IoT Hubem. Slouží .catch(err) k zachycení chyby a spuštění kódu obslužné rutiny.

Příklad:

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

Načtení dvojčete zařízení a prozkoumání ohlášených vlastností

Volání metody getTwin k načtení aktuálních informací o dvojčeti zařízení do objektu Twin

Příklad:

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

Aktualizace ohlášených vlastností dvojčete zařízení

Aktualizace slouží k aktualizaci ohlášených vlastností zařízení. Zahrňte opravu ve formátu JSON jako první parametr a metodu zpětného volání stavu provádění funkce jako druhý parametr metody.

V tomto příkladu je v proměnné patch uložena oprava dvojčete zařízení ve formátu JSON. Oprava obsahuje aktualizaci hodnoty dvojčete zařízení connectivitycellular. Obslužná rutina opravy a chyby jsou předány metodě update . Pokud dojde k chybě, zobrazí se chybová zpráva konzoly.

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

Oznámení o změnách požadovaných na nemovitosti

Vytvořte naslouchač událostí pro aktualizaci požadované vlastnosti, který se spustí při změně vlastnosti v zařízení, tím, že předáte název metody handleru zpětného volání do twin.on.

Posluchač události požadované vlastnosti může mít jednu z následujících forem:

  • Příjem všech oprav pomocí jedné obslužné rutiny události
  • Přijměte událost, pokud se v rámci skupiny vlastností něco změní.
  • Přijetí události pro změnu jedné vlastnosti

Příjem všech oprav pomocí jedné obslužné rutiny události

Můžete vytvořit nasloucháč ke sledování změn libovolné vlastnosti.

Tento příklad kódu vypíše všechny vlastnosti přijaté ze služby.

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

Přijměte událost, pokud se v rámci skupiny vlastností něco změní.

Můžete vytvořit posluchače pro příjem události, pokud se něco změní v rámci skupiny vlastností.

Příklad:

  1. minTemperature A maxTemperature vlastnosti jsou umístěny ve skupině vlastností s názvem properties.desired.climate changes.

  2. Aplikace služby back-end použije tuto opravu k aktualizaci minTemperature a maxTemperature požadovaných vlastností.

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

  3. Tento kód nastaví posluchač události změny požadovaných vlastností, který se spustí při jakýchkoli změnách v rámci skupiny vlastností properties.desired.climate. Pokud se v této skupině změní požadovaná vlastnost, zobrazí se v konzole zprávy o minimální a maximální teplotě:

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

Přijetí události pro změnu jedné vlastnosti

Můžete nastavit posluchače pro změnu jediné vlastnosti. V tomto příkladu se kód pro tuto událost spustí pouze v případě, že je logická hodnota fanOn součástí aktualizace. Kód vypíše nový požadovaný fanOn stav pokaždé, když ji služba aktualizuje.

  1. Backendová aplikace aplikuje opravu této požadované vlastnosti:

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

  2. Naslouchací proces se aktivuje pouze v případech, kdy se fanOn vlastnost změní:

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

Ukázky sady SDK pro zařízení

Sada Azure IoT SDK pro Node.js obsahuje dvě ukázky dvojčat zařízení:

Vytvoření back-endové aplikace

Back-endová aplikace se připojí k zařízení přes IoT Hub a může číst hlášené a požadované vlastnosti zařízení, zapisovat požadované vlastnosti zařízení a spouštět dotazy na zařízení.

Tato část popisuje, jak vytvořit back-endovou aplikaci, která:

  • Načte a aktualizuje digitální dvojče zařízení.
  • Vytvoří dotaz digitálního dvojčete zařízení.

Instalace balíčku SDK služby

Spuštěním tohoto příkazu nainstalujte azure-iothub na vývojový počítač:

npm install azure-iothub --save

Třída Registry zveřejňuje všechny metody potřebné k interakci s dvojčaty zařízení z back-endové aplikace.

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Použijte fromConnectionString pro připojení ke službě IoT Hub. Vaše aplikace potřebuje oprávnění k připojení služby ke změně požadovaných vlastností dvojčete zařízení a potřebuje oprávnění ke čtení registru pro dotazování registru identit. Neexistují žádné výchozí zásady sdíleného přístupu, které obsahují pouze tato dvě oprávnění, takže pokud ještě neexistuje, musíte ho vytvořit. Zadejte tento připojovací řetězec zásady sdíleného přístupu jako parametr pro fromConnectionString. Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Přehled ověřování Node.js SDK najdete v těchto tématech:

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Údaje o federované identitě

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k zařízení a modulovým dvojčatům služby IoT Hub je například vyžadován IoT Hub Twin Contributor. Další informace naleznete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential. Nicméně se doporučuje v produkčním prostředí použít jiný způsob, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro JavaScript.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tento balíček:

npm install --save @azure/identity

V tomto příkladu byly do proměnných prostředí přidány tajný klíč klienta z registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí se používají DefaultAzureCredential k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra jsou přihlašovací údaje bezpečnostního tokenu, které jsou předávány způsobu připojení IoT Hubu.

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

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

Výsledný token přihlašovacích údajů lze poté předat funkci fromTokenCredential pro připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra.

fromTokenCredential vyžaduje dva parametry:

  • Adresa URL služby Azure – Adresa URL služby Azure by měla být ve formátu {Your Entra domain URL}.azure-devices.net bez předpony https:// . Například MyAzureDomain.azure-devices.net.
  • Token přihlašovacích údajů Azure

V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential. Adresa URL domény Azure a přihlašovací údaje se následně poskytnou Registry.fromTokenCredential pro vytvoření připojení ke službě IoT Hub.

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);
Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra najdete v příkladech identit Azure.

Načtení a aktualizace digitálního dvojčete zařízení

Můžete vytvořit opravu, která obsahuje aktualizace značek a požadovaných vlastností dvojčete zařízení.

Pro aktualizaci dvojčete zařízení:

  1. Zavolejte getTwin pro získání objektu dvojče zařízení.
  • Naformátujte opravu, která obsahuje aktualizaci dvojčete zařízení. Oprava je formátována ve formátu JSON, jak je popsáno ve třídě Twin. Oprava back-endové služby může obsahovat aktualizace značek a požadovaných vlastností. Další informace o formátu opravy naleznete v tématu Značky a formát vlastností.
  1. Zavolejte update pro aktualizaci dvojčete zařízení záplatou.

V tomto příkladu se načte dvojče zařízení pomocí myDeviceId a následně se na dvojčata použije oprava, která obsahuje aktualizaci značek locationregion: '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();
               }
             });
         }
     });

Vytvořit dotaz dvojčete zařízení

Můžete vytvořit dotazy na zařízení podobné SQL, které shromáždí informace z dvojčat zařízení.

Pomocí createQuery vytvořte dotaz, který lze spustit v instanci ioT Hubu a najít informace o zařízeních nebo úlohách.

createQuery zahrnuje dva parametry:

  • sqlQuery – dotaz napsaný jako řetězec SQL.
  • pageSize – požadovaný počet výsledků na stránku (volitelné. výchozí hodnota: 1000, max: 1 0000).

Pokud je zadán parametr pageSize, objekt dotazu obsahuje hasMoreResults logickou vlastnost, kterou můžete zkontrolovat, a použít metodu nextAsTwin k získání další stránky výsledků tolikrát, kolikrát je potřeba k načtení všech výsledků. Metoda next je k dispozici pro výsledky, které nejsou dvojčaty zařízení, například výsledky agregačních dotazů.

Tento příklad dotazu vybere jenom digitální dvojčata zařízení umístěná v továrně Redmond43.

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(','));
    }
});

Tento ukázkový dotaz upřesňuje první dotaz tak, aby vybral jenom zařízení připojená přes mobilní síť.

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(','));
    }
});
};

Ukázková sada SDK pro službu

Sada Azure IoT SDK pro Node.js poskytuje funkční ukázku služební aplikace, která zpracovává úlohy pro digitální dvojčata zařízení. Další informace najdete v tématu Back-endová služba pro dvojče zařízení – tento projekt slouží k odesílání aktualizací oprav dvojčete zařízení pro konkrétní zařízení.

  • Last updated on