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

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

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:

1. Vytvoření objektu TwinCollection pro aktualizaci ohlášené vlastnosti
2. Aktualizace jedné nebo více ohlášených vlastností v rámci objektu TwinCollection
3. Použ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:

• Připojení k zařízení prostřednictvím IoT Hubu
• 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í.

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.

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í

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

Připojte back-endovou aplikaci k zařízení pomocí createFromConnectionString. Jako parametr zadejte službu IoT Hub připojovací řetězec, kterou jste vytvořili v části Požadavky.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

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

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

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

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

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

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

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

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

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

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

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

   client.open(true);
   

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

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

2. Slouží k aktualizaci ohlášené vlastnosti v rámci objektuTwinCollection. Volání put pro každou ohlášenou aktualizaci vlastností

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

Příklad:

TwinCollection reportedProperties = twin.getReportedProperties();

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

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

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

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

Tento příklad se 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í k klientovi služby IoT Hub

Připojení ke službě IoT Hub za účelem zobrazení a aktualizace informací o dvojčeti zařízení:

1. Vytvořte objekt DeviceTwinClientOptions . Nastavte všechny možnosti potřebné pro vaši aplikaci. Tyto možnosti se předají objektu DeviceTwin .
2. Pomocí konstruktoru DeviceTwin vytvořte připojení k IoT Hubu. Objekt DeviceTwin zpracovává komunikaci s centrem IoT. Jako parametry zadejte službu IoT Hub připojovací řetězec, kterou jste vytvořili v části Požadavky a objektuDeviceTwinClientOptions.
3. DeviceTwinDevice objekt představuje dvojče zařízení s jeho vlastnostmi a značkami.

Příklad:

public static final String iotHubConnectionString = "{IoT hub service 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
DeviceTwinClientOptions twinOptions = new DeviceTwinClientOptions();
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString,twinOptions);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Aktualizace polí dvojčat zařízení

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

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

2. Použití objektu HashSet ke add skupině párů značek dvojčat

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

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

   Tento příklad aktualizuje značky 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í:

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

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

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

4. Použ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í

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

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

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

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

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

1. Volání create_from_connection_string pro přidání připojovací řetězec zařízení
2. 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í:

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

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

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

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

• Voláním replace_twin nahraďte značky dvojč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

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

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

• Aktualizace značek dvojčat a požadovaných vlastností
• Dotazuje se na zařízení pomocí filtrů 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

Připojte se ke službě IoT Hub pomocí from_connection_string. Jako parametr zadejte službu IoT Hub připojovací řetězec, kterou jste vytvořili v části Požadavky.

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)

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.

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

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

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

Tento příklad spouští dva dotazy. První vybere 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í

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

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

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

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:

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

2. 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, },
       },
     },
    };
   

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

1. Back-endová aplikace použije tuto opravu požadované vlastnosti:

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

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

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

Ukázky sady SDK pro zařízení

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

• Jednoduché ukázkové dvojče zařízení

• Jednoduché ukázkové dvojče zařízení se SAS

Vytvoření back-endové aplikace

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

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

• Načte a aktualizuje 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

Použijte fromConnectionString pro připojení ke službě IoT Hub. Jako parametr zadejte službu IoT Hub připojovací řetězec, kterou jste vytvořili v části Požadavky.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

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

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

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