Kom igång med enhetstvillingar

Använd Azure IoT Hub-enhetens SDK och tjänst-SDK för att utveckla program som hanterar vanliga uppgifter för enhetstvillingar. Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, inklusive metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

Du kan använda enhetstvillingar för att:

• Lagra enhetsmetadata från lösningens serverdel
• Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används från din enhetsapp
• Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp
• Fråga efter enhetens metadata, konfiguration eller tillstånd

Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå och använda enhetstvillingar i IoT Hub.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Den här artikeln visar hur du utvecklar två typer av program:

• Enhetsappar kan hantera begäranden om att uppdatera önskade egenskaper och svara med ändringar i rapporterade egenskaper.
• Tjänstappar kan uppdatera taggar för enhetstvillingar, ange nya önskade egenskaper och fråga enheter baserat på enhetstvillingvärden.

Kommentar

Den här artikeln är avsedd att komplettera Azure IoT SDK-exempel som refereras inifrån den här artikeln. Du kan använda SDK-verktyg för att skapa både enhets- och serverdelsprogram.

Förutsättningar

• En IoT-hubb. Vissa SDK-anrop kräver den primära IoT Hub-anslutningssträng, så anteckna anslutningssträng.

• En registrerad enhet. Vissa SDK-anrop kräver enhetens primära anslutningssträng, så anteckna anslutningssträng.

• IoT Hub-tjänst anslutningssträng

  I den här artikeln skapar du en serverdelstjänst som lägger till önskade egenskaper till en enhetstvilling och sedan frågar identitetsregistret för att hitta alla enheter med rapporterade egenskaper som har uppdaterats i enlighet med detta. Tjänsten behöver behörigheten för tjänstanslutning för att ändra önskade egenskaper för en enhetstvilling, och den behöver registerläsningsbehörighet för att köra frågor mot identitetsregistret. Det finns ingen standardprincip för delad åtkomst som bara innehåller dessa två behörigheter, så du måste skapa en.

  Följ dessa steg för att skapa en princip för delad åtkomst som beviljar behörigheter för tjänstanslutning och registerläsning och få en anslutningssträng för den här principen:

  1. I Azure Portal väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.

  2. I den vänstra rutan i hubben väljer du Principer för delad åtkomst.

  3. Välj Lägg till princip för delad principåtkomst på den översta menyn ovanför listan med principer.

  4. I fönstret Lägg till princip för delad åtkomst till höger anger du ett beskrivande namn för principen, till exempel "serviceAndRegistryRead". Under Behörigheter väljer du Registerläsning och Service Connect och sedan Lägg till.

  5. Välj din nya princip i listan över principer.

  6. Välj kopieringsikonen för den primära anslutningssträng och spara värdet.

  Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

• Om ditt program använder MQTT-protokollet kontrollerar du att port 8883 är öppen i brandväggen. MQTT-protokollet kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

• Språk-SDK-krav:

  • .NET SDK – kräver Visual Studio.
  • Python SDK - Python version 3.7 eller senare rekommenderas. Se till att använda en 32-bitars eller 64-bitars installation beroende på vad som krävs för din konfiguration. Se till att du lägger till Python i den plattformsspecifika miljövariabeln när du uppmanas att göra det under installationen.
  • Java – kräver Java SE Development Kit 8. Se till att du väljer Java 8 under Långsiktigt stöd för att gå till nedladdningar för JDK 8.
  • Node.js – Kräver Node.js version 10.0.x eller senare.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för .NET för att skapa programkod för enhet och serverdelstjänst för enhetstvillingar.

Skapa ett enhetsprogram

Enhetsprogram kan läsa och skriva tvillingrapporterade egenskaper och meddelas om önskade ändringar av tvillingegenskapen som anges av ett serverdelsprogram eller IoT Hub.

I det här avsnittet beskrivs hur du använder enhetsprogramkod för att:

• Hämta en enhetstvilling och granska rapporterade egenskaper
• Uppdatera rapporterade egenskaper för enhetstvillingar
• Skapa en önskad egenskapsuppdateringsanropshanterare

Lägg till nuget-enhetspaket

Enhetsklientprogram som skrivits i C# kräver NuGet-paketet Microsoft.Azure.Devices.Client .

Ansluta till en enhet

Klassen DeviceClient visar alla metoder som krävs för att interagera med enhetstvillingar från enheten.

Anslut till enheten med metoden CreateFromConnectionString tillsammans med anslutningssträng och anslutningstransportprotokollet.

TransportType-transportprotokollparametern CreateFromConnectionString stöder följande transportprotokoll:

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

Protokollet Http1 stöds inte för enhetstvillinguppdateringar.

Det här exemplet ansluter till en enhet med hjälp av transportprotokollet Mqtt .

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

Hämta en enhetstvilling och granska egenskaper

Anropa GetTwinAsync för att hämta de aktuella egenskaperna för enhetstvillingar. Det finns många egenskaper för Tvillingobjekt som du kan använda för att komma åt specifika områden i Twin JSON-data, inklusive Properties, Status, Tagsoch Version.

Det här exemplet hämtar egenskaper för enhetstvillingar och skriver ut tvillingvärdena i JSON-format.

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

Uppdatera rapporterade egenskaper för enhetstvillingar

Så här uppdaterar du en tvillingrapporterad egenskap:

1. Skapa ett TwinCollection-objekt för den rapporterade egenskapsuppdateringen
2. Uppdatera en eller flera rapporterade egenskaper i TwinCollection objektet
3. Använd UpdateReportedPropertiesAsync för att skicka rapporterade egenskapsändringar till IoT Hub-tjänsten

Till exempel:

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

Skapa en önskad egenskapsuppdateringsanropshanterare

Skapa en önskad egenskapsuppdateringsanropshanterare som körs när en önskad egenskap ändras i enhetstvillingen genom att skicka motringningshanterarens metodnamn till SetDesiredPropertyUpdateCallbackAsync.

Det här anropet konfigurerar till exempel systemet för att meddela en metod med namnetOnDesiredPropertyChangedAsync när en önskad egenskap ändras.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Tvillingegenskaperna skickas till motringningsmetoden som en TwinCollection och kan undersökas som KeyValuePair strukturer.

Det här exemplet tar emot önskade egenskapsuppdateringar som en TwinCollectionoch loopar sedan igenom och skriver ut samlingsuppdateringarna KeyValuePair . När du har loopat igenom KeyValuePair samlingen anropas UpdateReportedPropertiesAsync koden för att uppdatera den DateTimeLastDesiredPropertyChangeReceived rapporterade egenskapen för att hålla den senaste uppdaterade tiden uppdaterad.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK-enhetsexempel

Azure IoT SDK för .NET innehåller ett fungerande exempel på en enhetsapp som hanterar uppgifter för enhetstvillingar. Mer information finns i TwinSample.

Skapa ett serverdelsprogram

Ett serverdelsprogram:

• Ansluter till en enhet via IoT Hub
• Kan läsa rapporterade och önskade egenskaper för enheten, skriva önskade egenskaper för enheten och köra enhetsfrågor

Klassen RegistryManager exponerar alla metoder som krävs för att skapa ett serverdelsprogram för att interagera med enhetstvillingar från tjänsten.

I det här avsnittet beskrivs hur du skapar programkod för serverdelen för att:

• Läsa och uppdatera enhetstvillingfält
• Skapa en enhetstvillingfråga

Lägg till tjänstens NuGet-paket

Serverdelstjänstprogram kräver NuGet-paketet Microsoft.Azure.Devices .

Ansluta till IoT Hub

Anslut ett serverdelsprogram till en enhet med CreateFromConnectionString. Som parameter anger du IoT Hub-tjänsten anslutningssträng som du skapade i avsnittet för förhandskrav.

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

Läsa och uppdatera enhetstvillingfält

Du kan hämta aktuella enhetstvillingfält till ett Tvillingobjekt genom att anropa GetTwinAsync.

Klassen Twin innehåller egenskaper som motsvarar varje avsnitt i en enhetstvilling. Använd klassegenskaperna Twin för att visa och uppdatera enhetstvillingfält. Du kan använda objektegenskaperna Twin för att uppdatera flera tvillingfält innan du skriver uppdateringarna till enheten med hjälp av UpdateTwinAsync.

När du har gjort uppdateringar av tvillingfält anropar du UpdateTwinAsync för att skriva Twin tillbaka objektfältuppdateringar till en enhet. Använd try och catch logik tillsammans med en felhanterare för att fånga felaktigt formaterade korrigeringsfel från UpdateTwinAsync.

Läsa och uppdatera taggar för enhetstvillingar

Använd egenskapen Taggar för enhetstvillingar för att läsa och skriva information om enhetstaggar.

Uppdatera taggar med ett tvillingobjekt

Det här exemplet skapar en location taggkorrigering, tilldelar den Twin till objektet med hjälp av Tags egenskapen och tillämpar sedan korrigeringen med .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);
}

Uppdatera taggar med en JSON-sträng

Du kan skapa och tillämpa en JSON-formaterad uppdateringskorrigering för enhetstvillinginformation. IoT Hub parsar och tillämpar korrigeringen om den är korrekt formaterad.

Det här exemplet anropar GetTwinAsync för att hämta de aktuella fälten för enhetstvillingar till ett Twin objekt, skapar en JSON-formaterad tag korrigering med region- och växtplatsinformation och anropar UpdateTwinAsync sedan för att tillämpa korrigeringen för att uppdatera enhetstvillingen. Ett felmeddelande visas om UpdateTwinAsync det inte går.

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

Visa och uppdatera önskade egenskaper för tvilling

Använd egenskapen twin TwinProperties.Desired för att läsa och skriva önskad egenskapsinformation för enheten. Uppdatera tvillingegenskaper Desired med en JSON-formaterad korrigering.

Det här exemplet anropar GetTwinAsync för att hämta de aktuella fälten för enhetstvillingar till ett Twin objekt, uppdaterar den önskade tvillingegenskapen speed och anropar UpdateTwinAsync sedan för att tillämpa Twin objektet för att uppdatera enhetstvillingen.

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

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

Andra metoder för tvillinguppdatering

Du kan också använda tvillinguppdateringar med hjälp av dessa SDK-metoder:

• Anropa ReplaceTwinAsync för att ersätta hela enhetstvillingen.
• Anropa UpdateTwins2Async för att uppdatera en lista över tvillingar som tidigare skapats i systemet.

Skapa en enhetstvillingfråga

Det här avsnittet visar två frågor för enhetstvillingar. Enhetstvillingfrågor är SQL-liknande frågor som returnerar en resultatuppsättning med enhetstvillingar.

Om du vill skapa en enhetstvillingfråga anropar du CreateQuery för att skicka en SQL-fråga för tvillingar och hämta ett IQuery-gränssnitt . Du kan också anropa CreateQuery med en andra parameter för att ange ett maximalt antal objekt per sida.

Nästa anrop GetNextAsTwinAsync eller GetNextAsJsonAsync metod så många gånger som behövs för att hämta alla tvillingresultat.

• HämtaNästaAsTwinAsync för att hämta nästa sidiga resultat som Tvillingobjekt .
• HämtaNästaAsJsonAsync för att hämta nästa sidiga resultat som JSON-strängar.

Gränssnittet IQuery innehåller en boolesk egenskap för HasMoreResults som du kan använda för att kontrollera om det finns fler tvillingresultat att hämta.

Den här exempelfrågan väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen .

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

Den här exempelfrågan förfinar den första frågan för att endast välja de enheter som också är anslutna via ett mobilnät.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

SDK-tjänstexempel

Azure IoT SDK för .NET innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för enhetstvillingar. Mer information finns i Exempel på Registerhanteraren.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Java för att skapa programkod för enhet och serverdelstjänst för enhetstvillingar.

Skapa ett enhetsprogram

Enhetsprogram kan läsa och skriva tvillingrapporterade egenskaper och meddelas om önskade ändringar av tvillingegenskapen som anges av ett serverdelsprogram eller IoT Hub.

I det här avsnittet beskrivs hur du skapar enhetsprogramkod för att:

• Hämta och visa en enhetstvilling
• Uppdatera rapporterade egenskaper för enhetstvillingar
• Prenumerera på önskade egenskapsändringar

Klassen DeviceClient visar alla metoder som du behöver för att interagera med enhetstvillingar från enheten.

Enhetsimportinstruktioner

Använd följande enhetsimportinstruktioner för att få åtkomst till Azure IoT SDK för Java.

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

Ansluta till enheten

Så här ansluter du till en enhet:

1. Använd IotHubClientProtocol för att välja ett transportprotokoll. Till exempel:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. DeviceClient Använd konstruktorn för att lägga till enhetens primära anslutningssträng och protokoll.

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

3. Använd open för att ansluta enheten till IoT Hub. Om klienten redan är öppen gör metoden ingenting.

   client.open(true);
   

Hämta och visa en enhetstvilling

När du har öppnat klientanslutningen anropar du getTwin för att hämta de aktuella tvillingegenskaperna till ett Twin objekt.

Till exempel:

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

Uppdatera rapporterade egenskaper för enhetstvilling

När du har hämtat den aktuella tvillingen kan du börja göra rapporterade egenskapsuppdateringar. Du kan också göra rapporterade egenskapsuppdateringar utan att hämta den aktuella tvillingen så länge du har rätt version av rapporterade egenskaper. Om du skickar rapporterade egenskaper och får ett "villkorsfel" är din rapporterade egenskapsversion inaktuell. I så fall hämtar du den senaste versionen genom att anropa getTwin igen.

Så här uppdaterar du rapporterade egenskaper:

1. Anropa getReportedProperties för att hämta de tvillingrapporterade egenskaperna till ett TwinCollection-objekt .

2. Använd put för att uppdatera en rapporterad egenskap i objektet TwinCollection . Anropa put för varje rapporterad egenskapsuppdatering.

3. Använd updateReportedProperties för att tillämpa gruppen med rapporterade egenskaper som uppdaterades med hjälp av put metoden.

Till exempel:

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

Prenumerera på önskade egenskapsändringar

Anropa subscribeToDesiredProperties för att prenumerera på önskade egenskapsändringar. Den här klienten får ett återanrop med ett Twin objekt varje gång en önskad egenskap uppdateras. Återanropet innehåller antingen den fullständiga önskade egenskapsuppsättningen eller bara den uppdaterade önskade egenskapen beroende på hur den önskade egenskapen ändrades.

Det här exemplet prenumererar på önskade egenskapsändringar. Önskade egenskapsändringar skickas till en hanterare med namnet DesiredPropertiesUpdatedHandler.

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

I det här exemplet anropar den önskade egenskapsändringens DesiredPropertiesUpdatedHandler återanropshanterareDesiredProperties för att hämta egenskapsändringarna och skriver sedan ut de uppdaterade tvillingegenskaperna.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

SDK-enhetsexempel

Azure IoT SDK för Java innehåller ett arbetsexempel för att testa de enhetsappbegrepp som beskrivs i den här artikeln. Mer information finns i Exempel på enhetstvilling.

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du skapar ett serverdelsprogram som:

• Uppdaterar taggar för enhetstvillingar
• Frågar enheter med filter på taggar och egenskaper

Klassen ServiceClient DeviceTwin innehåller metoder som tjänster kan använda för att komma åt enhetstvillingar.

Tjänstimportinstruktioner

Använd följande tjänstimportinstruktioner för att få åtkomst till Azure IoT SDK för Java.

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

Ansluta till IoT Hub-tjänstklienten

Så här ansluter du till IoT Hub för att visa och uppdatera information om enhetstvillingar:

1. Skapa ett DeviceTwinClientOptions-objekt . Ange de alternativ som behövs för ditt program. Dessa alternativ skickas till objektet DeviceTwin .
2. Använd en DeviceTwin-konstruktor för att skapa anslutningen till IoT Hub. Objektet DeviceTwin hanterar kommunikationen med din IoT-hubb. Som parametrar anger du IoT Hub-tjänsten anslutningssträng som du skapade i avsnittet Förutsättningar och DeviceTwinClientOptions objektet.
3. DeviceTwinDevice-objektet representerar enhetstvillingen med dess egenskaper och taggar.

Till exempel:

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

Uppdatera enhetstvillingfält

Så här uppdaterar du enhetstvillingfält:

1. Använd getTwin för att hämta de aktuella enhetstvillingfälten

   Det här exemplet hämtar och skriver ut enhetstvillingfälten:

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

2. Använda ett HashSet objekt till add en grupp med tvillingtaggpar

3. Använd setTags för att lägga till en grupp taggpar från ett tags objekt till ett DeviceTwinDevice objekt

4. Använd updateTwin för att uppdatera tvillingen i IoT-hubben

   I det här exemplet uppdateras taggarna för region- och växtenhetstvillingar för en enhetstvilling:

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

Skapa en enhetstvillingfråga

Det här avsnittet visar två frågor för enhetstvillingar. Enhetstvillingfrågor är SQL-liknande frågor som returnerar en resultatuppsättning med enhetstvillingar.

Klassen Query innehåller metoder som kan användas för att skapa SQL-liknande frågor till IoT Hub för tvillingar, jobb, enhetsjobb eller rådata.

Så här skapar du en enhetsfråga:

1. Använda createSqlQuery för att skapa SQL-frågan för tvillingar

2. Använda queryTwin för att köra frågan

3. Använd hasNextDeviceTwin för att kontrollera om det finns en annan enhetstvilling i resultatuppsättningen

4. Använd getNextDeviceTwin för att hämta nästa enhetstvilling från resultatuppsättningen

Följande exempelfrågor returnerar högst 100 enheter.

Den här exempelfrågan väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen .

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

Den här exempelfrågan förfinar den första frågan för att endast välja de enheter som också är anslutna via ett mobilnät.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

SDK-tjänstexempel

Azure IoT SDK för Java innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för enhetstvillingar. Mer information finns i Exempel på enhetstvilling.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Python för att skapa programkod för enhet och serverdelstjänst för enhetstvillingar.

Skapa ett enhetsprogram

Enhetsprogram kan läsa och skriva tvillingrapporterade egenskaper och meddelas om önskade ändringar av tvillingegenskapen som anges av ett serverdelsprogram eller IoT Hub.

Klassen IoTHubDeviceClient innehåller metoder som kan användas för att arbeta med enhetstvillingar.

I det här avsnittet beskrivs hur du skapar enhetsprogramkod som:

• Hämtar en enhetstvilling och undersöker rapporterade egenskaper
• Korrigera rapporterade egenskaper för enhetstvillingar

Ansluta till en enhet

Det här avsnittet visar hur du ansluter ett program till en enhet med hjälp av en primär enhetsnyckel som innehåller en delad åtkomstnyckel.

Så här ansluter du ett program till en enhet:

1. Anropa create_from_connection_string för att lägga till enhetens anslutningssträng
2. Anropa connect för att ansluta enhetsklienten till en Azure IoT-hubb

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

Hämta en enhetstvilling och granska rapporterade egenskaper

Du kan hämta och undersöka information om enhetstvillingar, inklusive taggar och egenskaper. Informationen om enhetstvillingen som hämtas matchar JSON-formaterade data för enhetstvillingar som du kan visa för en enhet i Azure Portal.

Anropa get_twin för att hämta enhetstvillingen från Azure IoT Hub-tjänsten. Tvillinginformationen placeras i en variabel som kan skrivas ut eller undersökas.

Det här exemplet hämtar enhetstvillingen print och använder kommandot för att visa enhetstvillingen i JSON-format.

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

Korrigera rapporterade egenskaper för enhetstvillingar

Du kan använda en korrigering för att uppdatera enhetsrapporterade egenskaper i JSON-format.

Så här tillämpar du en korrigering för att uppdatera rapporterade egenskaper:

1. Tilldela en JSON-korrigering för rapporterad egenskap till en variabel.
2. Anropa patch_twin_reported_properties för att tillämpa JSON-korrigeringen på rapporterade egenskaper. Det här är ett synkront anrop, vilket innebär att den här funktionen inte returneras förrän korrigeringen skickas till tjänsten och bekräftas.

Om patch_twin_reported_properties returnerar ett fel genererar den här funktionen motsvarande fel.

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

Du kan också anropa dessa metoder för att uppdatera enhetstvillingar:

• Anropa replace_twin för att ersätta taggar för enhetstvillingar och önskade egenskaper.
• Anropa update_twin för att uppdatera taggar för enhetstvillingar och önskade egenskaper.

Uppdateringshanterare för inkommande önskade egenskaper

Anropa on_twin_desired_properties_patch_received för att skapa en hanteringsfunktion eller coroutine som anropas när en korrigering av önskade egenskaper för en tvilling tas emot. Hanteraren tar ett argument, vilket är tvillingkorrigeringen i form av ett JSON-ordlisteobjekt.

I det här exemplet konfigureras en korrigeringshanterare för önskade egenskaper med namnet twin_patch_handler.

Till exempel:

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

Tar twin_patch_handler emot och skriver ut önskade JSON-egenskapsuppdateringar.

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

SDK-enhetsexempel

Azure IoT SDK för Python innehåller följande exempel:

• get_twin – Anslut till en enhet och hämta tvillinginformation.
• update_twin_reported_properties – Uppdatera rapporterade egenskaper för tvilling.
• receive_twin_desired_properties – Ta emot och uppdatera önskade egenskaper.

Skapa ett serverdelsprogram

Ett serverdelsprogram ansluter till en enhet via IoT Hub och kan läsa rapporterade egenskaper för enheten och önskade egenskaper, skriva önskade egenskaper för enheten och köra enhetsfrågor.

I det här avsnittet beskrivs hur du skapar ett serverdelsprogram för att:

• Uppdatera tvillingtaggar och önskade egenskaper
• Frågar enheter med filter på taggar och egenskaper

Klassen IoTHubRegistryManager visar alla metoder som krävs för att skapa ett serverdelsprogram för att interagera med enhetstvillingar från tjänsten.

Ansluta till IoT Hub

Anslut till IoT Hub med hjälp av from_connection_string. Som parameter anger du IoT Hub-tjänsten anslutningssträng som du skapade i avsnittet för förhandskrav.

Till exempel:

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)

Uppdatera tvillingtaggar och önskade egenskaper

Du kan uppdatera både enhetstvillingtaggar och önskade egenskaper från ett serverdelsprogram samtidigt med hjälp av update_twin.

1. Anropa get_twin för att hämta den aktuella versionen av enhetstvillingen
2. Använd klassen Twin för att lägga till taggar och egenskaper i JSON-format.
3. Anropa update_twin för att tillämpa korrigeringen på enhetstvillingen. Du kan också använda replace_twin för att ersätta önskade egenskaper och taggar för en enhetstvilling.

I det här exemplet uppdateras region och plant taggas information och en power_level önskad egenskap anges till 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)

Skapa en enhetstvillingfråga

Du kan köra frågor mot information om enhetstvillingar med hjälp av frågor för enhetstvillingar. Enhetstvillingfrågor är SQL-liknande frågor som returnerar en resultatuppsättning med enhetstvillingar.

Så här använder du en enhetstvillingfråga:

1. Använd ett QuerySpecification-objekt för att definiera en SQL-liknande frågebegäran.

2. Använd query_iot_hub för att fråga en IoTHub och hämta information om enhetstvillingar med hjälp av SQL-liknande frågespecifikation.

Det här exemplet kör två frågor. Den första väljer endast enhetstvillingar för enheter som finns i Redmond43 anläggningen, och den andra förfinar frågan för att endast välja de enheter som också är anslutna via ett mobilnät. Resultaten skrivs ut efter varje fråga.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

SDK-tjänstexempel

Azure IoT SDK för Python innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för enhetstvillingar. Mer information finns i Registerhanterarens frågeexempel.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Node.js för att skapa programkod för enhet och serverdelstjänst för enhetstvillingar.

Skapa ett enhetsprogram

Enhetsprogram kan läsa och skriva tvillingrapporterade egenskaper och meddelas om önskade ändringar av tvillingegenskapen som anges av ett serverdelsprogram eller IoT Hub.

I det här avsnittet beskrivs hur du använder paketet azure-iot-device i Azure IoT SDK för Node.js för att skapa ett enhetsprogram för att:

• Hämta en enhetstvilling och granska rapporterade egenskaper
• Uppdatera rapporterade egenskaper för enhetstvillingar
• Få meddelande om önskade egenskapsändringar

Installera SDK-paket

Kör det här kommandot för att installera azure-iot-device SDK på utvecklingsdatorn:

npm install azure-iot-device --save

Paketet azure-iot-device innehåller objekt som samverkar med IoT-enheter. Klassen Twin innehåller tvillingspecifika objekt. I det här avsnittet beskrivs Client klasskod som används för att läsa och skriva enhetstvillingdata.

Välj ett transportprotokoll

Objektet Client stöder följande protokoll:

• Amqp
• Http – När du använder Httpsöker instansen Client efter meddelanden från IoT Hub sällan (minst var 25:e minut).
• Mqtt
• MqttWs
• AmqpWs

Installera nödvändiga transportprotokoll på utvecklingsdatorn.

Det här kommandot installerar till exempel protokollet Mqtt :

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

Mer information om skillnaderna mellan MQTT-, AMQP- och HTTPS-stöd finns i Vägledning för kommunikation från moln till enhet och Välj ett kommunikationsprotokoll.

Skapa en klientmodul

Skapa en Client modul med det installerade paketet.

Till exempel:

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

Skapa en protokollmodul

Skapa en Protocol modul med ett installerat transportpaket.

Det här exemplet tilldelar MQTT-protokollet:

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

Lägg till anslutningssträng- och transportprotokollet för enheten

Anropa fromConnectionString för att ange parametrar för enhetsanslutning:

• connStr – en anslutningssträng som kapslar in "enhetsanslutningsbehörigheter" för en IoT-hubb. Anslutningssträng innehåller värdnamn, enhets-ID och delad åtkomstnyckel i det här formatet: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor – transportprotokollet.

I det här exemplet används transportprotokollet Mqtt :

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

Öppna anslutningen till IoT Hub

Använd den öppna metoden för att öppna en anslutning mellan en IoT-enhet och IoT Hub. Använd .catch(err) för att fånga upp ett fel och köra hanteringskod.

Till exempel:

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

Hämta en enhetstvilling och granska rapporterade egenskaper

Anropa getTwin för att hämta aktuell information om enhetstvillingar till ett Tvillingobjekt .

Till exempel:

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

Uppdatera rapporterade egenskaper för enhetstvillingar

Använd uppdatering för att uppdatera enhetsrapporterade egenskaper. Inkludera en JSON-formaterad korrigering som den första parametern och återanropsmetoden för funktionskörningsstatus som den andra parametern till metoden.

I det här exemplet lagras en JSON-formaterad korrigering av enhetstvillingar i variabeln patch . Korrigeringen innehåller ett uppdateringsvärde för enhetstvillingar connectivity på cellular. Korrigerings- och felhanteraren skickas till update metoden. Om det uppstår ett fel visas ett konsolfelmeddelande.

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

Få meddelande om önskade egenskapsändringar

Skapa en önskad händelselyssnare för egenskapsuppdatering som körs när en önskad egenskap ändras på enheten genom att skicka namn på motringningshanterarens metod till twin.on.

Den önskade egenskapshändelselyssnaren kan ha något av följande formulär:

• Ta emot alla korrigeringar med en enskild händelsehanterare
• Ta emot en händelse om något ändras under en egenskapsgruppering
• Ta emot en händelse för en enskild egenskapsändring

Ta emot alla korrigeringar med en enskild händelsehanterare

Du kan skapa en lyssnare för att få önskad egenskapsändring.

Den här exempelkoden matar ut alla egenskaper som tas emot från tjänsten.

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

Ta emot en händelse om något ändras under en egenskapsgruppering

Du kan skapa en lyssnare för att ta emot en händelse om något under en egenskapsgruppering ändras.

Till exempel:

1. Egenskaperna minTemperature och maxTemperature finns under en egenskapsgrupp med namnet properties.desired.climate changes.

2. Ett serverdelstjänstprogram tillämpar den här korrigeringen för att uppdatera minTemperature och maxTemperature önskade egenskaper:

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

3. Den här koden konfigurerar en önskad egenskapsändringshändelselyssnare som utlöser eventuella ändringar i properties.desired.climate egenskapsgruppering. Om det finns en önskad egenskapsändring i den här gruppen, ändras meddelandena minsta och högsta temperatur som visas i konsolen:

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

Ta emot en händelse för en enskild egenskapsändring

Du kan konfigurera en lyssnare för en enda egenskapsändring. I det här exemplet körs koden för den här händelsen endast om det fanOn booleska värdet är en del av korrigeringen. Koden matar ut det nya önskade fanOn tillståndet när tjänsten uppdaterar det.

1. Ett serverdelsprogram tillämpar den här önskade egenskapskorrigeringen:

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

2. Lyssnaren utlöses endast när egenskapen fanOn ändras:

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

Exempel på enhets-SDK

Azure IoT SDK för Node.js innehåller två exempel på enhetstvillingar:

• Enkel exempelenhetstvilling

• Enkel exempelenhetstvilling med SAS

Skapa ett serverdelsprogram

Ett serverdelsprogram ansluter till en enhet via IoT Hub och kan läsa rapporterade egenskaper för enheten och önskade egenskaper, skriva önskade egenskaper för enheten och köra enhetsfrågor.

I det här avsnittet beskrivs hur du skapar ett serverdelsprogram som:

• Hämtar och uppdaterar en enhetstvilling
• Skapar en enhetstvillingfråga

Installera tjänst-SDK-paket

Kör det här kommandot för att installera azure-iothub på utvecklingsdatorn:

npm install azure-iothub --save

Klassen Registry exponerar alla metoder som krävs för att interagera med enhetstvillingar från ett serverdelsprogram.

Ansluta till IoT Hub

Använd fromConnectionString för att ansluta till IoT Hub. Som parameter anger du IoT Hub-tjänsten anslutningssträng som du skapade i avsnittet för förhandskrav.

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

Hämta och uppdatera en enhetstvilling

Du kan skapa en korrigering som innehåller tagg- och önskade egenskapsuppdateringar för en enhetstvilling.

Så här uppdaterar du en enhetstvilling:

1. Anropa getTwin för att hämta enhetstvillingobjektet.

• Formatera en korrigering som innehåller enhetstvillinguppdateringen. Korrigeringen är formaterad i JSON enligt beskrivningen i Twin-klassen. En serverdelstjänstkorrigering kan innehålla tagg- och önskade egenskapsuppdateringar. Mer information om korrigeringsformat finns i Format för taggar och egenskaper.

1. Anropa uppdateringen för att uppdatera enhetstvillingen med korrigeringen.

I det här exemplet hämtas enhetstvillingen för myDeviceIdoch sedan tillämpas en korrigering på tvillingarna som innehåller location tagguppdatering av region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Skapa en enhetstvillingfråga

Du kan skapa SQL-liknande enhetsfrågor för att samla in information från enhetstvillingar.

Använd createQuery för att skapa en fråga som kan köras på en IoT Hub-instans för att hitta information om enheter eller jobb.

createQuery innehåller två parametrar:

• sqlQuery – frågan som skrivs som en SQL-sträng.
• pageSize – Önskat antal resultat per sida (valfritt. standard: 1000, max: 10000).

Om parametern pageSize anges innehåller frågeobjektet en hasMoreResults boolesk egenskap som du kan kontrollera och använda nextAsTwin metoden för att hämta nästa tvillingresultatsida så många gånger som behövs för att hämta alla resultat. En metod med namnet next är tillgänglig för resultat som inte är enhetstvillingar, till exempel resultatet av aggregeringsfrågor.

Den här exempelfrågan väljer endast enhetstvillingar för enheter som finns i Redmond43 anläggningen.

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

Den här exempelfrågan förfinar den första frågan för att endast välja de enheter som också är anslutna via mobilt nätverk.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Service SDK-exempel

Azure IoT SDK för Node.js innehåller ett fungerande exempel på en tjänstapp som hanterar uppgifter för enhetstvillingar. Mer information finns i Enhetstvillingens serverdelstjänst – Det här projektet används för att skicka uppdatering av enhetstvillingar för en viss enhet.