Školení
Modul
Synchronizace služby Azure Digital Twins s daty zařízení IoT - Training
Nastavte tok dat ze simulovaného zařízení IoT do Služby Azure Digital Twins.
Tento prohlížeč se už nepodporuje.
Upgradujte na Microsoft Edge, abyste mohli využívat nejnovější funkce, aktualizace zabezpečení a technickou podporu.
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:
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 Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu pro vaše řešení.
V tomto článku se dozvíte, jak vyvíjet dva typy aplikací:
Poznámka
Tento článek je určený k doplnění ukázek sad SDK Azure IoT, na které odkazuje tento článek. Nástroje sady SDK můžete použít k sestavení zařízení i back-endových aplikací.
Služba IoT Hub
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).
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í.
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:
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;
Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:
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 Zabezpečení osvědčených postupů > zabezpečení připojení.
Třída DeviceClient zveřejňuje všechny metody potřebné k interakci s 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 CreateFromConnectionString
transportní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);
Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:
Pomocí DeviceAuthenticationWithX509Certificate vytvořte objekt, který obsahuje informace o zařízení a certifikátu. DeviceAuthenticationWithX509Certificate
je předán jako druhý parametr ( DeviceClient.Create
krok 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 auth
DeviceAuthenticationWithX509Certificate
, 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ě. Slouží Environment.GetEnvironmentVariable("HOSTNAME")
například ke čtení proměnné prostředí názvu 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:
Pracovní ukázky ověřování certifikátů X.509 zařízení najdete tady:
Zavolejte GetTwinAsync a načtěte aktuální vlastnosti dvojčete 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
, Tags
a Version
.
Tento příklad načte vlastnosti dvojčete zařízení a vytiskne hodnoty dvojčat 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é vlastnosti dvojčete:
TwinCollection
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í 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.
Toto volání například nastaví systém tak, aby upozorňovat metodu pojmenovanouOnDesiredPropertyChangedAsync
při každé změně požadované vlastnosti.
await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);
Vlastnosti dvojčete se předají metodě zpětného volání jako TwinCollection a lze je prozkoumat jako KeyValuePair
struktury.
Tento příklad obdrží aktualizace požadované vlastnosti jako a TwinCollection
pak prochází smyčky a vytiskne KeyValuePair
aktualizace kolekce. Po procházení KeyValuePair
kolekce volání UpdateReportedPropertiesAsync
kódu aktualizovat ohlášenou DateTimeLastDesiredPropertyChangeReceived
vlastnost tak, aby byl čas poslední aktualizace 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);
}
Sada Azure IoT SDK pro .NET poskytuje funkční ukázku aplikace zařízení, která zpracovává úlohy dvojčat zařízení. Další informace najdete v tématu TwinSample.
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:
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.
Aplikace back-endových služeb vyžadují balíček NuGet Microsoft.Azure.Devices .
Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:
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í cloudu.
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 tuto zásadu sdíleného přístupu připojovací řetězec jako parametr .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);
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.
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í:
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 dvojčatům modulů služby IoT Hub je například potřeba přispěvatel dvojčete služby IoT Hub. Další informace najdete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení role Azure RBAC.
Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.
Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential
nebo pared-down 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í DefaultAzureCredential
pro 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:
using Azure.Core;
using Azure.Identity;
V tomto příkladu se do proměnných prostředí přidá tajný klíč klienta 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 je přihlašovací údaje tokenu zabezpečení předávané metodě 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 TokenCredential
se předá objekt ServiceClient.Create
připojení ServiceClient 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 TokenCredential
se předá k RegistryManager.Create
vytvoření objektu RegistryManager .
string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Funkční ukázka ověřování služby Microsoft Entra najdete v ukázce ověřování na základě rolí.
Aktuální pole dvojčete zařízení můžete načíst do objektu Twin voláním GetTwinAsync.
Třída Twin
obsahuje vlastnosti , které odpovídají každé části dvojčete zařízení. Twin
Vlastnosti třídy slouží k zobrazení a aktualizaci polí dvojčete 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 dvojčete zavolejte UpdateTwinAsync a zapište Twin
aktualizace polí objektů zpět do zařízení. Použití try
a catch
logika spojená s obslužnou rutinou chyby k zachycení nesprávně formátovaných chyb oprav z UpdateTwinAsync
.
Ke čtení a zápisu informací o značkách zařízení použijte vlastnost Značky dvojčete zařízení.
Tento příklad vytvoří location
opravu značky, přiřadí ji k objektu Twin
pomocí Tags
vlastnosti 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);
}
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á.
Tato ukázková volání GetTwinAsync
pro načtení aktuálních polí dvojčete zařízení do objektu Twin
, vytvoří opravu ve tag
formátu JSON s informacemi o umístění v oblasti a umístění zařízení a potom voláním UpdateTwinAsync
této opravy aktualizují dvojče 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);
}
Ke čtení a zápisu požadovaných vlastností zařízení použijte vlastnost TwinProperties.Desired dvojčete zařízení. Aktualizujte vlastnosti dvojčete Desired
pomocí opravy ve formátu JSON.
Tato ukázková volání GetTwinAsync
načtou aktuální pole dvojčete zařízení do objektu Twin
, aktualizuje požadovanou vlastnost dvojčete speed
a potom volání UpdateTwinAsync
, která použijí Twin
objekt pro 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);
Aktualizace dvojčat můžete použít také pomocí těchto metod sady SDK:
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 dvojčete zařízení, zavolejte CreateQuery a odešlete dotaz SQL dvojčat 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.
Další volání GetNextAsTwinAsync
nebo GetNextAsJsonAsync
metoda tolikrát, kolikrát je potřeba k načtení všech výsledků dvojčete.
Rozhraní IQuery
zahrnuje HasMoreResults boolean vlastnost, kterou můžete použít ke kontrole, zda existují více výsledků dvojčete k načtení.
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)));
Sada Azure IoT SDK pro .NET poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčat zařízení. Další informace naleznete v tématu Ukázka Správce registru.
Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Javu vytvořit kód aplikace zařízení a back-endové služby pro dvojčata 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:
Třída DeviceClient zveřejňuje všechny metody, které potřebujete k interakci s 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 Zabezpečení osvědčených postupů > zabezpečení připojení.
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.*;
Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:
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 Zabezpečení osvědčených postupů > zabezpečení připojení.
Připojení zařízení ke službě IoT Hub:
K výběru přenosového protokolu použijte IotHubClientProtocol . Příklad:
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
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);
K připojení zařízení k IoT Hubu použijte open . Pokud je klient již otevřený, metoda nic nedělá.
client.open(true);
Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:
SSLContext
Přidejte informace do objektu ClientOptions.ClientOptions
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ě. Slouží Environment.GetEnvironmentVariable("PUBLICKEY")
například ke čtení proměnné prostředí řetězce 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:
Pracovní ukázky ověřování certifikátů X.509 zařízení najdete tady:
Po otevření připojení klienta volání getTwin načtěte vlastnosti aktuálního 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);
Po načtení aktuálního dvojčete můžete začít provádět aktualizace ohláš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", je verze ohlášených vlastností zadaná. V takovém případě získáte nejnovější verzi opětovným voláním getTwin
.
Aktualizace ohlášených vlastností:
Volání getReportedProperties načtení ohlášených vlastností dvojčete do TwinCollection objektu.
Slouží k aktualizaci ohlášené vlastnosti v rámci objektuTwinCollection
. Volání put
pro každou ohlášenou aktualizaci vlastností
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);
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 přihlásí k odběru 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 DesiredPropertiesUpdatedHandler
požadovaná vlastnost změnit volání zpět obslužné rutiny volání getDesiredProperties načíst změny vlastnosti a pak vytiskne aktualizované vlastnosti dvojčete.
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);
}
}
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 dvojčete zařízení.
Tato část popisuje, jak vytvořit back-endovou aplikaci, která:
Třída ServiceClient
DeviceTwin obsahuje metody, které mohou služby použít pro přístup k dvojčatům zařízení.
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;
Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:
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í cloudu.
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 tuto zásadu sdíleného přístupu připojovací řetězec jako parametr .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);
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í v sadě Java 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.
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í:
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 dvojčatům modulů služby IoT Hub je například potřeba přispěvatel dvojčete služby IoT Hub. Další informace najdete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení role Azure RBAC.
Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.
Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential
nebo pared-down ChainedTokenCredential
.
Další informace o výhodách a nevýhodách použití DefaultAzureCredential
najdete 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í, jako jsou id tenanta tajného klíče klienta, ID klienta a hodnoty tajných kódů klienta, jako jsou proměnné prostředí. Po vytvoření ho TokenCredential
předejte ServiceClient nebo jinému tvůrci jako parametr credential.
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 přihlašovací údaje tokenu zabezpečení předávané konstruktoru, jako je ServiceClient.
TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
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 do proměnných prostředí přidány hodnoty klienta registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí se používají ClientSecretCredentialBuilder
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();
Sada Java SDK také obsahuje tyto třídy, které ověřují back-endovou aplikaci pomocí Microsoft Entra:
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í:
Načtení aktuálních polí dvojčete zařízení pomocí getTwinu
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);
Použití objektu HashSet
ke add
skupině párů značek dvojčat
Použití setTags k přidání skupiny párů značek z objektu tags
do objektu DeviceTwinDevice
Použití updateTwin k aktualizaci dvojčete v IoT Hubu
Tento příklad aktualizuje značky dvojčat zařízení v oblasti a zařízení pro dvojče zařízení:
// 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);
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.
Vytvoření dotazu zařízení:
Použití createSqlQuery k sestavení dotazu SQL dvojčat
Spuštění dotazu pomocí queryTwin
Pomocí hasNextDeviceTwin zkontrolujte, jestli ve sadě výsledků existuje další dvojče zařízení.
Použití getNextDeviceTwin k načtení 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());
}
Sada Azure IoT SDK pro Javu poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčat zařízení. Další informace naleznete v tématu Ukázka dvojčete zařízení.
Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Python vytvořit kód aplikace zařízení a back-endové služby pro dvojčata zařízení.
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
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ý:
Přidejte tento kód pro import IoTHubDeviceClient
funkcí ze sady AZURE.iot.device SDK.
from azure.iot.device import IoTHubDeviceClient
Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:
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 Zabezpečení osvědčených postupů > zabezpečení připojení.
Připojení zařízení ke službě IoT Hub:
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()
Připojení zařízení ke službě IoT Hub pomocí certifikátu X.509:
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ě. Slouží os.getenv("HOSTNAME")
například ke čtení proměnné prostředí názvu 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:
Pracovní ukázky ověřování certifikátů X.509 zařízení najdete v příkladech, jejichž názvy souborů končí ve scénářích centra Async.
Můžete načíst a prozkoumat informace o dvojčeti zařízení, včetně značek 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))
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í:
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 on_twin_desired_properties_patch_received vytvořte funkci obslužné rutiny nebo korutinu, která se volá při přijetí opravy požadovaných vlastností dvojčete. Obslužná rutina přebírá jeden argument, což je oprava dvojčete 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()
Přijme twin_patch_handler
a vytiskne aktualizace požadované vlastnosti JSON.
# Define behavior for receiving twin desired property patches
def twin_patch_handler(twin_patch):
print("Twin patch received:")
print(twin_patch)
Sada Azure IoT SDK pro Python obsahuje následující ukázky:
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:
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.
Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:
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í cloudu.
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 tuto zásadu sdíleného přístupu připojovací řetězec jako parametr .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)
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.
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í:
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 dvojčatům modulů služby IoT Hub je například potřeba přispěvatel dvojčete služby IoT Hub. Další informace najdete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení role Azure RBAC.
Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.
Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential
nebo pared-down 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í DefaultAzureCredential
najdete 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 se do proměnných prostředí přidal tajný klíč klienta 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 je přihlašovací údaje tokenu zabezpečení předávané metodě 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:
{Your Entra domain URL}.azure-devices.net
bez předpony https://
. Například MyAzureDomain.azure-devices.net
.V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential
. Adresu URL a přihlašovací údaje služby Azure se pak zadají k IoTHubRegistryManager.from_token_credential
vytvoření 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)
Pracovní ukázky ověřování služby Microsoft Entra naleznete v tématu Microsoft Authentication Library (MSAL) pro Python.
Pomocí update_twin můžete aktualizovat značky dvojčat zařízení i požadované vlastnosti z back-endové aplikace.
update_twin
pro použití opravy na dvojče zařízení K nahrazení požadovaných vlastností a značek dvojčete zařízení můžete použít také replace_twin .Tento příklad aktualizuje region
a plant
označí informace a nastaví power_level
požadovanou vlastnost 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)
Informace o dvojčeti zařízení můžete dotazovat pomocí dotazů dvojčete zařízení. Dotazy dvojčete zařízení jsou dotazy podobné SQL, které vracejí sadu výsledků dvojčat zařízení.
Použití dotazu dvojčete zařízení:
K definování požadavku dotazu podobného SQL použijte objekt QuerySpecification.
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 jenom dvojčata zařízení umístěná v Redmond43
zařízení a druhý dotaz zpřesní a vybere jenom 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()
Sada Azure IoT SDK pro Python poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčat zařízení. Další informace naleznete v tématu Ukázka dotazu Správce registru.
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í.
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:
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 Zabezpečení osvědčených postupů > zabezpečení připojení.
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
Aplikace zařízení se může ověřit ve službě IoT Hub pomocí následujících metod:
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 Zabezpečení osvědčených postupů > zabezpečení připojení.
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:
Voláním zConnectionString přidejte modul zařízení nebo identity připojovací řetězec a typ přenosu do objektuClient
. Přidejte x509=true
do připojovací řetězec, aby bylo možné označit, ž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
Nakonfigurujte proměnnou JSON s podrobnostmi o certifikátu a předejte ji do DeviceClientOptions.
Volání setOptions pro přidání certifikátu a klíče X.509 (a volitelně i přístupového hesla) do přenosu klienta.
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á setOptions
a 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:
Funkční ukázka ověřování certifikátu X.509 zařízení najdete v tématu Jednoduché ukázkové zařízení X.509.
Balíček zařízení azure-iot-device obsahuje objekty, které jsou rozhraní se zařízeními IoT. Třída Twin obsahuje objekty specifické pro dvojčete. Tato část popisuje Client
kód třídy, který slouží ke čtení a zápisu dat dvojčete zařízení.
Objekt Client
podporuje tyto protokoly:
Amqp
Http
– Při použití Http
Client
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řte Client
modul pomocí nainstalovaného balíčku.
Příklad:
const Client = require('azure-iot-device').Client;
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;
Volání zConnectionString pro zadání parametrů připojení zařízení:
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);
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);
});
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 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 patch
proměnné uložena oprava dvojčete zařízení ve formátu JSON. Oprava obsahuje hodnotu cellular
aktualizace dvojčete connectivity
zařízení . 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();
}
});
Vytvořte naslouchací proces aktualizace požadované vlastnosti, který se spustí při změně požadované vlastnosti v zařízení předáním názvu metody obslužné rutiny zpětného volání twin.on.
Naslouchací proces události požadované vlastnosti může mít jednu z následujících forem:
Můžete vytvořit naslouchací proces pro příjem jakékoli změny požadované 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));
});
Pokud se něco pod seskupováním vlastností změní, můžete vytvořit naslouchací proces pro příjem události.
Příklad:
maxTemperature
A minTemperature
vlastnosti jsou umístěny ve skupině vlastností s názvem properties.desired.climate changes
.
Aplikace back-endové služby tuto opravu použije k aktualizaci minTemperature
a maxTemperature
požadovaným vlastnostem:
const twinPatch1 = {
properties: {
desired: {
climate: { minTemperature: 68, maxTemperature: 76, },
},
},
};
Tento kód nastaví naslouchací proces změny požadovaných vlastností, který aktivuje všechny změny v rámci properties.desired.climate
seskupení vlastností. 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);
}
});
Naslouchací proces můžete nastavit pro změnu jedné vlastnosti. V tomto příkladu se kód pro tuto událost spustí pouze v případě, že fanOn
je logická hodnota součástí opravy. Kód vypíše nový požadovaný fanOn
stav pokaždé, když ji služba aktualizuje.
Back-endová aplikace použije tuto opravu požadované vlastnosti:
const twinPatch2 = {
properties: {
desired: {
climate: {
hvac: {
systemControl: { fanOn: true, },
},
},
},
},
};
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);
});
Sada Azure IoT SDK pro Node.js obsahuje dvě ukázky dvojčat zařízení:
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á:
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.
Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:
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í cloudu.
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 tuto zásadu sdíleného přístupu připojovací řetězec jako parametr .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);
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:
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í:
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 dvojčatům modulů služby IoT Hub je například potřeba přispěvatel dvojčete služby IoT Hub. Další informace najdete v tématu Správa přístupu ke službě IoT Hub pomocí přiřazení role Azure RBAC.
Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.
Nejjednodušší způsob, jak použít Microsoft Entra k ověření back-endové aplikace, je použít DefaultAzureCredential, ale doporučuje se použít jinou metodu v produkčním prostředí, včetně konkrétní TokenCredential
nebo pared-down 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í DefaultAzureCredential
najdete 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 se do proměnných prostředí přidal tajný klíč klienta 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 je přihlašovací údaje tokenu zabezpečení předávané metodě 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ů se pak dá předat zTokenCredential 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:
{Your Entra domain URL}.azure-devices.net
bez předpony https://
. Například MyAzureDomain.azure-devices.net
.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 pak zadají k Registry.fromTokenCredential
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);
Pracovní ukázky ověřování služby Microsoft Entra najdete v příkladech identit Azure.
Můžete vytvořit opravu, která obsahuje aktualizace značek a požadovaných vlastností dvojčete zařízení.
Aktualizace dvojčete zařízení:
V tomto příkladu se načte myDeviceId
dvojče zařízení a pak se na dvojčata, která obsahuje location
aktualizaci region: 'US', plant: 'Redmond43'
značek, použije oprava .
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();
}
});
}
});
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:
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ů dvojčete tolikrát, kolikrát je potřeba k načtení všech výsledků. Volána next
metoda 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 dvojčata zařízení umístěná Redmond43
v zařízení.
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(','));
}
});
};
Sada Azure IoT SDK pro Node.js poskytuje funkční ukázku aplikace služby, která zpracovává úlohy dvojčat zařízení. Další informace najdete v tématu Back-endová služba dvojčete zařízení – tento projekt slouží k odesílání aktualizací oprav dvojčete zařízení pro konkrétní zařízení.
Školení
Modul
Synchronizace služby Azure Digital Twins s daty zařízení IoT - Training
Nastavte tok dat ze simulovaného zařízení IoT do Služby Azure Digital Twins.