Cihaz ikizleriyle başlayın

Yaygın cihaz ikizi görevlerini işleyen uygulamalar geliştirmek için Azure IoT Hub cihaz SDK'sını ve hizmet SDK'sını kullanın. Cihaz ikizleri meta veriler, yapılandırmalar ve koşullar dahil olmak üzere cihaz durumu bilgilerini depolayan JSON belgeleridir. IoT Hub, kendisine bağlanan her cihaz için bir cihaz ikizini kalıcı olarak saklar.

Cihaz ikizlerini şu amaçlarla kullanabilirsiniz:

Çözümünüzün arka ucundan 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şitleme
Cihaz meta verilerinizi, yapılandırmanızı veya durumunuzu sorgulama

Cihaz ikizlerinin ne zaman kullanılacağı dahil olmak üzere cihaz ikizleri hakkında daha fazla bilgi için bkz . IoT Hub'da cihaz ikizlerini anlama ve kullanma.

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 için doğru IoT Hub katmanını ve boyutunu seçme.

Bu makalede iki tür uygulama geliştirme gösterilmektedir:

Cihaz uygulamaları istenen özellikleri güncelleştirme ve bildirilen özelliklerde yapılan değişikliklerle yanıt verme isteklerini işleyebilir.
Hizmet uygulamaları cihaz ikizi etiketlerini güncelleştirebilir, istenen yeni özellikleri ayarlayabilir ve cihaz ikizi değerlerine göre cihazları sorgulayabilir.

Not

Bu makale, bu makalede bahsedilen Azure IoT SDK'ları örneklerini desteklemeye yöneliktir. Sdk araçlarını kullanarak hem cihaz hem de arka uç uygulamaları oluşturabilirsiniz.

Önkoşullar

IoT hub'ı
Kayıtlı bir cihaz
Uygulamanız MQTT protokolunu kullanıyorsa, güvenlik duvarınızda 8883 numaralı bağlantı noktasının açık olduğundan emin olun. MQTT protokolü 8883 numaralı bağlantı noktası üzerinden iletişim kurar. 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ğlanma.

Visual Studio gerektirir

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 ikizini al ve bildirilen özellikleri incele
Bildirilen cihaz ikizi özelliklerini güncelle
İstenen özellik güncelleştirme geri çağırma işleyicisi oluşturma

Gerekli cihaz NuGet paketi

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

Cihaz kitaplığını kullanmak için bu using deyimi ekleyin.

using Microsoft.Azure.Devices.Client;

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması aşağıdaki yöntemleri kullanarak IoT Hub ile kimlik doğrulaması yapabilir:

Paylaşılan erişim anahtarı
X.509 sertifikası

Önemli

Bu makale, simetrik anahtar kimlik doğrulaması olarak da adlandırılan paylaşılan erişim imzasını kullanarak bir cihazı bağlama adımlarını içerir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak X.509 sertifikalarını kullanarak bir cihazın kimliğini doğrulamak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik yöntemleri Bağlantı güvenliği.

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

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

X.509 sertifikası kullanarak kimlik doğrulaması

X.509 sertifikası kullanarak bir cihazı IoT Hub'a bağlamak için:

Cihaz ve sertifika bilgilerini içeren bir nesne oluşturmak için DeviceAuthenticationWithX509Certificate kullanın. DeviceAuthenticationWithX509Certificate ikinci parametre DeviceClient.Create olarak geçirilir (2. adım).
Cihazı bir X.509 sertifikası kullanarak IoT Hub'a bağlamak için DeviceClient.Create kullanın.

Bu örnekte, cihaz ve sertifika bilgileri, authDeviceAuthenticationWithX509Certificate öğesine geçirilerek DeviceClient.Create nesnesinde doldurulur.

Bu örnekte, netlik için yerel değişkenler olarak sertifika giriş parametresi değerleri gösterilmektedir. Bir üretim sisteminde, hassas giriş parametrelerini ortam değişkenlerinde veya daha güvenli başka bir depolama konumunda depolayın. Örneğin, konak adı ortam değişkenini okumak için kullanın Environment.GetEnvironmentVariable("HOSTNAME") .

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Sertifika kimlik doğrulaması hakkında daha fazla bilgi için bkz:

Kod örnekleri

Cihaz X.509 sertifika kimlik doğrulamasının çalışma örnekleri için bkz:

Cihaz ikizini al ve özelliklerini incele

Geçerli cihaz ikizi özelliklerini almak için GetTwinAsync'i çağırın. Birçok Twin nesne özelliği, Properties, Status, Tags, ve Version gibi Twin JSON verilerinin belirli alanlarına erişim sağlamak için kullanılabilir.

Bu örnek, cihaz ikizi özelliklerini alır ve bu özelliklerin değerlerini JSON formatında yazar.

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

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

Bildirilen özellik güncelleştirmesi için TwinCollection nesnesi oluşturma
Nesne içinde TwinCollection bildirilen bir veya daha fazla özelliği güncelleştirme
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);

Çift özellikler, bir TwinCollection olarak callback yöntemine geçirilir ve KeyValuePair yapılar olarak incelenebilir.

Bu örnek, TwinCollection olarak istenen özellik güncellemelerini alır ve ardından koleksiyon güncellemelerini KeyValuePair döngü üzerinden yazdırır. KeyValuePair koleksiyonu üzerinde döngü yaptıktan sonra, kod son güncelleme saatini güncel tutmak için bildirilen özelliği güncelleştirmek amacıyla UpdateReportedPropertiesAsync çağırırDateTimeLastDesiredPropertyChangeReceived.

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 ve bildirilen ve istenen özellikleri okuyabilir, istenen özellikleri yazabilir ve cihaz sorgularını çalıştırabilir.

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ştur

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.

NuGet Paketi hizmeti ekleme

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

IoT hub'ına bağlanma

Aşağıdaki yöntemleri kullanarak bir arka uç hizmetini IoT Hub'a bağlayabilirsiniz:

Paylaşılan erişim ilkesi
Microsoft Entra

Önemli

Bu makale, paylaşılan erişim imzası kullanarak hizmete bağlanma adımlarını içerir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak Microsoft Entra ID veya yönetilen kimliklerle bir hizmette kimlik doğrulaması yapmak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik uygulamaları Bulut güvenliği.

Paylaşılan erişim ilkesi kullanarak bağlanma

CreateFromConnectionString kullanarak bir arka uç uygulamasını bir cihaza bağlayın. Uygulamanızın 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 zaten bir tane yoksa bir tane oluşturmanız gerekir. Bu paylaşılan erişim ilkesinin bağlantı dizesini, fromConnectionString için bir parametre olarak sağlayın. Paylaşılan erişim ilkeleri hakkında daha fazla bilgi için bkz . Paylaşılan erişim imzalarıyla IoT Hub'a erişimi denetleme.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Microsoft Entra kullanarak bağlanma

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve güvenlik belirteci kimlik bilgilerini alması gerekir. Bu belirteç bir IoT Hub bağlantı yöntemine aktarılır. IoT Hub için Microsoft Entra'yı ayarlama ve kullanma hakkında genel bilgi için bkz . Microsoft Entra Id kullanarak IoT Hub'a erişimi denetleme.

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulama bilgisi için yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, sunucu tarafı uygulaması tarafından kimlik doğrulama için kullanılan istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

İstemci sırrı
Sertifika
Federe kimlik bilgileri

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazına ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için IoT Hub İkizi Katkıda Bulunanı gereklidir. Daha fazla bilgi için bkz . Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme.

Microsoft Entra uygulamasını ayarlama hakkında daha fazla bilgi için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile uygulama kaydetme.

DefaultAzureCredential kullanarak kimlik doğrulaması

Arka uç uygulamasının kimliğini doğrulamak için Microsoft Entra kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya azaltılmış bir ChainedTokenCredential gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde DefaultAzureCredential ve İstemci gizli anahtarı kullanarak kimlik doğrulaması açıklanmaktadır. DefaultAzureCredential kullanmanın avantajları ve dezavantajları hakkında daha fazla bilgi için bkz. DefaultAzureCredential için kullanım kılavuzu.

DefaultAzureCredential farklı kimlik doğrulama mekanizmalarını destekler ve yürütülmekte olduğu ortama göre uygun kimlik bilgisi türünü belirler. Çalışır bir kimlik bilgisi bulana kadar birden çok kimlik bilgisi türünü sırayla kullanmayı dener.

Microsoft Entra, bu NuGet paketlerini ve bunlara karşılık gelen using deyimleri gerektirir:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Bu örnekte, Microsoft Entra uygulama kaydının istemci sırrı, istemci kimliği ve kiracı kimliği ortam değişkenlerine eklenir. Bu ortam değişkenleri tarafından DefaultAzureCredential uygulamanın kimliğini doğrulamak için kullanılır. Başarılı bir Microsoft Entra kimlik doğrulaması sonucunda, IoT Hub bağlantı yöntemine iletilen bir güvenlik belirteci kimlik bilgisi elde edilir.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Sonuçta elde edilen TokenCredential , Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanma yöntemine geçirilebilir:

Bu örnekte, TokenCredential nesnesi, bir ServiceClient bağlantı nesnesi oluşturmak için ServiceClient.Create'ye geçirilir.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Bu örnekte, TokenCredentialRegistryManager.Create öğesine geçirilerek bir RegistryManager nesnesi oluşturulur.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Kod örneği

Microsoft Entra hizmeti kimlik doğrulamasının çalışan bir örneği için bkz . Rol tabanlı kimlik doğrulama örneği.

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

GetTwinAsync ç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. Şu anda Twin kullanarak cihazda güncelleştirmeleri yazmadan önce birden çok ikiz alanını güncelleştirmek için nesne özelliklerini kullanabilirsiniz UpdateTwinAsync.

İkiz alan güncelleştirmeleri yaptıktan sonra, nesne alanı güncelleştirmelerini bir cihaza geri yazmak için UpdateTwinAsync'iTwin. try ve catch mantığını, UpdateTwinAsync'den hatalı biçimlendirilmiş yama hatalarını yakalamak için bir hata işleyicisiyle birlikte kullanın.

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, bunu Twin nesnesine Tags özelliğini kullanarak atar ve ardından UpdateTwinAsync kullanarak dü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çiminde bir cihaz ikizi güncelleştirme yaması 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 GetTwinAsync nesnesine almak için Twin çağırır, bölge ve tesis konumu bilgileriyle JSON biçimli bir tag yama oluşturur, ardından cihaz ikizini güncellemek için yamayı uygulamak amacıyla UpdateTwinAsync çağırır. 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 özellikleri görüntüle ve güncelleştir

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, cihazın geçerli ikiz alanlarını bir GetTwinAsync nesnesine almak için GetTwinAsync çağrısını yapar, ikizin speed istenen özelliğini günceller ve ardından cihaz ikizini güncellemek için UpdateTwinAsync çağrısını yaparak Twin nesnesini uygular.

// 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üncelleme 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ştur

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

Şu şekilde cihaz ikizi sorgusu oluşturun: CreateQuery'yi çağırarak cihaz ikizi 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 GetNextAsTwinAsync veya GetNextAsJsonAsync metodunu gerektiği kadar çağırın.

GetNextAsTwinAsync ile, sonraki sayfalı sonucu İkiz nesneleri olarak alın.
Sonraki sayfalı sonucu JSON dizeleri şeklinde almak için GetNextAsJsonAsync

Arabirim, daha fazla ikiz sonucu getirip getiremeyeceğinizi kontrol etmek için kullanabileceğiniz bir IQuery 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.

Java SE Geliştirme Seti 8 gerektirir. JDK 8 indirmelerine gitmek için Uzun süreli destek bölümünde Java 8'i seçtiğinizden emin olun.

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 bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özellik değişiklikleri ile ilgili bildirim alabilir.

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

Cihaz ikizini alma ve görüntüleme
Bildirilen cihaz ikizi özelliklerini güncelle
İ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.

Önemli

Cihaz import ifadeleri

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.*;

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması aşağıdaki yöntemleri kullanarak IoT Hub ile kimlik doğrulaması yapabilir:

Paylaşılan erişim anahtarı
X.509 sertifikası

Önemli

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

Bir cihazı IoT Hub'a bağlamak için:

Bir aktarım protokolü seçmek için IotHubClientProtocol kullanın. Örneğin:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

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

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

X.509 sertifikası kullanarak kimlik doğrulaması

X.509 sertifikası kullanarak bir cihazı IoT Hub'a bağlamak için:

buildSSLContext kullanarak SSLContext nesnesini derleyin.
SSLContext Bilgileri clientOptions nesnesine ekleyin.
bilgisini kullanarak cihazdan IoT Hub'a bağlantı oluşturmak için ClientOptions'ı çağırın.

Bu örnekte, netlik için yerel değişkenler olarak sertifika giriş parametresi değerleri gösterilmektedir. Bir üretim sisteminde, hassas giriş parametrelerini ortam değişkenlerinde veya daha güvenli başka bir depolama konumunda depolayın. Örneğin, ortak anahtar sertifika dizesi ortam değişkenlerini okumak için kullanın Environment.GetEnvironmentVariable("PUBLICKEY") .

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Sertifika kimlik doğrulaması hakkında daha fazla bilgi için bkz:

Kod örnekleri

Cihaz X.509 sertifika kimlik doğrulamasının çalışma örnekleri için bkz:

Cihaz ikizini alma ve görüntüleme

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

Ö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 ikizinin bildirilen özelliklerini güncelleştir.

Mevcut ikizi aldıktan sonra rapor edilen özellik güncellemeleri 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, tekrar arayarak getTwin en son sürümü alın.

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

İkiz rapor edilen özellikleri bir TwinCollection nesnesine almak için getReportedProperties çağrısını yapın.
Nesne içinde bildirilen bir özelliği güncelleştirmek için putTwinCollection. Bildirilen her özellik güncelleştirmesi için çağrı yapın.put
yöntemini kullanarak güncelleştirilen bildirilen özellikler grubunu uygulamak için updateReportedProperties.

Ö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 olmak için subscribeToDesiredProperties çağrısı yapın. Bu istemci, istenen bir özellik her güncelleştirildiğinde, Twin nesnesiyle bir geri çağırma işlevi 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ın ikizi etiketlerini günceller
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 import ifadeleri

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'a bağlanma

Aşağıdaki yöntemleri kullanarak bir arka uç hizmetini IoT Hub'a bağlayabilirsiniz:

Paylaşılan erişim ilkesi
Microsoft Entra

Önemli

Paylaşılan erişim ilkesi kullanarak bağlanma

IoT hub'ına bağlantı oluşturmak için bir DeviceTwin oluşturucu kullanın. Bu nesne, DeviceTwin IoT hub'ınız ile iletişimi işler.

Uygulamanızın 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 zaten bir tane yoksa bir tane oluşturmanız gerekir. Bu paylaşılan erişim ilkesinin bağlantı dizesini, fromConnectionString için bir parametre olarak sağlayın. Paylaşılan erişim ilkeleri hakkında daha fazla bilgi için bkz . Paylaşılan erişim imzalarıyla IoT Hub'a erişimi denetleme.

DeviceTwinDevice nesnesi, cihaz ikizini özellikleri ve etiketleriyle temsil eder.

Örneğin:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Microsoft Entra kullanarak bağlanma

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve güvenlik belirteci kimlik bilgilerini alması gerekir. Bu belirteç bir IoT Hub bağlantı yöntemine geçirilir. IoT Hub için Microsoft Entra'yı ayarlama ve kullanma hakkında genel bilgi için bkz . Microsoft Entra Id kullanarak IoT Hub'a erişimi denetleme.

Java SDK kimlik doğrulamasına genel bakış için bkz . Java ve Azure Identity ile Azure kimlik doğrulaması.

Kolaylık olması açısından bu bölüm, istemci sırrını kullanarak kimlik doğrulamasını açıklamaya odaklanır.

Microsoft Entra uygulamasını yapılandırma

İstemci gizli
Sertifika
Federe kimlik bilgileri

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazına ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için IoT Hub Twin Contributor gereklidir. Daha fazla bilgi için bkz . Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme.

Microsoft Entra uygulamasını ayarlama hakkında daha fazla bilgi için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile uygulama kaydetme.

DefaultAzureCredential kullanarak kimlik doğrulaması

Arka uç uygulamasının kimliğini doğrulamak için Microsoft Entra kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya azaltılmış bir ChainedTokenCredential gibi farklı bir yöntem kullanılması önerilir. Azure Identity istemci kitaplığındaki Java için Kimlik Bilgisi Zincirleri hakkında daha fazla bilgi ve DefaultAzureCredential kullanımının avantajları ile dezavantajları için bkz.

DefaultAzureCredential farklı kimlik doğrulama mekanizmalarını destekler ve yürütülmekte olduğu ortama göre uygun kimlik bilgisi türünü belirler. Çalışır bir kimlik bilgisi bulana kadar birden çok kimlik bilgisi türünü sırayla kullanmayı dener.

DefaultAzureCredentialBuilder kullanarak Microsoft Entra uygulaması kimlik bilgilerini doğrulayabilirsiniz. İstemci gizli anahtarı tenantID, clientID ve istemci gizli anahtarı değerleri gibi bağlantı parametrelerini ortam değişkenleri olarak kaydedin. TokenCredential oluşturulduktan sonra bunu ServiceClient'a veya başka bir oluşturucuya 'credential' parametresi olarak geçirin.

Bu örnekte, DefaultAzureCredentialBuilder DefaultAzureCredential bölümünde açıklanan listeden bir bağlantının kimliğini doğrulamayı dener. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, ServiceClient gibi bir yapılandırıcıya geçirilen bir güvenlik belirteci kimlik bilgisidir.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

ClientSecretCredentialBuilder kullanarak kimlik doğrulaması yapma

İstemci gizli dizi bilgilerini kullanarak kimlik bilgisi oluşturmak için ClientSecretCredentialBuilder'ı kullanabilirsiniz. Başarılı olursa, bu yöntem ServiceClient'a veya başka bir oluşturucuya 'credential' parametresi olarak geçirilebilen bir TokenCredential döndürür.

Bu örnekte, Microsoft Entra uygulama kaydının istemci gizli anahtarı, istemci kimliği ve kiracı kimliği değerleri ortam değişkenlerine eklenmiştir. Bu ortam değişkenleri, ClientSecretCredentialBuilder tarafından kimlik bilgisi oluşturmak için kullanılır.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Diğer kimlik doğrulama sınıfları

Java SDK'sı, Microsoft Entra ile arka uç uygulamasının kimliğini doğrulayan şu sınıfları da içerir:

Kod örnekleri

Microsoft Entra hizmeti kimlik doğrulamasının çalışma örnekleri için bkz . Rol tabanlı kimlik doğrulama örneği.

Cihaz ikizi alanlarını güncelleştirme

Cihaz ikizi alanlarını güncellemek için:

Geçerli cihaz ikizi alanlarını almak için getTwin'i kullan

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

İkiz etiket çiftleri grubuna HashSet için bir add nesnesi kullanın
setTags işlevini kullanarak bir tags nesneden bir DeviceTwinDevice nesneye etiket çiftleri grubu ekleyin.

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ştur

Bu bölümde iki cihaz ikizi sorguları sergilenmektedir. 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 tarzında sorgular oluşturmak amacıyla kullanılabilecek yöntemler içerir.

Cihaz sorgusu oluşturmak için:

createSqlQuery kullanarak ikizler SQL sorgusunu oluşturun
Sorguyu yürütmek için queryTwin kullanma
Sonuç kümesinde başka bir cihaz ikizi olup olmadığını denetlemek için hasNextDeviceTwin kullanın
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.

Python SDK - Python sürüm 3.7 veya üzeri önerilir. Kurulumunuzun gereksinimine uygun olarak 32 bit veya 64 bit yüklemeyi kullanmaya dikkat edin. Yükleme sırasında istendiğinde, platforma özgü ortam değişkeninize Python’u eklediğinizden emin olun.

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.

Paketleri yükleme

Cihaz uygulamaları oluşturmak için azure-iot-device kitaplığının yüklenmesi gerekir.

pip install azure-iot-device

Arka uç hizmet uygulamaları oluşturmak için azure-iot-hub kitaplığı yüklenmelidir.

pip install azure-iot-hub

Cihaz uygulaması oluşturma

Cihaz uygulamaları ikiz özelliklerin bildirilen değerlerini okuyup yazabilir ve arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz özelliklerde yapılan değişiklikler 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 ikizini alır ve bildirilen özellikleri inceler.
Cihaz dijital ikizi özellikleri güncellemesi rapor edildi.

Cihaz import ifadesi

Azure.iot.device SDK'sindeki IoTHubDeviceClient işlevlerini içeri aktarmak için bu kodu ekleyin.

from azure.iot.device import IoTHubDeviceClient

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması aşağıdaki yöntemleri kullanarak IoT Hub ile kimlik doğrulaması yapabilir:

Paylaşılan erişim anahtarı
X.509 sertifikası

Önemli

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

Bir cihazı IoT Hub'a bağlamak için:

create_from_connection_string'ı çağırarak cihazın birincil bağlantı dizesini ekleyin.
Cihaz istemcisini bağlamak için connect çağrısı yapın.

Örneğin:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

X.509 sertifikası kullanarak kimlik doğrulaması

X.509 sertifikası kullanarak bir cihazı IoT Hub'a bağlamak için:

X.509 sertifika parametrelerini eklemek için create_from_x509_certificate kullanma
Cihaz istemcisini bağlamak için connect fonksiyonunu çağırın

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Sertifika kimlik doğrulaması hakkında daha fazla bilgi için bkz:

Kod örnekleri

Cihaz X.509 sertifika kimlik doğrulamasının çalışma örnekleri için, Async hub senaryolarında dosya adları x509 ile biten örneklere bakın.

Cihaz ikizini al ve bildirilen özellikleri incele

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 cihaz ikizini JSON formatında görüntülemek için print komutunu kullanır.

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

Cihaz dijital ikizi özellikleri güncellemesi rapor edildi.

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:

Bir değişkene bildirilen özellik JSON yaması atayın.
Bildirilen özelliklere JSON düzeltme ekini uygulamak için patch_twin_reported_properties çağırın. Bu işlev, zaman uyumlu bir çağrıdır, yani düzeltme eki hizmete gönderilene ve onaylanana kadar geri dönmü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.

İstenen gelen özellikler güncelleme işleyicisi

İkiz istenen özellikler yaması alındığında çağrılacak bir işleyici işlevi veya eş yordam oluşturmak için on_twin_desired_properties_patch_received işlevini çağırın. İşleyici, bir JSON sözlük nesnesi biçimindeki ikiz yamasını temsil eden 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 - İkili bildirilmiş özellikleri güncelleyin.
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

Aşağıdaki yöntemleri kullanarak bir arka uç hizmetini IoT Hub'a bağlayabilirsiniz:

Paylaşılan erişim ilkesi
Microsoft Entra

Önemli

Paylaşılan erişim ilkesi kullanarak bağlanma

from_connection_string kullanarak IoT hub'ına bağlanın. Uygulamanızın 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 zaten bir tane yoksa bir tane oluşturmanız gerekir. Bu paylaşılan erişim ilkesinin bağlantı dizesini, fromConnectionString için bir parametre olarak sağlayın. Paylaşılan erişim ilkeleri hakkında daha fazla bilgi için bkz . Paylaşılan erişim imzalarıyla IoT Hub'a erişimi denetleme.

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

Microsoft Entra kullanarak bağlanma

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve güvenlik belirteci kimlik bilgilerini alması gerekir. Bu belirteç, bir IoT Hub bağlantı yöntemine iletilir. IoT Hub için Microsoft Entra'yı ayarlama ve kullanma hakkında genel bilgi için bkz . Microsoft Entra Id kullanarak IoT Hub'a erişimi denetleme.

Python SDK kimlik doğrulamasına genel bakış için bkz . Python için Azure SDK'sını kullanarak Azure hizmetlerinde Python uygulamalarının kimliğini doğrulama

Microsoft Entra uygulamasını yapılandırma

İstemci gizli bilgisi
Sertifika
Federe kimlik bilgileri

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, bir IoT Hub cihazına ve modül ikizlerine okuma ve yazma erişimi sağlamak için IoT Hub Twin Contributor rolü gereklidir. Daha fazla bilgi için bkz . Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme.

Microsoft Entra uygulamasını ayarlama hakkında daha fazla bilgi için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile uygulama kaydetme.

DefaultAzureCredential kullanarak kimlik doğrulaması

Arka uç uygulamasının kimliğini doğrulamak için Microsoft Entra kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya azaltılmış bir ChainedTokenCredential gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde DefaultAzureCredential ve İstemci gizli anahtarı kullanılarak kimlik doğrulama açıklanmaktadır. DefaultAzureCredential kullanımının avantajları ve dezavantajları hakkında daha fazla bilgi için, Python için Azure Identity istemci kitaplığındaki Kimlik Bilgileri Zincirleri bölümüne bakın.

Microsoft Entra bu içeri aktarma paketini ve karşılık gelen import deyimini gerektirir:

pip install azure-identity

from azure.identity import DefaultAzureCredential

Bu örnekte, Microsoft Entra uygulama kaydının istemci sırrı, istemci kimliği ve kiracı kimliği çevre değişkenlerine eklenmiştir. Bu ortam değişkenleri tarafından DefaultAzureCredential uygulamanın kimliğini doğrulamak için kullanılır. Başarılı bir Microsoft Entra kimlik doğrulamanın sonucu, IoT Hub bağlantı yöntemine aktarılan bir güvenlik jetonu kimlik bilgisidir.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Sonuçta elde edilen AccessToken, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanmak amacıyla from_token_credential'ye geçirilebilir.

IoT Hub'a Entra belirteci kimlik bilgilerini kullanarak hizmet bağlantısı oluşturmak için IoTHubRegistryManager.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential iki parametre gerektirir:

Azure hizmet URL'si - Azure hizmet URL'si ön ek olmadan {Your Entra domain URL}.azure-devices.net biçiminde https:// olmalıdır. Örneğin, MyAzureDomain.azure-devices.net.
Azure kimlik bilgisi belirteci

Bu örnekte, Azure kimlik bilgileri DefaultAzureCredential kullanılarak elde edilir. Ardından, IoT Hub'a IoTHubRegistryManager.from_token_credential bağlantı oluşturmak için Azure hizmet URL'si ve kimlik bilgileri sağlanır.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Kod örnekleri

Microsoft Entra hizmeti kimlik doğrulamasının örnek çalışmaları için bkz. Python için Microsoft Authentication Library (MSAL).

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

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

Bu örnek, region ve plant etiket bilgilerini günceller ve power_level istenen özelliği 1 olarak ayarlar.

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ştur

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 şu adımları izleyin:

SQL benzeri bir sorgu isteği tanımlamak için QuerySpecification nesnesi kullanın.
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.

Node.js sürüm 10.0.x veya üzerini gerektirir

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 nesneler tarafından bildirilen özellikleri okuyup yazabilir ve bir arka uç uygulaması veya IoT Hub tarafından ayarlanan istenen ikiz nesne ö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 ikizini al ve bildirilen özellikleri incele
Bildirilen cihaz ikizi özelliklerini güncelle
İstenilen mülk değişiklikleri ile ilgili bildirimleri alın

Önemli

Cihaz SDK'sı paketini 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

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması aşağıdaki yöntemleri kullanarak IoT Hub ile kimlik doğrulaması yapabilir:

X.509 sertifikası
Paylaşılan erişim anahtarı

Önemli

X.509 sertifikası kullanarak kimlik doğrulaması

X.509 sertifikası cihazdan IoT Hub'a bağlantı aktarımına eklenir.

X.509 sertifikası kullanarak cihazdan IoT Hub'a bağlantıyı yapılandırmak için:

fromConnectionString çağrısını, cihaz veya kimlik modülü bağlantı dizesini ve aktarım türünü Client nesnesine eklemek için yapın. Bağlantı dizesine bir sertifika eklendiğini belirtmek için x509=true ifadesini DeviceClientOptions öğesine ekleyin. Örneğin:
- Bir cihaz bağlantı dizesi:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Kimlik modülü bağlantı dizesi:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Sertifika ayrıntılarıyla bir JSON değişkeni yapılandırın ve DeviceClientOptions'a geçirin.
İstemci aktarımına bir X.509 sertifikası ve anahtarı (ve isteğe bağlı olarak parola) eklemek için setOptions'ı çağırın.
Cihazdan IoT Hub'a bağlantıyı açmak için open çağrısı yapın.

Bu örnekte, bir JSON değişkeni içindeki sertifika yapılandırma bilgileri gösterilir. Sertifika yapılandırması clientOptionssetOptions'e geçirilir ve open kullanılarak bağlantı açılır.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Sertifika kimlik doğrulaması hakkında daha fazla bilgi için bkz:

Kod örneği

Cihaz X.509 sertifika kimlik doğrulamasının çalışan bir örneği için bkz . Basit örnek cihaz X.509.

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

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: Http olarak kullanıldığında, Client örneği IoT Hub'dan gelen iletileri seyrek olarak 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 ikizini al ve bildirilen özellikleri incele

Mevcut cihaz ikizi bilgilerini bir Twin nesnesine çekmek 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

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çimindeki cihaz ikizi yaması, patch değişkeninde saklanır. Düzeltme eki, cihaz ikizi connectivity güncelleştirme değerini cellulariçerir. Düzeltme eki ve hata işleyici update yöntemine 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();
      }
  });

İstenilen mülk değişiklikleri ile ilgili bildirimleri alın

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 grubu altında herhangi bir değişiklik olursa bir olay bildirimi al.
Tek bir özellik değişikliği için etkinlik alma

Tek bir olay işleyicisi ile tüm yamaları alın.

İ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 grubu altında herhangi bir değişiklik olursa bir olay bildirimi al.

Bir özellik grubu altında herhangi bir değişiklik olursa, bir olayı almak için bir dinleyici oluşturabilirsiniz.

Örneğin:

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

Arka uç hizmet uygulaması bu düzeltmeyi minTemperature ve maxTemperature istenen özellikleri güncellemek için uygular.

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

Bu kod, properties.desired.climate özellik gruplandırması içindeki değişiklikler için tetikleyen istenen özellikler değişikliği olay dinleyicisi olarak 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 etkinlik alma

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

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

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

Özellik yalnızca fanOn değiştiğinde dinleyici 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:

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 ikizini alır ve günceller
Cihaz ikizi için sorgu oluşturur

Hizmet SDK'sı paketini 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

Aşağıdaki yöntemleri kullanarak bir arka uç hizmetini IoT Hub'a bağlayabilirsiniz:

Paylaşılan erişim ilkesi
Microsoft Entra

Önemli

Paylaşılan erişim ilkesi kullanarak bağlanma

IoT hub'ına bağlanmak için fromConnectionString komutunu kullanın. Uygulamanızın 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 zaten bir tane yoksa bir tane oluşturmanız gerekir. Bu paylaşılan erişim ilkesinin bağlantı dizesini, fromConnectionString için bir parametre olarak sağlayın. Paylaşılan erişim ilkeleri hakkında daha fazla bilgi için bkz . Paylaşılan erişim imzalarıyla IoT Hub'a erişimi denetleme.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Microsoft Entra kullanarak bağlanma

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve güvenlik belirteci kimlik bilgilerini alması gerekir. Bu belirteç, bir IoT Hub bağlantı yöntemine iletilir. IoT Hub için Microsoft Entra'yı ayarlama ve kullanma hakkında genel bilgi için bkz . Microsoft Entra Id kullanarak IoT Hub'a erişimi denetleme.

Node.js SDK kimlik doğrulamasına genel bakış için bkz:

Microsoft Entra uygulamasını yapılandırma

İstemci sırrı
Sertifika
Federe kimlik bilgileri

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak için IoT Hub Twin Katkı Sağlayıcı gereklidir. Daha fazla bilgi için bkz . Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme.

Microsoft Entra uygulamasını ayarlama hakkında daha fazla bilgi için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile uygulama kaydetme.

DefaultAzureCredential kullanarak kimlik doğrulaması

Arka uç uygulamasının kimliğini doğrulamak için Microsoft Entra kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya azaltılmış bir ChainedTokenCredential gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde DefaultAzureCredential ve istemci sırrı kullanılarak kimlik doğrulaması açıklanmaktadır. kullanmanın DefaultAzureCredentialavantajları ve dezavantajları hakkında daha fazla bilgi için bkz . JavaScript için Azure Identity istemci kitaplığında kimlik bilgileri zincirleri

Microsoft Entra bu paketi gerektirir:

npm install --save @azure/identity

Bu örnekte, Microsoft Entra uygulama kaydının istemci sırrı, istemci kimliği ve kiracı kimliği çevre değişkenlerine eklenmiştir. Bu ortam değişkenleri tarafından DefaultAzureCredential uygulamanın kimliğini doğrulamak için kullanılır. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, IoT Hub bağlantı yöntemine iletilen bir güvenlik belirteci kimlik bilgisi olur.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Sonuçta elde edilen kimlik bilgisi belirteci, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanmak üzere fromTokenCredential'a geçirilebilir:

fromTokenCredential iki parametre gerektirir:

Azure hizmet URL'si - Azure hizmet URL'si ön ek olmadan {Your Entra domain URL}.azure-devices.net biçiminde https:// olmalıdır. Örneğin, MyAzureDomain.azure-devices.net.
Azure kimlik doğrulama belirteci

Bu örnekte, Azure kimlik bilgileri DefaultAzureCredential kullanılarak elde edilir. Ardından IoT Hub'a bağlantı oluşturmak için Registry.fromTokenCredential Azure etki alanı URL'si ve kimlik bilgileri sağlanır.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Kod örnekleri

Microsoft Entra hizmeti kimlik doğrulamasının çalışma örnekleri için bkz . Azure kimlik örnekleri.

Cihaz ikizini 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 ikizini güncelleştirmek için:

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

Cihaz ikizi güncellemesini içeren bir yamayı formatlayın. Düzeltme eki, twin sınıfında açıklandığı gibi JSON biçiminde biçimlendirilir. Arka uç servis yamaları 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.

Cihaz ikizini düzeltme ekiyle güncellemek için update çağrısını yapın.

Bu örnekte, myDeviceId için cihaz ikizi alınır ve ardından location etiket güncelleştirmesini içeren bir düzeltme eki region: 'US', plant: 'Redmond43' ikizlere 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ştur

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 kontrol edebileceğiniz bir boole özelliği içerir ve tüm sonuçları almak için gereken sayıda sonraki ikiz sonuçlar sayfasını almak için hasMoreResults yöntemini kullanabilirsiniz. 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 Cihaz İkizi Arka Uç Hizmeti'ne bakın - Bu proje, belirli bir cihaza yönelik cihaz ikizi yamaları göndermek için kullanılır.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-04-10

Aracılığıyla paylaş

Cihaz ikizleriyle başlayın

Önkoşullar

Genel bakış

Cihaz uygulaması oluşturma

Gerekli cihaz NuGet paketi

IoT Hub’a cihaz bağlama

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

X.509 sertifikası kullanarak kimlik doğrulaması

Kod örnekleri

Cihaz ikizini al ve özelliklerini incele

Bildirilen cihaz ikizi özelliklerini güncelle

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

SDK cihaz örneği

Arka uç uygulaması oluşturma

NuGet Paketi hizmeti ekleme

IoT hub'ına bağlanma

Paylaşılan erişim ilkesi kullanarak bağlanma

Microsoft Entra kullanarak bağlanma

Microsoft Entra uygulamasını yapılandırma

DefaultAzureCredential kullanarak kimlik doğrulaması

Kod örneği

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

Cihaz ikizi etiketlerini okuma ve güncelleştirme

İkiz nesnesi kullanarak etiketleri güncelleştirme

JSON dizesi kullanarak etiketleri güncelleştirme

İkiz istenen özellikleri görüntüle ve güncelleştir

Diğer ikiz güncelleme yöntemleri

Cihaz ikizi sorgusu oluştur

SDK hizmet örneği

Genel bakış

Cihaz uygulaması oluşturma

Cihaz import ifadeleri

IoT Hub’a cihaz bağlama

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

X.509 sertifikası kullanarak kimlik doğrulaması

Kod örnekleri

Cihaz ikizini alma ve görüntüleme

Cihaz ikizinin bildirilen özelliklerini güncelleştir.

İstenen özellik değişikliklerine abone olma

SDK cihaz örneği

Arka uç uygulaması oluşturma

Hizmet import ifadeleri

IoT Hub'a bağlanma

Paylaşılan erişim ilkesi kullanarak bağlanma

Microsoft Entra kullanarak bağlanma

Microsoft Entra uygulamasını yapılandırma

DefaultAzureCredential kullanarak kimlik doğrulaması

ClientSecretCredentialBuilder kullanarak kimlik doğrulaması yapma

Diğer kimlik doğrulama sınıfları

Kod örnekleri

Cihaz ikizi alanlarını güncelleştirme

Cihaz ikizi sorgusu oluştur

SDK hizmet örneği

Genel bakış

Paketleri yükleme

Cihaz uygulaması oluşturma

Cihaz import ifadesi

IoT Hub’a cihaz bağlama

Paylaşılan erişim anahtarı kullanarak kimlik doğrulaması yapma

X.509 sertifikası kullanarak kimlik doğrulaması

Kod örnekleri

Cihaz ikizini al ve bildirilen özellikleri incele

Cihaz dijital ikizi özellikleri güncellemesi rapor edildi.

İstenen gelen özellikler güncelleme işleyicisi

SDK cihaz örnekleri

Arka uç uygulaması oluşturma

IoT hub'ına bağlanma

Paylaşılan erişim ilkesi kullanarak bağlanma

Microsoft Entra kullanarak bağlanma

Microsoft Entra uygulamasını yapılandırma

DefaultAzureCredential kullanarak kimlik doğrulaması

Kod örnekleri

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

Cihaz ikizi sorgusu oluştur

SDK hizmet örneği

Genel bakış

Cihaz uygulaması oluşturma

Cihaz SDK'sı paketini yükleme

IoT Hub’a cihaz bağlama