Cihaz ikizlerini (.NET) kullanmaya başlama

Makale
01/29/2024

Cihaz ikizleri; meta veriler, yapılandırmalar ve koşullar gibi cihaz durumu bilgilerini depolayan JSON belgelerdir. IoT Hub, ona bağlanan her cihaz için bir cihaz ikizi kalıcı hale getirmekte.

Not

Bu makalede açıklanan özellikler yalnızca IoT Hub'ın standart katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. Çözümünüz için doğru IoT Hub katmanını seçme.

Cihaz ikizlerini kullanarak:

Çözüm arka ucunuzdan cihaz meta verilerini depolayın.
Kullanılabilir özellikler ve koşullar gibi geçerli durum bilgilerini (örneğin, kullanılan bağlantı yöntemi) cihaz uygulamanızdan bildirin.
Cihaz uygulaması ve arka uç uygulaması arasında üretici yazılımı ve yapılandırma güncelleştirmeleri gibi uzun süre çalışan iş akışlarının durumunu eşitleyin.
Cihaz meta verilerinizi, yapılandırmanızı veya durumunuzu sorgular.

Cihaz ikizleri eşitleme ve cihaz yapılandırmalarını ve koşullarını sorgulamak için tasarlanmıştır. Cihaz ikizlerinin ne zaman kullanılacağı da dahil olmak üzere cihaz ikizleri hakkında daha fazla bilgi için bkz . Cihaz ikizlerini anlama.

IoT hub'ları, aşağıdaki öğeleri içeren cihaz ikizlerini depolar:

Etiketler' e tıklayın. Cihaz meta verilerine yalnızca çözüm arka ucu tarafından erişilebilir.
İstenen özellikler. Çözüm arka ucu tarafından değiştirilebilir ve cihaz uygulaması tarafından gözlemlenebilir JSON nesneleri.
Bildirilen özellikler. Cihaz uygulaması tarafından değiştirilebilir ve çözüm arka ucu tarafından okunabilir JSON nesneleri.

Etiketler ve özellikler dizi içeremez, ancak iç içe nesneler içerebilir.

Aşağıdaki çizimde cihaz ikizi kuruluşu gösterilmektedir:

Cihaz ikizi kavram diyagramının ekran görüntüsü.

Ayrıca, çözüm arka ucu yukarıdaki tüm verilere göre cihaz ikizlerini sorgulayabilir. Cihaz ikizleri hakkında daha fazla bilgi için bkz . Cihaz ikizlerini anlama. Sorgulama hakkında daha fazla bilgi için bkz . IoT Hub sorgu dili.

Bu makalede aşağıdaki işlemler hakkında bilgi edinirsiniz:

Bağlantı kanalını cihaz ikizinde bildirilen bir özellik olarak raporlamak için sanal bir cihaz uygulaması kullanın.
Daha önce oluşturulan etiketlerdeki ve özelliklerdeki filtreleri kullanarak arka uç uygulamanızdaki cihazları sorgular.

Bu makalede iki .NET konsol uygulaması oluşturacaksınız:

AddTagsAndQuery: Etiket ekleyen ve cihaz ikizlerini sorgulayan bir arka uç uygulaması.
Rapor Bağlan ivity: IoT hub'ınıza bağlanan ve bağlantı durumunu bildiren sanal bir cihaz uygulaması.

Not

Hem cihaz hem de arka uç uygulamaları oluşturmak için kullanılabilen SDK araçları hakkında daha fazla bilgi için bkz . Azure IoT SDK'ları .

Önkoşullar

Visual Studio.
Bir IoT hub'ı. CLI veya Azure portalı ile bir tane oluşturun.
Kayıtlı bir cihaz. Azure portalında bir tane kaydedin.
Güvenlik duvarınızda 8883 numaralı bağlantı noktasının açık olduğundan emin olun. Bu makaledeki cihaz örneği, 8883 numaralı bağlantı noktası üzerinden iletişim kuran MQTT protokollerini kullanır. Bu bağlantı noktası bazı kurumsal ve eğitim ağı ortamlarında engellenebilir. Bu sorunu çözmenin daha fazla bilgi ve yolları için bkz. IoT Hub'a (MQTT) Bağlan.

IoT hub'ını bağlantı dizesi alma

Bu makalede, bir cihaz ikizine istenen özellikleri ekleyen bir arka uç hizmeti oluşturacak ve ardından kimlik kayıt defterini sorgulayarak uygun şekilde güncelleştirilmiş bildirilen özelliklere sahip tüm cihazları bulacaksınız. Hizmetinizin bir cihaz ikizinin istenen özelliklerini değiştirmek için hizmet bağlantı iznine ve kimlik kayıt defterini sorgulamak için kayıt defteri okuma iznine ihtiyacı var. Yalnızca bu iki izni içeren varsayılan paylaşılan erişim ilkesi yoktur, bu nedenle bir tane oluşturmanız gerekir.

Hizmet bağlama ve kayıt defteri okuma izinleri veren bir paylaşılan erişim ilkesi oluşturmak ve bu ilke için bir bağlantı dizesi almak için şu adımları izleyin:

Azure portalında Kaynak grupları'nı seçin. Hub'ınızın bulunduğu kaynak grubunu seçin ve ardından kaynak listesinden hub'ınızı seçin.
Hub'ınızın sol tarafındaki bölmede Paylaşılan erişim ilkeleri'ni seçin.
İlke listesinin üst kısmındaki menüden Paylaşılan ilke erişim ilkesi ekle'yi seçin.
Sağdaki Paylaşılan erişim ilkesi ekle bölmesinde, ilkeniz için serviceAndRegistryRead gibi açıklayıcı bir ad girin. İzinler'in altında Kayıt Defteri Okuma ve Hizmet Bağlan'ni ve ardından Ekle'yi seçin.
İlke listesinden yeni ilkenizi seçin.
Birincil bağlantı dizesi için kopyalama simgesini seçin ve değeri kaydedin.

IoT Hub paylaşılan erişim ilkeleri ve izinleri hakkında daha fazla bilgi için bkz . Erişim denetimi ve izinleri.

Bildirilen özellikleri güncelleştiren bir cihaz uygulaması oluşturma

Bu bölümde, hub'ınıza myDeviceId olarak bağlanan bir .NET konsol uygulaması oluşturacak ve ardından bildirilen özelliklerini güncelleştirerek hücresel ağ kullanarak bağlandığını onaylaacaksınız.

Visual Studio'yu açın ve Yeni proje oluştur'u seçin.
Konsol Uygulaması (.NET Framework) öğesini ve ardından İleri'yi seçin.
Yeni projenizi yapılandırın bölümünde projeye Rapor Bağlan ivity adını verin ve İleri'yi seçin.
Çözüm Gezgini'da Rapor Bağlan ivity projesine sağ tıklayın ve ardından NuGet Paketlerini Yönet'i seçin.
Varsayılan .NET Framework'leri koruyun ve oluştur'u seçerek projeyi oluşturun.
Gözat'ı seçin ve Microsoft.Azure.Devices.Client'ı arayın ve seçin. Yükle'yi seçin.

Bu adım Azure IoT cihaz SDK'sı NuGet paketini ve bağımlılıklarını indirir, yükler ve bunlara bir başvuru ekler.

Aşağıdaki using deyimlerini Program.cs dosyasının en üst kısmına ekleyin:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Program sınıfına aşağıdaki alanları ekleyin. değerini IoT Hub'a bir cihaz kaydettiğinizde gördüğünüz cihaz bağlantı dizesi ile değiştirin{device connection string}:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Program sınıfına aşağıdaki yöntemi ekleyin:

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

İstemci nesnesi, cihazdan cihaz ikizleriyle etkileşim kurmak için ihtiyacınız olan tüm yöntemleri kullanıma sunar. Yukarıda gösterilen kod client nesnesini başlatır ve myDeviceId için cihaz ikizini alır.

Program sınıfına aşağıdaki yöntemi ekleyin:

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Yukarıdaki kod, myDeviceId dosyasının bildirilen özelliğini bağlantı bilgileriyle güncelleştirir.

Son olarak, Main yöntemine aşağıdaki satırları ekleyin:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Çözüm Gezgini'da çözümünüze sağ tıklayın ve Başlangıç Projelerini Ayarla'yı seçin.
Ortak Özellikler>Başlangıç Projesi'nde Birden çok başlangıç projesi'ni seçin. Rapor Bağlan ivity için Eylem olarak Başlat'ıseçin. Değişikliklerinizi kaydetmek için Tamam'ı seçin.
Rapor Bağlan ivity projesine sağ tıklayıp Hata Ayıkla'yı ve ardından Yeni örneği başlat'ı seçerek bu uygulamayı çalıştırın. Uygulamanın ikiz bilgilerini alıp bildirilen bir özellik olarak bağlantı gönderdiğini görmeniz gerekir.

Cihaz bağlantı bilgilerini bildirdikten sonra her iki sorguda da görünmelidir.
AddTagsAndQuery projesine sağ tıklayın ve sorguları yeniden çalıştırmak için Hata Ayıkla>Yeni örneği başlat'ı seçin. Bu kez myDeviceId her iki sorgu sonuçlarında da görünmelidir.

İstenen özellikleri ve sorgu ikizlerini güncelleştiren bir hizmet uygulaması oluşturma

Bu bölümde, C# kullanarak myDeviceId ile ilişkilendirilmiş cihaz ikizi için konum meta verileri ekleyen bir .NET konsol uygulaması oluşturacaksınız. Uygulama, ABD'de bulunan cihazlar için IoT hub'ını sorgular ve ardından hücresel ağ bağlantısı bildiren cihazları sorgular.

Visual Studio'da Dosya > Yeni Proje'yi> seçin. Yeni proje oluştur bölümünde Konsol Uygulaması (.NET Framework) öğesini ve ardından İleri'yi seçin.
Yeni projenizi yapılandırın bölümünde projeyi AddTagsAndQuery olarak adlandırın ve İleri'yi seçin.
.NET Framework'ün varsayılan sürümünü kabul edin, ardından oluştur'u seçerek projeyi oluşturun.
Çözüm Gezgini AddTagsAndQuery projesine sağ tıklayıp NuGet Paketlerini Yönet'i seçin.
Gözat'ı seçin, Microsoft.Azure.Devices'ı arayın ve seçin. Yükle'yi seçin.

Bu adım Azure IoT hizmet SDK'sı NuGet paketini ve bağımlılıklarını indirir, yükler ve bunlara bir başvuru ekler.
Aşağıdaki using deyimlerini Program.cs dosyasının en üst kısmına ekleyin:
```
using Microsoft.Azure.Devices;
```
Program sınıfına aşağıdaki alanları ekleyin. değerini, IoT hub'ını alma bağlantı dizesi'nde kopyaladığınız IoT Hub bağlantı dizesi ile değiştirin{iot hub connection string}.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

Program sınıfına aşağıdaki yöntemi ekleyin:

public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

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

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

RegistryManager sınıfı, hizmetten cihaz ikizleriyle etkileşime geçmek için gereken tüm yöntemleri kullanıma sunar. Önceki kod önce registryManager nesnesini başlatır, ardından myDeviceId için cihaz ikizini alır ve son olarak etiketlerini istenen konum bilgileriyle güncelleştirir.

Güncelleştirmeden sonra iki sorgu yürütür: birincisi yalnızca Redmond43 tesisinde bulunan cihazların cihaz ikizlerini seçer ve ikincisi sorguyu yalnızca hücresel ağ üzerinden bağlanan cihazları seçecek şekilde daraltıyor.

Önceki kod, sorgu nesnesini oluşturduğunda, döndürülen belge sayısı üst sınırını belirtir. Sorgu nesnesi, getNextAsTwinAsync yöntemlerini birden çok kez çağırarak tüm sonuçları almak için kullanabileceğiniz bir HasMoreResults boole özelliği içerir. GetNextAsJson adlı bir yöntem, toplama sorgularının sonuçları gibi cihaz ikizleri olmayan sonuçlar için kullanılabilir.

Son olarak, Main yöntemine aşağıdaki satırları ekleyin:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

AddTagsAndQuery projesine sağ tıklayıp Hata Ayıkla'yı ve ardından Yeni örneği başlat'ı seçerek bu uygulamayı çalıştırın. Sorgunun sonuçlarında redmond43'te bulunan tüm cihazları soran ve sonuçları hücresel ağ kullanan cihazlarla kısıtlayan sorgu için hiçbiri olmayan bir cihaz görmeniz gerekir.

Bu makalede şunları yapacaksınız:

Arka uç uygulamasından etiket olarak cihaz meta verileri eklendi
Cihaz ikizinde bildirilen cihaz bağlantı bilgileri
SQL benzeri IoT Hub sorgu dilini kullanarak cihaz ikizi bilgilerini sorguladık

Sonraki adımlar

Şunlar hakkında bilgi edinmek için:

Cihazlardan telemetri gönderme, bkz. Hızlı Başlangıç: IoT Tak Çalıştır cihazdan Azure IoT Hub'a telemetri gönderme.
Cihaz ikizlerinin istenen özelliklerini kullanarak cihazları yapılandırma, bkz . Öğretici: Cihazlarınızı arka uç hizmetinden yapılandırma.
Kullanıcı tarafından denetlenen bir uygulamadan fan açma gibi cihazları etkileşimli olarak denetleme konusuna bakın. Hızlı Başlangıç: IoT hub'ına bağlı bir cihazı denetleme.

Cihaz ikizlerini (.NET) kullanmaya başlama

Önkoşullar

IoT hub'ını bağlantı dizesi alma

Bildirilen özellikleri güncelleştiren bir cihaz uygulaması oluşturma

İstenen özellikleri ve sorgu ikizlerini güncelleştiren bir hizmet uygulaması oluşturma

Sonraki adımlar

Ek kaynaklar