Začínáme s dvojčaty zařízení

Článek
12/04/2024

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

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 dvojčat zařízení, nastavit nové požadované vlastnosti a dotazovat se na zařízení na základě hodnot dvojčat zařízení.

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

Požadavky

IoT Hub. Některá volání sady SDK vyžadují primární připojovací řetězec ioT Hubu, proto si poznamenejte připojovací řetězec.
Registrované zařízení. Některá volání sady SDK vyžadují primární připojovací řetězec zařízení, proto si poznamenejte připojovací řetězec.
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).
Požadavky sady Language SDK:
- .NET SDK – Vyžaduje Visual Studio.
- Doporučuje se python sdk - 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 konkrétní platformu.
- Java – vyžaduje Sadu 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.
- Node.js – vyžaduje Node.js verze 10.0.x nebo novější.

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 zpětného volání aktualizace požadované vlastnosti

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řidání balíčku NuGet zařízení

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

Připojení k zařízení

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

Načtení dvojčete zařízení a prozkoumání vlastností

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, Tagsa 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ých vlastností dvojčete zařízení

Aktualizace ohlášené vlastnosti dvojčete:

Vytvoření objektu TwinCollection pro aktualizaci ohlášené vlastnosti
Aktualizace jedné nebo více ohlášených vlastností v rámci objektu TwinCollection
Použití UpdateReportedPropertiesAsync k nabízení 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ření obslužné rutiny zpětného volání aktualizace 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.

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

Ukázka zařízení sady SDK

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.

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ření dotazu 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í balíčku NuGet služby

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

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

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

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.

Ověřování pomocí DefaultAzureCredential

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

Ukázka kódu

Funkční ukázka 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 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.

Č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 dvojčete zařízení.

Aktualizace značek pomocí objektu dvojčete

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

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

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

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

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

Jiné metody aktualizace dvojčete

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

Voláním metody ReplaceTwinAsync nahraďte celé dvojče zařízení.
Zavolejte UpdateTwins2Async a aktualizujte seznam dvojčat vytvořených v systému.

Vytvoření dotazu 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 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.

GetNextAsTwinAsync k načtení dalšího stránkovaného výsledku jako objekty Twin .
GetNextAsJsonAsync k načtení dalšího stránkovaného výsledku jako řetězců JSON.

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

Ukázka služby SDK

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.

Přehled

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

Vytvoření aplikace zařízení

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 dvojčaty zařízení ze zařízení.

Důležité

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í k zařízení

Připojení k zařízení:

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

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

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

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

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

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 dvojčete zařízení.

Vytvoření back-endové aplikace

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

Aktualizuje značky dvojčat zařízení.
Dotazuje se na zařízení pomocí filtrů na značky a vlastnosti.

Třída ServiceClient DeviceTwin 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é

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

Připojení pomocí Microsoft Entra

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.

Konfigurace aplikace Microsoft Entra

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

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

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

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

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

Vytvoření dotazu 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.

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

Ukázka služby SDK

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

Přehled

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

Vytvoření aplikace zařízení

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í

Důležité

Připojení k zařízení

Tato část ukazuje, jak připojit aplikaci k zařízení pomocí primárního klíče zařízení, který obsahuje sdílený přístupový klíč.

Připojení aplikace k zařízení:

Volání create_from_connection_string pro přidání připojovací řetězec zařízení
Volání připojení pro připojení klienta zařízení k centru Azure IoT

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

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

# connect the application to the device
await device_client.connect()

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

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

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

Přiřaďte k proměnné opravu JSON ohlášené vlastnosti.
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čat 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 opravy příchozích požadovaných vlastností

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)

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

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ů na značky a vlastnosti.

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é

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

Připojení pomocí Microsoft Entra

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

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

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, 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í DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro Python.

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:

IoTHubRegistryManager k vytvoření připojení služby ke službě IoT Hub pomocí přihlašovacích údajů tokenu Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

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

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í

Pomocí update_twin můžete aktualizovat značky dvojčat zařízení i požadované vlastnosti z back-endové aplikace.

Zavolejte get_twin a získejte aktuální verzi dvojčete zařízení.
Pomocí třídy Twin můžete přidat značky a vlastnosti ve formátu JSON.
Volání 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)

Vytvoření dotazu dvojčete zařízení

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

Ukázka služby SDK

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.

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í

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 vlastností

Důležité

Instalace balíčků SADY SDK

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

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

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řidání připojovací řetězec zařízení a přenosového protokolu

Volání zConnectionString 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 patch proměnné uložena oprava dvojčete zařízení ve formátu JSON. Oprava obsahuje hodnotu cellularaktualizace 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();
      }
  });

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

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:

Příjem všech oprav pomocí jedné obslužné rutiny události
Přijetí události, pokud se v seskupování 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 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));
});

Přijetí události, pokud se v seskupování vlastností něco změní

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

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

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

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

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

Načte a aktualizuje dvojče zařízení.
Vytvoří dotaz dvojčete zařízení.

Instalace balíčků sady 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é

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

Připojení pomocí Microsoft Entra

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

Konfigurace aplikace Microsoft Entra

Tajný klíč klienta
Certifikát
Přihlašovací údaje federované identity

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, 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í DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro JavaScript.

Microsoft Entra vyžaduje tento balíček:

npm install --save @azure/identity

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:

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

Ukázky kódu

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

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

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

Aktualizace dvojčete zařízení:

Volání getTwin pro načtení objektu dvojčete 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í.

Aktualizace volání pro aktualizaci dvojčete zařízení opravou

V tomto příkladu se načte myDeviceIddvojč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();
               }
             });
         }
     });

Vytvoření dotazu 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ů 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(','));
    }
});
};

Ukázka sady SDK služby

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

Sdílet prostřednictvím

Začínáme s dvojčaty zařízení

Požadavky

Přehled

Vytvoření aplikace zařízení

Přidání balíčku NuGet zařízení

Připojení k zařízení

Načtení dvojčete zařízení a prozkoumání vlastností

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

Vytvoření obslužné rutiny zpětného volání aktualizace požadované vlastnosti

Ukázka zařízení sady SDK

Vytvoření back-endové aplikace

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

Připojení ke službě IoT Hub

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

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ukázka kódu

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

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

Aktualizace značek pomocí objektu dvojčete

Aktualizace značek pomocí řetězce JSON

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

Jiné metody aktualizace dvojčete

Vytvoření dotazu dvojčete zařízení

Ukázka služby SDK

Přehled

Vytvoření aplikace zařízení

Příkazy importu zařízení

Připojení k zařízení

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í

Ukázka zařízení sady SDK

Vytvoření back-endové aplikace

Příkazy importu služby

Připojení ke službě IoT Hub

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

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ověřování pomocí ClientSecretCredentialBuilder

Jiné třídy ověřování

Ukázky kódu

Aktualizace polí dvojčat zařízení

Vytvoření dotazu dvojčete zařízení

Ukázka služby SDK

Přehled

Vytvoření aplikace zařízení

Připojení k zařízení

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

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

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

Ukázky zařízení sady SDK

Vytvoření back-endové aplikace

Připojení ke službě IoT Hub

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

Připojení pomocí Microsoft Entra

Konfigurace aplikace Microsoft Entra

Ověřování pomocí DefaultAzureCredential

Ukázky kódu

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

Vytvoření dotazu dvojčete zařízení

Ukázka služby SDK

Přehled

Vytvoření aplikace zařízení

Instalace balíčků SADY SDK

Volba přenosového protokolu

Vytvoření klientského modulu

Vytvoření modulu protokolu

Přidání připojovací řetězec zařízení a přenosového protokolu

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

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 vlastností

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

Přijetí události, pokud se v seskupování vlastností něco změní

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

Ukázky sady SDK pro zařízení