Cihaz ikizlerini kullanmaya başlama

• 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 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

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ı

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:

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

2. Cihazı bir X.509 sertifikası kullanarak IoT Hub'a bağlamak için DeviceClient.Create kullanın.

Bu örnekte, cihaz ve sertifika bilgileri öğesine DeviceClient.Creategeçirilen nesnede authDeviceAuthenticationWithX509Certificate 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:

• X.509 sertifikalarıyla kimlik doğrulaması
• Öğretici: Test için sertifika oluşturma ve karşıya yükleme

Kod örnekleri

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

• X.509 sertifikasıyla bağlanma
• DeviceClientX509AuthenticationE2ETests
• Destekli proje - IoT Hub Cihazı Sağlama Hizmeti ile IoT cihazlarını güvenli ve uygun ölçekte sağlama

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

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.

Hizmet NuGet Paketi 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

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 ilkesini parametresi olarak bağlantı dizesi sağlayınfromConnectionString. 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 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.

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulaması kimlik bilgileri için yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulaması için kullanılan gizli dizi gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

• İstemci gizli anahtarı
• Sertifika
• Federasyon kimliği 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 TokenCredential veya ayrıştırılmış ChainedTokenCredentialbir dahil olmak üzere farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde kullanarak DefaultAzureCredential kimlik doğrulaması ve İstemci gizli dizisi açıklanmaktadır. kullanmanın DefaultAzureCredentialavantajları 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ışan bir kimlik bilgisi bulana kadar sırayla birden çok kimlik bilgisi türü 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ı istemci gizli dizisi, 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ının sonucu, IoT Hub bağlantı yöntemine geçirilen bir güvenlik belirteci kimlik bilgisidir.

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:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

Bu örnekte, TokenCredential bir RegistryManager nesnesi oluşturmak için öğesine geçirilirRegistryManager.Create.

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'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 TwinTags 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.

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

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ı

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

Bir cihazı IoT Hub'a bağlamak 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);
   

X.509 sertifikası kullanarak kimlik doğrulaması

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

1. buildSSLContext kullanarak SSLContext nesnesini derleyin.
2. SSLContext Bilgileri clientOptions nesnesine ekleyin.
3. Cihazdan ClientOptions IoT Hub'a bağlantıyı oluşturmak için bilgileri kullanarak DeviceClient'ı ç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:

• X.509 sertifikalarıyla kimlik doğrulaması
• Öğretici: Test için sertifika oluşturma ve karşıya yükleme

Kod örnekleri

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

• Gönderme-alma x509 örneği
• Olay gönderme x509

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'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

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

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.

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 ilkesini parametresi olarak bağlantı dizesi sağlayınfromConnectionString. 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ı için bu bölüm, istemci gizli dizisini kullanarak kimlik doğrulamasını açıklamaya odaklanır.

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulaması kimlik bilgileri için yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulaması için kullanılan gizli dizi gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

• İstemci gizli anahtarı
• Sertifika
• Federasyon kimliği 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 TokenCredential veya ayrıştırılmış ChainedTokenCredentialbir dahil olmak üzere farklı bir yöntem kullanılması önerilir. kullanmanın DefaultAzureCredentialavantajları ve dezavantajları hakkında daha fazla bilgi için bkz . Java için Azure Identity istemci kitaplığındaki kimlik bilgileri zincirleri.

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ışan bir kimlik bilgisi bulana kadar sırayla birden çok kimlik bilgisi türü 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 oluşturucuya 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, Ortam değişkenlerine Microsoft Entra uygulama kaydı istemci gizli dizisi, istemci kimliği ve kiracı kimliği değerleri eklenmiştir. Bu ortam değişkenleri tarafından ClientSecretCredentialBuilder kimlik bilgilerini 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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

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

• 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 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

Cihaz içeri aktarma deyimi

İşlevleri azure.iot.device SDK'sından içeri aktarmak IoTHubDeviceClient 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ı

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

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

1. Cihaz birincil bağlantı dizesi eklemek için create_from_connection_string'ı çağırın.
2. 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:

1. X.509 sertifika parametrelerini eklemek için create_from_x509_certificate kullanma
2. Cihaz istemcisini bağlamak için arama bağlantısı

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 os.getenv("HOSTNAME") .

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

• X.509 sertifikalarıyla kimlik doğrulaması
• Öğretici: Test için sertifika oluşturma ve karşıya yükleme

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

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

• Paylaşılan erişim ilkesi
• Microsoft Entra

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 ilkesini parametresi olarak bağlantı dizesi sağlayınfromConnectionString. 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 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.

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

Tercih ettiğiniz kimlik doğrulaması kimlik bilgileri için yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulaması için kullanılan gizli dizi gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

• İstemci gizli anahtarı
• Sertifika
• Federasyon kimliği 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 TokenCredential veya ayrıştırılmış ChainedTokenCredentialbir dahil olmak üzere farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde kullanarak DefaultAzureCredential kimlik doğrulaması ve İstemci gizli dizisi açıklanmaktadır. kullanmanın DefaultAzureCredentialavantajları ve dezavantajları hakkında daha fazla bilgi için bkz . Python için Azure Identity istemci kitaplığındaki kimlik bilgileri zincirleri.

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ışan bir kimlik bilgisi bulana kadar sırayla birden çok kimlik bilgisi türü kullanmayı dener.

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, Ortam değişkenlerine Microsoft Entra uygulama kaydı istemci gizli dizisi, istemci kimliği ve kiracı kimliği 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 geçirilen bir güvenlik belirteci 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 üzere öğesine geçirilebilir from_token_credential :

• Entra belirteci kimlik bilgilerini kullanarak IoT Hub'a 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 https:// biçiminde {Your Entra domain URL}.azure-devices.net olmalıdır. Örneğin, MyAzureDomain.azure-devices.net.
• Azure kimlik bilgisi belirteci

Bu örnekte Azure kimlik bilgileri kullanılarak DefaultAzureCredentialelde 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 çalışma örnekleri 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.

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.

• 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 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

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ı

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:

1. Cihaz veya kimlik modülünü bağlantı dizesi eklemek ve nesneye aktarım türü eklemek için FromConnectionString'den çağrısı yapınClient. x509=true bir sertifikanın öğesine eklendiğini belirtmek için bağlantı dizesi ekleyinDeviceClientOptions. Örneğin:

   • 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

2. Sertifika ayrıntılarıyla bir JSON değişkeni yapılandırın ve DeviceClientOptions'a geçirin.

3. İstemci aktarımına bir X.509 sertifikası ve anahtarı (ve isteğe bağlı olarak parola) eklemek için setOptions'ı çağırın.

4. 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ı clientOptions öğesine setOptionsgeçirilir ve bağlantı kullanılarak openaçı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:

• X.509 sertifikalarıyla kimlik doğrulaması
• Test için sertifika oluşturma ve karşıya yükleme

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- 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ı 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

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 ilkesini parametresi olarak bağlantı dizesi sağlayınfromConnectionString. 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 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.

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

• Azure'da kullanıcı kimlik doğrulaması ile çalışmaya başlama
• JavaScript için Azure Identity istemci kitaplığı

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulaması kimlik bilgileri için yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulaması için kullanılan gizli dizi gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

• İstemci gizli anahtarı
• Sertifika
• Federasyon kimliği 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 TokenCredential veya ayrıştırılmış ChainedTokenCredentialbir dahil olmak üzere farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölümde kullanarak DefaultAzureCredential kimlik doğrulaması ve İstemci gizli dizisi 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

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ışan bir kimlik bilgisi bulana kadar sırayla birden çok kimlik bilgisi türü kullanmayı dener.

Microsoft Entra bu paketi gerektirir:

npm install --save @azure/identity

Bu örnekte, Ortam değişkenlerine Microsoft Entra uygulama kaydı istemci gizli dizisi, istemci kimliği ve kiracı kimliği 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 geçirilen bir güvenlik belirteci kimlik bilgisidir.

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:

• Kapsayıcı Kayıt Defteri
• İstemci
• JobClient

fromTokenCredential iki parametre gerektirir:

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

Bu örnekte Azure kimlik bilgileri kullanılarak DefaultAzureCredentialelde 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 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.