Cihaz ikizlerini kullanmaya başlama

Genel bakış

Bu makalede, cihaz ikizleri için cihaz ve arka uç hizmeti uygulama kodu oluşturmak üzere .NET için Azure IoT SDK'sının nasıl kullanılacağı açıklanmaktadır.

Cihaz uygulaması oluşturma

Cihaz uygulamaları ikiz tarafından bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özellik değişiklikleri hakkında bilgilendirilebilir.

Bu bölümde, cihaz uygulama kodunun nasıl kullanılacağı açıklanır:

• Cihaz ikizi alma ve bildirilen özellikleri inceleme
• Bildirilen cihaz ikizi özelliklerini güncelleştirme
• İstenen özellik güncelleştirme geri çağırma işleyicisi oluşturma

Cihaz NuGet Paketi ekleme

C# dilinde yazılan cihaz istemci uygulamaları Için Microsoft.Azure.Devices.Client NuGet paketi gerekir.

Bir cihaza bağlanma

DeviceClient sınıfı, cihazdan cihaz ikizleriyle etkileşime geçmek için gereken tüm yöntemleri kullanıma sunar.

Cihaz bağlantı dizesi ve bağlantı aktarım protokolüyle birlikte CreateFromConnectionString yöntemini kullanarak cihaza bağlanın.

CreateFromConnectionString TransportType aktarım protokolü parametresi aşağıdaki aktarım protokollerini destekler:

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

Protokol Http1 , cihaz ikizi güncelleştirmeleri için desteklenmez.

Bu örnek, aktarım protokollerini Mqtt kullanarak bir cihaza bağlanır.

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

Cihaz ikizi alma ve özellikleri inceleme

Geçerli cihaz ikizi özelliklerini almak için GetTwinAsync'i çağırın. , , Tagsve Versiongibi StatusPropertiesJSON verilerinin Twin belirli alanlarına erişmek için kullanabileceğiniz birçok İkiz nesne özelliği vardır.

Bu örnek, cihaz ikizi özelliklerini alır ve ikiz değerlerini JSON biçiminde yazdırır.

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

Bildirilen cihaz ikizi özelliklerini güncelleştirme

İkiz bildirilen özelliğini güncelleştirmek için:

1. Bildirilen özellik güncelleştirmesi için TwinCollection nesnesi oluşturma
2. Nesne içinde TwinCollection bildirilen bir veya daha fazla özelliği güncelleştirme
3. Bildirilen özellik değişikliklerini IoT hub hizmetine göndermek için UpdateReportedPropertiesAsync kullanın

Örneğin:

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

İstenen özellik güncelleştirme geri çağırma işleyicisi oluşturma

Geri çağırma işleyici yöntemi adını SetDesiredPropertyUpdateCallbackAsync'e geçirerek, cihaz ikizinde istenen özellik değiştirildiğinde yürütülen istenen özellik güncelleştirme geri çağırma işleyicisi oluşturun.

Örneğin, bu çağrı istenen bir özellik değiştirildiğinde adlıOnDesiredPropertyChangedAsync bir yöntemi bildirmek için sistemi ayarlar.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

İkiz özellikleri bir TwinCollection olarak geri çağırma yöntemine geçirilir ve yapılar olarak KeyValuePair incelenebilir.

Bu örnek, istenen özellik güncelleştirmelerini olarak TwinCollectionalır ve ardından döngüye girip koleksiyon güncelleştirmelerini yazdırır KeyValuePair . Koleksiyonda KeyValuePair döngü yaptıktan sonra kod, bildirilen özelliği güncelleştirmek DateTimeLastDesiredPropertyChangeReceived için son güncelleştirme saatini güncel tutmak için çağırırUpdateReportedPropertiesAsync.

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 cihaz örneği

.NET için Azure IoT SDK'sı, cihaz ikizi görevlerini işleyen bir cihaz uygulamasının çalışan bir örneğini sağlar. Daha fazla bilgi için bkz . TwinSample.

Arka uç uygulaması oluşturma

Arka uç uygulaması:

• IoT Hub aracılığıyla bir cihaza bağlanır
• Bildirilen ve istenen özellikleri okuyabilir, istenen cihaz özelliklerini yazabilir ve cihaz sorgularını çalıştırabilir

RegistryManager sınıfı, hizmetten cihaz ikizleriyle etkileşim kurmak için bir arka uç uygulaması oluşturmak için gereken tüm yöntemleri kullanıma sunar.

Bu bölümde aşağıdakilere yönelik arka uç uygulama kodunun nasıl oluşturulacağı açıklanmaktadır:

• Cihaz ikizi alanlarını okuma ve güncelleştirme
• Cihaz ikizi sorgusu oluşturma

Hizmet NuGet Paketi ekleme

Arka uç hizmet uygulamaları Için Microsoft.Azure.Devices NuGet paketi gerekir.

IoT hub'ına bağlanma

CreateFromConnectionString kullanarak bir arka uç uygulamasını bir cihaza bağlayın. Parametre olarak, önkoşullar bölümünde oluşturduğunuz IoT Hub hizmeti bağlantı dizesi sağlayın.

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

Cihaz ikizi alanlarını okuma ve güncelleştirme

GetTwinAsync'i çağırarak geçerli cihaz ikizi alanlarını bir twin nesnesine alabilirsiniz.

sınıfı, Twin bir cihaz ikizinin her bölümüne karşılık gelen özellikler içerir. Twin Cihaz ikizi alanlarını görüntülemek ve güncelleştirmek için sınıf özelliklerini kullanın. kullanarak cihazda UpdateTwinAsyncgüncelleştirmeleri yazmadan önce birden çok ikiz alanını güncelleştirmek için nesne özelliklerini kullanabilirsinizTwin.

İkiz alan güncelleştirmeleri yaptıktan sonra, nesne alanı güncelleştirmelerini bir cihaza geri yazmak Twin için UpdateTwinAsync'i arayın. 'den UpdateTwinAsynchatalı biçimlendirilmiş düzeltme eki hatalarını yakalamak için hata işleyicisi ile birlikte ve catch mantığını kullanıntry.

Cihaz ikizi etiketlerini okuma ve güncelleştirme

Cihaz etiketi bilgilerini okumak ve yazmak için cihaz ikizi Etiketleri özelliğini kullanın.

İkiz nesnesi kullanarak etiketleri güncelleştirme

Bu örnek bir location etiket düzeltme eki oluşturur, özelliğini kullanarak bunu nesnesine Twin Tags atar ve ardından kullanarak UpdateTwinAsyncdüzeltme ekini uygular.

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

JSON dizesi kullanarak etiketleri güncelleştirme

JSON biçimli bir cihaz ikizi bilgi güncelleştirme düzeltme eki oluşturabilir ve uygulayabilirsiniz. IoT Hub, düzeltme ekini doğru biçimlendirilmişse ayrıştırır ve uygular.

Bu örnek, geçerli cihaz ikizi alanlarını bir Twin nesneye almak için çağırırGetTwinAsync, bölge ve tesis konumu bilgileriyle JSON biçimli tag bir yama oluşturur ve ardından cihaz ikizini güncelleştirmek için düzeltme ekini uygulamayı çağırırUpdateTwinAsync. Başarısız olursa UpdateTwinAsync bir hata iletisi görüntülenir.

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

İkiz istenen özelliklerini görüntüleme ve güncelleştirme

Cihaz istenen özellik bilgilerini okumak ve yazmak için cihaz ikizi TwinProperties.Desired özelliğini kullanın. JSON biçimli bir düzeltme eki kullanarak ikiz Desired özelliklerini güncelleştirin.

Bu örnek, geçerli cihaz ikizi alanlarını bir nesneye almak için çağırırGetTwinAsync, istenen ikiz speed özelliğini güncelleştirir ve ardından cihaz ikizini Twin güncelleştirmek için nesneyi uygulamak için çağırırUpdateTwinAsync.Twin

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

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

Diğer ikiz güncelleştirme yöntemleri

Ayrıca şu SDK yöntemlerini kullanarak ikiz güncelleştirmeleri de uygulayabilirsiniz:

• Cihaz ikizinin tamamını değiştirmek için ReplaceTwinAsync öğesini çağırın.
• Sistemde daha önce oluşturulmuş ikizlerin listesini güncelleştirmek için UpdateTwins2Async'i arayın.

Cihaz ikizi sorgusu oluşturma

Bu bölümde iki cihaz ikizi sorgusu gösterilmektedir. Cihaz ikizi sorguları, cihaz ikizlerinin sonuç kümesini döndüren SQL benzeri sorgulardır.

Cihaz ikizi sorgusu oluşturmak için CreateQuery'yi çağırarak ikizler SQL sorgusu gönderin ve bir IQuery Arabirimi alın. sayfa başına en fazla öğe sayısını belirtmek için isteğe bağlı olarak ikinci bir parametreyle çağırabilirsiniz CreateQuery .

Tüm ikiz sonuçlarını almak için gereken sayıda sonraki çağrı GetNextAsTwinAsync veya GetNextAsJsonAsync yöntem.

• Sonraki sayfalanmış sonucu İkiz nesneleri olarak almak için GetNextAsTwinAsync.
• Sonraki sayfalanan sonucu JSON dizeleri olarak almak için GetNextAsJsonAsync .

Arabirimi, IQuery getirebileceğiniz daha fazla ikiz sonucu olup olmadığını denetlemek için kullanabileceğiniz bir HasMoreResults boole özelliği içerir.

Bu örnek sorgu yalnızca Redmond43 tesisinde bulunan cihazların cihaz ikizlerini seçer.

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

Bu örnek sorgu, ilk sorguyu yalnızca hücresel ağ üzerinden de bağlı olan cihazları seçecek şekilde daraltıyor.

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 hizmet örneği

.NET için Azure IoT SDK'sı, cihaz ikizi görevlerini işleyen bir hizmet uygulamasının çalışma örneğini sağlar. Daha fazla bilgi için bkz . Kayıt Defteri Yöneticisi Örneği.

Genel bakış

Bu makalede, cihaz ikizleri için cihaz ve arka uç hizmeti uygulama kodu oluşturmak üzere Java için Azure IoT SDK'sının nasıl kullanılacağı açıklanmaktadır.

Cihaz uygulaması oluşturma

Cihaz uygulamaları ikiz tarafından bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özellik değişiklikleri hakkında bilgilendirilebilir.

Bu bölümde, cihaz uygulama kodunun nasıl oluşturulacağı açıklanır:

• Cihaz ikizlerini alma ve görüntüleme
• Bildirilen cihaz ikizi özelliklerini güncelleştirme
• İstenen özellik değişikliklerine abone olma

DeviceClient sınıfı, cihazdan cihaz ikizleriyle etkileşime geçmek için ihtiyacınız olan tüm yöntemleri kullanıma sunar.

Cihaz içeri aktarma deyimleri

Java için Azure IoT SDK'sına erişmek için aşağıdaki cihaz içeri aktarma deyimlerini kullanın.

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

Cihaza bağlanma

Bir cihaza bağlanmak için:

1. Bir aktarım protokolü seçmek için IotHubClientProtocol kullanın. Örneğin:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. DeviceClient Cihaz birincil bağlantı dizesi ve protokol eklemek için oluşturucuyu kullanın.

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

3. Cihazı IoT hub'ına bağlamak için open komutunu kullanın. İstemci zaten açıksa yöntemi hiçbir şey yapmaz.

   client.open(true);
   

Cihaz ikizlerini alma ve görüntüleme

İstemci bağlantısını açtıktan sonra, geçerli ikiz özelliklerini bir Twin nesneye almak için getTwin'i çağırın.

Örneğin:

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

Cihaz ikizi bildirilen özelliklerini güncelleştirme

Geçerli ikizi aldıktan sonra bildirilen özellik güncelleştirmeleri yapmaya başlayabilirsiniz. Ayrıca, doğru bildirilen özellikler sürümüne sahip olduğunuz sürece geçerli ikizi almadan bildirilen özellik güncelleştirmeleri de yapabilirsiniz. Bildirilen özellikleri gönderir ve "önkoşul başarısız oldu" hatası alırsanız, bildirilen özellikler sürümünüz güncel değildir. Bu durumda, yeniden arayarak getTwin en son sürümü alın.

Bildirilen özellikleri güncelleştirmek için:

1. İkiz tarafından bildirilen özellikleri bir TwinCollection nesnesine getirmek için getReportedProperties çağrısı yapın.

2. Nesne içinde TwinCollection bildirilen bir özelliği güncelleştirmek için put komutunu kullanın. Bildirilen her özellik güncelleştirmesi için çağrısı.put

3. yöntemini kullanarak güncelleştirilen bildirilen özellikler grubunu uygulamak için updateReportedProperties komutunu put kullanın.

Örneğin:

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

İstenen özellik değişikliklerine abone olma

İstenen özellik değişikliklerine abone olmak için subscribeToDesiredProperties çağrısı yapın. Bu istemci, istenen bir özellik her güncelleştirildiğinde nesneyle Twin bir geri çağırma alır. Bu geri çağırma, istenen özelliklerin tamamını veya istenen özelliğin nasıl değiştirildiğine bağlı olarak yalnızca güncelleştirilmiş istenen özelliği içerir.

Bu örnek, istenen özellik değişikliklerine abonedir. İstenen özellik değişiklikleri adlı DesiredPropertiesUpdatedHandlerbir işleyiciye geçirilir.

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

Bu örnekte, istenen özellik değişikliği geri çağırma işleyicisi, DesiredPropertiesUpdatedHandler özellik değişikliklerini almak için getDesiredProperties'i çağırır ve ardından güncelleştirilmiş ikiz özelliklerini yazdırır.

  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 cihaz örneği

Java için Azure IoT SDK'sı, bu makalede açıklanan cihaz uygulaması kavramlarını test etmek için çalışan bir örnek içerir. Daha fazla bilgi için bkz . Cihaz İkizi Örneği.

Arka uç uygulaması oluşturma

Bu bölümde aşağıdakilere sahip bir arka uç uygulamasının nasıl oluşturulacağı açıklanmaktadır:

• Cihaz ikizi etiketlerini güncelleştirir
• Etiketlerdeki ve özelliklerdeki filtreleri kullanarak cihazları sorgular

ServiceClient DeviceTwin sınıfı, hizmetlerin cihaz ikizlerine erişmek için kullanabileceği yöntemleri içerir.

Hizmet içeri aktarma deyimleri

Java için Azure IoT SDK'sına erişmek için aşağıdaki hizmet içeri aktarma deyimlerini kullanın.

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

IoT hub hizmeti istemcisine bağlanma

Cihaz ikizi bilgilerini görüntülemek ve güncelleştirmek için IoT Hub'a bağlanmak için:

1. DeviceTwinClientOptions nesnesi oluşturun. Uygulamanız için gereken seçenekleri ayarlayın. Bu seçenekler nesneye DeviceTwin geçirilir.
2. IoT hub'ına bağlantı oluşturmak için bir DeviceTwin oluşturucu kullanın. nesnesi, DeviceTwin IoT hub'ınız ile iletişimi işler. Parametreler olarak, Önkoşullar bölümünde ve nesnesinde oluşturduğunuz IoT Hub hizmetini bağlantı dizesi sağlayınDeviceTwinClientOptions.
3. DeviceTwinDevice nesnesi, cihaz ikizini özellikleri ve etiketleriyle temsil eder.

Örneğin:

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

Cihaz ikizi alanlarını güncelleştirme

Cihaz ikizi alanlarını güncelleştirmek için:

1. Geçerli cihaz ikizi alanlarını almak için getTwin kullanma

   Bu örnek, cihaz ikizi alanlarını alır ve yazdırır:

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

2. İkiz HashSet etiket çiftleri grubuna add nesne kullanma

3. Nesneden tags nesneye etiket çiftleri grubu eklemek için DeviceTwinDevice setTags kullanma

4. IoT hub'ında ikizi güncelleştirmek için updateTwin kullanma

   Bu örnek, bir cihaz ikizi için bölge ve tesis cihaz ikizi etiketlerini güncelleştirir:

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

Cihaz ikizi sorgusu oluşturma

Bu bölümde iki cihaz ikizi sorgusu gösterilmektedir. Cihaz ikizi sorguları, cihaz ikizlerinin sonuç kümesini döndüren SQL benzeri sorgulardır.

Query sınıfı ikizler, işler, cihaz işleri veya ham veriler için IoT Hub'da SQL stili sorgular oluşturmak için kullanılabilecek yöntemler içerir.

Cihaz sorgusu oluşturmak için:

1. ikizler SQL sorgusunu oluşturmak için createSqlQuery kullanma

2. Sorguyu yürütmek için queryTwin kullanma

3. Sonuç kümesinde başka bir cihaz ikizi olup olmadığını denetlemek için hasNextDeviceTwin kullanın

4. Sonuç kümesinden sonraki cihaz ikizini almak için getNextDeviceTwin kullanın

Aşağıdaki örnek sorgular en fazla 100 cihaz döndürür.

Bu örnek sorgu yalnızca Redmond43 tesisinde bulunan cihazların cihaz ikizlerini seçer.

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

Bu örnek sorgu, ilk sorguyu yalnızca hücresel ağ üzerinden de bağlı olan cihazları seçecek şekilde daraltıyor.

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 hizmet örneği

Java için Azure IoT SDK'sı, cihaz ikizi görevlerini işleyen bir hizmet uygulamasının çalışan bir örneğini sağlar. Daha fazla bilgi için bkz . Cihaz İkizi Örneği.

Genel bakış

Bu makalede, cihaz ikizleri için cihaz ve arka uç hizmeti uygulama kodu oluşturmak üzere Python için Azure IoT SDK'sının nasıl kullanılacağı açıklanmaktadır.

Cihaz uygulaması oluşturma

Cihaz uygulamaları ikiz tarafından bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özellik değişiklikleri hakkında bilgilendirilebilir.

IoTHubDeviceClient sınıfı, cihaz ikizleriyle çalışmak için kullanılabilecek yöntemler içerir.

Bu bölümde, aşağıdakilere yönelik cihaz uygulama kodunun nasıl oluşturulacağı açıklanmaktadır:

• Bir cihaz ikizi alır ve bildirilen özellikleri inceler
• Yama bildirilen cihaz ikizi özellikleri

Bir cihaza bağlanma

Bu bölümde, paylaşılan erişim anahtarı içeren bir cihaz birincil anahtarı kullanarak bir uygulamayı cihaza nasıl bağlayacağınız gösterilmektedir.

Bir uygulamayı bir cihaza bağlamak için:

1. Cihaz bağlantı dizesi eklemek için create_from_connection_string'ı arayın
2. Cihaz istemcisini bir Azure IoT hub'ına bağlamak için connect çağrısı yapma

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

Cihaz ikizi alma ve bildirilen özellikleri inceleme

Etiketler ve özellikler dahil olmak üzere cihaz ikizi bilgilerini alabilir ve inceleyebilirsiniz. Alınan cihaz ikizi bilgileri, Azure portalında bir cihaz için görüntüleyebileceğiniz JSON biçimli cihaz ikizi verileriyle eşleşir.

Cihaz ikizini Azure IoT Hub hizmetinden almak için get_twin'ı arayın. İkiz bilgileri yazdırılabilir veya incelenebilir bir değişkene yerleştirilir.

Bu örnek, cihaz ikizini alır ve JSON biçiminde cihaz ikizini görüntülemek için komutunu kullanır print .

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

Yama bildirilen cihaz ikizi özellikleri

Cihaz tarafından bildirilen özellikleri JSON biçiminde güncelleştirmek için bir düzeltme eki uygulayabilirsiniz.

Bildirilen özellikleri güncelleştirmek üzere bir düzeltme eki uygulamak için:

1. Bir değişkene bildirilen bir özellik JSON düzeltme eki atayın.
2. Bildirilen özelliklere JSON düzeltme ekini uygulamak için patch_twin_reported_properties çağırın. Bu zaman uyumlu bir çağrıdır, yani düzeltme eki hizmete gönderilene ve onaylanana kadar bu işlev döndürülmüyor.

Hata döndürürse patch_twin_reported_properties , bu işlev ilgili hatayı oluşturur.

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

Cihaz ikizlerini güncelleştirmek için şu yöntemleri de çağırabilirsiniz:

• Cihaz ikizi etiketlerini ve istenen özellikleri değiştirmek için replace_twin çağrısı yapın.
• Cihaz ikizi etiketlerini ve istenen özellikleri güncelleştirmek için update_twin çağrısı yapın.

Gelen istenen özellikler düzeltme eki işleyicisi

İkiz istenen özellikler düzeltme eki alındığında çağrılan bir işleyici işlevi veya eş yordam oluşturmak için on_twin_desired_properties_patch_received çağır. İşleyici, JSON sözlük nesnesi biçiminde ikiz yaması olan bir bağımsız değişken alır.

Bu örnek, adlı twin_patch_handleristenen özellikler düzeltme eki işleyicisini ayarlar.

Örneğin:

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

JSON twin_patch_handler istenen özellik güncelleştirmelerini alır ve yazdırır.

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

SDK cihaz örnekleri

Python için Azure IoT SDK'sı aşağıdaki örnekleri içerir:

• get_twin - Bir cihaza bağlanın ve ikiz bilgilerini alın.
• update_twin_reported_properties - İkizi bildirilen özellikleri güncelleştirin.
• receive_twin_desired_properties - İstenen özellikleri alma ve güncelleştirme.

Arka uç uygulaması oluşturma

Arka uç uygulaması IoT Hub aracılığıyla bir cihaza bağlanır ve bildirilen ve istenen özellikleri okuyabilir, istenen özellikleri yazabilir ve cihaz sorgularını çalıştırabilir.

Bu bölümde, aşağıdakiler için arka uç uygulamasının nasıl oluşturulacağı açıklanır:

• İkiz etiketlerini ve istenen özellikleri güncelleştirme
• Etiketlerdeki ve özelliklerdeki filtreleri kullanarak cihazları sorgular

IoTHubRegistryManager sınıfı, hizmetten cihaz ikizleriyle etkileşim kurmak için bir arka uç uygulaması oluşturmak için gereken tüm yöntemleri kullanıma sunar.

IoT hub'ına bağlanma

from_connection_string kullanarak IoT hub'ına bağlanın. Parametre olarak, önkoşullar bölümünde oluşturduğunuz IoT Hub hizmeti bağlantı dizesi sağlayın.

Örneğin:

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)

İkiz etiketlerini ve istenen özellikleri güncelleştirme

update_twin kullanarak arka uç uygulamasından hem cihaz ikizi etiketlerini hem de istenen özellikleri aynı anda güncelleştirebilirsiniz.

1. Cihaz ikizinin geçerli sürümünü almak için get_twin çağırın
2. JSON biçiminde etiketler ve özellikler eklemek için twin sınıfını kullanın.
3. Düzeltme ekini cihaz ikizi için uygulamak için çağrısı update_twin yapın. Cihaz ikizi için istenen özellikleri ve etiketleri değiştirmek için replace_twin de kullanabilirsiniz.

Bu örnek, bilgileri güncelleştirir region ve plant etiketler ve istenen özelliği power_level olarak 1ayarlar.

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)

Cihaz ikizi sorgusu oluşturma

Cihaz ikizi sorgularını kullanarak cihaz ikizi bilgilerini sorgulayabilirsiniz. Cihaz ikizi sorguları, cihaz ikizlerinin sonuç kümesini döndüren SQL benzeri sorgulardır.

Cihaz ikizi sorgusu kullanmak için:

1. SQL benzeri bir sorgu isteği tanımlamak için QuerySpecification nesnesi kullanın.

2. IoTHub'ı sorgulamak ve SQL benzeri sorgu belirtimini kullanarak cihaz ikizi bilgilerini almak için query_iot_hub kullanın.

Bu örnekte iki sorgu çalıştırılır. birincisi yalnızca tesis içinde Redmond43 bulunan cihazların cihaz ikizlerini seçer ve ikincisi sorguyu yalnızca hücresel ağ üzerinden de bağlı olan cihazları seçecek şekilde daraltıyor. Sonuçlar her sorgudan sonra yazdırılır.

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 hizmet örneği

Python için Azure IoT SDK'sı, cihaz ikizi görevlerini işleyen bir hizmet uygulamasının çalışan bir örneğini sağlar. Daha fazla bilgi için bkz . Kayıt Defteri Yöneticisi Sorgu Örneği.

Genel bakış

Bu makalede, cihaz ikizleri için cihaz ve arka uç hizmeti uygulama kodu oluşturmak üzere Node.js için Azure IoT SDK'sının nasıl kullanılacağı açıklanmaktadır.

Cihaz uygulaması oluşturma

Cihaz uygulamaları ikiz tarafından bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özellik değişiklikleri hakkında bilgilendirilebilir.

Bu bölümde, bir cihaz uygulaması oluşturmak üzere Node.js için Azure IoT SDK'sında azure-iot-device paketinin nasıl kullanılacağı açıklanmaktadır:

• Cihaz ikizi alma ve bildirilen özellikleri inceleme
• Bildirilen cihaz ikizi özelliklerini güncelleştirme
• İstenen özellik değişiklikleriyle ilgili bildirim alma

SDK paketlerini yükleme

Geliştirme makinenize azure-iot-device cihaz SDK'sını yüklemek için şu komutu çalıştırın:

npm install azure-iot-device --save

azure-iot-device paketi, IoT cihazlarıyla arabirim oluşturan nesneler içerir. İkiz sınıfı, ikize özgü nesneleri içerir. Bu bölümde, cihaz ikizi verilerini okumak ve yazmak için kullanılan sınıf kodu açıklanmaktadır Client .

Aktarım protokolü seçme

Client nesnesi şu protokolleri destekler:

• Amqp
• Http- kullanılırken HttpClient örnek, IoT Hub'dan gelen iletileri seyrek denetler (en az 25 dakikada bir).
• Mqtt
• MqttWs
• AmqpWs

Geliştirme makinenize gerekli aktarım protokollerini yükleyin.

Örneğin, bu komut protokolü yükler Mqtt :

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

MQTT, AMQP ve HTTPS desteği arasındaki farklar hakkında daha fazla bilgi için bkz . Buluttan cihaza iletişim kılavuzu ve İletişim protokolü seçme.

İstemci modülü oluşturma

Yüklü paketi kullanarak bir Client modül oluşturun.

Örneğin:

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

Protokol modülü oluşturma

Yüklü bir Protocol aktarım paketi kullanarak bir modül oluşturun.

Bu örnekte MQTT protokolü atanır:

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

Cihaz bağlantı dizesi ve aktarım protokollerini ekleme

Cihaz bağlantı parametrelerini sağlamak içinConnectionString'den çağrısı yapın:

• connStr - IoT hub'ı için "cihaz bağlantısı" izinlerini kapsülleyen bir bağlantı dizesi. bağlantı dizesi şu biçimde konak adı, cihaz kimliği ve paylaşılan erişim anahtarı içerir: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor - Aktarım protokolü.

Bu örnekte aktarım protokolü kullanılır Mqtt :

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

IoT Hub bağlantısını açma

Bir IoT cihazı ile IoT Hub arasında bağlantı açmak için open yöntemini kullanın. Bir hatayı yakalamak ve işleyici kodunu yürütmek için kullanın .catch(err) .

Örneğin:

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

Cihaz ikizi alma ve bildirilen özellikleri inceleme

Geçerli cihaz ikizi bilgilerini bir twin nesnesine almak için getTwin çağrısı yapın.

Örneğin:

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

Bildirilen cihaz ikizi özelliklerini güncelleştirme

Cihaz tarafından bildirilen özellikleri güncelleştirmek için güncelleştirmeyi kullanın. İlk parametre olarak JSON biçimli bir düzeltme eki ve yöntemin ikinci parametresi olarak işlev yürütme durumu geri çağırma yöntemi ekleyin.

Bu örnekte JSON biçimli bir cihaz ikizi yaması değişkeninde patch depolanır. Düzeltme eki, cihaz ikizi connectivity güncelleştirme değerini cellulariçerir. Düzeltme eki ve hata işleyici yöntemine update geçirilir. Bir hata varsa konsol hata iletisi görüntülenir.

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

İstenen özellik değişiklikleriyle ilgili bildirim alma

Geri çağırma işleyicisi yöntem adını twin.on'a geçirerek cihazda istenen özellik değiştirildiğinde yürütülen istenen özellik güncelleştirme olay dinleyicisini oluşturun.

İstenen özellik olay dinleyicisi aşağıdaki formlardan birini alabilir:

• Tek bir olay işleyicisi ile tüm düzeltme eklerini alma
• Özellikler gruplandırma altında herhangi bir değişiklik olursa olay alma
• Tek bir özellik değişikliği için olay alma

Tek bir olay işleyicisi ile tüm düzeltme eklerini alma

İstediğiniz özellik değişikliğini almak için bir dinleyici oluşturabilirsiniz.

Bu örnek kod, hizmetten alınan tüm özelliklerin çıkışını oluşturur.

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

Özellikler gruplandırma altında herhangi bir değişiklik olursa olay alma

Özellik gruplandırma altında herhangi bir değişiklik olursa olay almak için dinleyici oluşturabilirsiniz.

Örneğin:

1. minTemperature ve maxTemperature özellikleri adlı properties.desired.climate changesbir özellik gruplandırma altında bulunur.

2. Arka uç hizmet uygulaması bu düzeltme ekini güncelleştirmeye minTemperature ve maxTemperature istenen özelliklere uygular:

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

3. Bu kod, özellik gruplandırma içindeki değişiklikler için tetikleyen istenen bir özellik değişikliği olay dinleyicisi properties.desired.climate ayarlar. Bu grupta istenen özellik değişikliği varsa, konsolda görüntülenen en düşük ve en yüksek sıcaklık değişikliği iletileri:

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

Tek bir özellik değişikliği için olay alma

Tek bir özellik değişikliği için dinleyici ayarlayabilirsiniz. Bu örnekte, bu olayın kodu yalnızca boole değeri düzeltme ekinin fanOn bir parçasıysa yürütülür. Hizmet her güncelleştirdiğinde kod istenen fanOn yeni durumu döndürür.

1. Arka uç uygulaması bu istenen özellik düzeltme ekini uygular:

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

2. Dinleyici yalnızca özellik değiştiğinde fanOn tetiklenir:

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

Cihaz SDK'sı örnekleri

Node.js için Azure IoT SDK'sı iki cihaz ikizi örneği içerir:

• Basit örnek cihaz ikizi

• SAS ile basit örnek cihaz ikizi

Arka uç uygulaması oluşturma

Arka uç uygulaması IoT Hub aracılığıyla bir cihaza bağlanır ve bildirilen ve istenen özellikleri okuyabilir, istenen özellikleri yazabilir ve cihaz sorgularını çalıştırabilir.

Bu bölümde aşağıdakilere sahip bir arka uç uygulamasının nasıl oluşturulacağı açıklanmaktadır:

• Cihaz ikizlerini alır ve güncelleştirir
• Cihaz ikizi sorgusu oluşturur

Hizmet SDK'sı paketlerini yükleme

Geliştirme makinenize azure-iothub yüklemek için şu komutu çalıştırın:

npm install azure-iothub --save

Registry sınıfı, bir arka uç uygulamasından cihaz ikizleriyle etkileşime geçmek için gereken tüm yöntemleri kullanıma sunar.

IoT hub'ına bağlanma

IoT hub'ına bağlanmak için fromConnectionString komutunu kullanın. Parametre olarak, önkoşullar bölümünde oluşturduğunuz IoT hub hizmeti bağlantı dizesi sağlayın.

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

Cihaz ikizlerini alma ve güncelleştirme

Cihaz ikizi için etiket ve istenen özellik güncelleştirmelerini içeren bir düzeltme eki oluşturabilirsiniz.

Cihaz ikizlerini güncelleştirmek için:

1. Cihaz ikizi nesnesini almak için getTwin'i çağırın.

• Cihaz ikizi güncelleştirmesini içeren bir düzeltme ekini biçimlendirin. Düzeltme eki, twin sınıfında açıklandığı gibi JSON biçiminde biçimlendirilir. Arka uç hizmet düzeltme eki etiket ve istenen özellik güncelleştirmelerini içerebilir. Yama biçimi hakkında daha fazla bilgi için bkz . Etiketler ve özellikler biçimi.

1. Cihaz ikizini düzeltme eki ile güncelleştirmek için güncelleştirme çağrısı yapın.

Bu örnekte cihaz ikizi için myDeviceIdalınır, ardından etiket güncelleştirmesini region: 'US', plant: 'Redmond43'içeren location ikizlere bir düzeltme eki uygulanır.

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

Cihaz ikizi sorgusu oluşturma

Cihaz ikizlerinden bilgi toplamak için SQL benzeri cihaz sorguları oluşturabilirsiniz.

Cihazlar veya işler hakkında bilgi bulmak üzere IoT hub örneğinde çalıştırılabilir bir sorgu oluşturmak için createQuery kullanın.

createQuery iki parametre içerir:

• sqlQuery - SQL dizesi olarak yazılan sorgu.
• pageSize - Sayfa başına istenen sonuç sayısı (isteğe bağlı. varsayılan: 1000, maksimum: 10000).

pageSize parametresi belirtilirse, sorgu nesnesi bir boole özelliği içerir hasMoreResults ve tüm sonuçları almak için gereken sayıda sonraki ikiz sonuçları sayfasını almak için yöntemini kullanabilirsiniznextAsTwin. Adlı next bir yöntem, toplama sorgularının sonuçları gibi cihaz ikizleri olmayan sonuçlar için kullanılabilir.

Bu örnek sorgu yalnızca tesis içinde bulunan cihazların cihaz ikizlerini Redmond43 seçer.

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

Bu örnek sorgu, ilk sorguyu yalnızca hücresel ağ üzerinden de bağlı olan cihazları seçecek şekilde daraltıyor.

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

Hizmet SDK'sı örneği

Node.js için Azure IoT SDK'sı, cihaz ikizi görevlerini işleyen bir hizmet uygulamasının çalışma örneğini sağlar. Daha fazla bilgi için bkz . Cihaz İkizi Arka Uç Hizmeti - Bu proje belirli bir cihaz için cihaz ikizi düzeltme eki güncelleştirmeleri göndermek için kullanılır.