Buluttan cihaza iletileri gönderme - Azure IoT Hub

Cihaz uygulaması oluşturma

Bu bölümde, buluttan cihaza iletilerin nasıl alındığı açıklanır.

Bir cihaz istemci uygulamasının iletileri almak için kullanabileceği iki seçenek vardır:

Callback: Cihaz uygulaması, bir mesaj geldiğinde hemen çağrılan zaman uyumsuz bir mesaj işleyici yöntemi ayarlar.
Yoklama: Cihaz uygulaması, bir kod döngüsü (örneğin, bir while veya for döngüsü) kullanarak yeni IoT Hub iletilerini kontrol eder. Döngü sürekli olarak yürütülür ve iletiler kontrol ediliyor.

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 ifadeleri ekleyin.

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

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ı, cihazda ileti almak için gereken tüm yöntemleri kullanıma sunar.

CreateFromConnectionString yöntemini kullanarak IoT Hub birincil bağlantı dizesi ve Cihaz Kimliğini DeviceClient sağlayın. Gerekli IoT Hub birincil bağlantı dizesi ek olarak, CreateFromConnectionString yöntemi şu isteğe bağlı parametreleri içerecek şekilde aşırı yüklenebilir:

transportType - Aktarım protokolü: HTTP sürüm 1, AMQP veya MQTT çeşitlemeleri. AMQP varsayılan değerdir. Kullanılabilir tüm değerleri görmek için bkz. TransportType Sabit Listesi.
transportSettings - DeviceClient ve ModuleClient için çeşitli aktarıma özgü ayarları tanımlamak için kullanılan arabirim. Daha fazla bilgi için ITransportSettings Arabirimi'ne bakın.
ClientOptions - Başlatma sırasında cihaz veya modül istemci örneğinin yapılandırılmasına izin veren seçenekler.

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

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:

X.509 sertifikasıyla bağlanma
DeviceClientX509AuthenticationE2ETests (X509 Kimlik Doğrulama E2E Testleri)
Destekli proje - IoT Hub Cihazı Sağlama Hizmeti ile IoT cihazlarını güvenli ve uygun ölçekte sağlama

Geri Çağrı

Cihaz uygulamasında geri arama buluttan cihaza iletileri almak için uygulamanın IoT Hub'a bağlanması ve gelen iletileri işlemek için bir geri çağırma dinleyicisi ayarlaması gerekir. Cihaza gelen iletiler IoT Hub ileti kuyruğundan alınır.

Cihaz uygulaması, geri çağırma özelliğini kullanarak SetReceiveMessageHandlerAsync kullanarak bir ileti işleyici yöntemi ayarlar. İleti işleyicisi çağrılır ve bir ileti alınır. İletileri almak için bir geri çağırma yöntemi oluşturmak, alınan iletiler için sürekli yoklama gereksinimini ortadan kaldırır.

Geri çağırma yalnızca şu protokoller kullanılarak kullanılabilir:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only

Http1 protokol seçeneği, SDK yöntemlerinin alınan mesajları yine de yoklaması gerekeceğinden, geri çağırmaları desteklemez ve bu da geri çağırma ilkesine ters düşer.

Bu örnekte, SetReceiveMessageHandlerAsync, her ileti alındığında çağrılan, OnC2dMessageReceivedAsync adlı bir geri çağırma işleyicisi yöntemi ayarlar.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Yoklama

Yoklama, iletileri denetlemek için ReceiveAsync kullanır.

ReceiveAsync bir çağrı şu şekilleri alabilir:

ReceiveAsync() - Devam etmeden önce ileti için varsayılan zaman aşımı süresini bekleyin.
ReceiveAsync (Timespan) - Belirli bir zaman aşımı kullanarak cihaz kuyruğundan bir mesaj alın.
ReceiveAsync (CancellationToken) - İptal tokeni kullanarak cihaz kuyruğundan bir ileti alın. İptal belirteci kullanılırken varsayılan zaman aşımı süresi kullanılmaz.

MQTT veya AMQP yerine HTTP 1 aktarım türü kullanıldığında, ReceiveAsync yöntemi hemen döndürür. HTTP 1 ile buluttan cihaza iletiler için desteklenen desen, iletileri seyrek olarak (en az 25 dakikada bir) denetleyen aralıklı bağlı cihazlardır. Daha fazla HTTP 1 isteği gönderilmesi, IoT Hub'ın bu istekleri sınırlamasına neden olur. MQTT, AMQP ve HTTP 1 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.

CompleteAsync yöntemi

Cihaz bir ileti aldıktan sonra cihaz uygulaması, IoT Hub'a iletinin başarıyla işlendiğini ve iletinin IoT Hub cihaz kuyruğundan güvenli bir şekilde kaldırılabildiğini bildirmek için CompleteAsync yöntemini çağırır. Cihaz, kullandığı aktarım protokolünden bağımsız olarak işlemi başarıyla tamamlandığında bu yöntemi çağırmalıdır.

Mesajı terket, reddet veya süresi dolsun

AMQP ve HTTP sürüm 1 protokolleri ile, ancak MQTT protokolüyle değil, cihaz şunları da yapabilir:

AbandonAsync'i çağırarak bir iletiyi bırakın. Bu, IoT Hub'ın iletinin gelecekte kullanılmak üzere cihaz kuyruğunda saklanmasını sağlar.
RejectAsync'i çağırarak bir iletiyi reddedin. Bu işlem, iletiyi cihaz kuyruğundan kalıcı olarak kaldırır.

Cihazın iletiyi tamamlamasını, bırakmasını veya reddetmesini engelleyen bir şey olursa, IoT Hub sabit bir zaman aşımı süresinden sonra iletiyi yeniden teslim için kuyruğa alır. Bu nedenle, cihaz uygulamasındaki ileti işleme mantığının idempotent (aynı operasyonda değişiklik yapmadan tekrarlayan işlemler) olması gerekir, böylece aynı iletiyi birden çok kez almak aynı sonucu verir.

Buluttan cihaza ileti yaşam döngüsü ve IoT Hub'ın buluttan cihaza iletileri nasıl işlediği hakkında daha fazla bilgi için bkz . IoT hub'ından buluttan cihaza iletiler gönderme.

Yoklama döngüsü

Uygulama, yoklama adı verilen bir yöntemle çalışarak, durdurulana kadar yeni iletileri kontrol etmek için ReceiveAsync yöntemini tekrar tekrar çağıran bir kod döngüsü kullanır.

Bir zaman aşımı değeri veya varsayılan zaman aşımı ile kullanılıyorsa ReceiveAsync , döngüde her çağrı ReceiveAsync belirtilen zaman aşımı süresini bekler. ReceiveAsync zaman aşımına uğradığında, bir null değeri döndürülür ve döngü devam eder.

Bir ileti alındığında, tarafından bir ReceiveAsync nesnesi döndürülür ve bu nesne CompleteAsync'e geçirilmelidir. Belirtilen iletiyi, CompleteAsync parametresine göre ileti kuyruğundan silmesi için IoT Hub'ı Task bildiren bir çağrı.

Bu örnekte döngü, bir ileti alınana veya yoklama döngüsü durdurulana kadar çağrı ReceiveAsync yapar.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Mesaj tekrar deneme politikasını alma

Cihaz istemci iletisi yeniden deneme ilkesi DeviceClient.SetRetryPolicy kullanılarak tanımlanabilir.

İleti yeniden deneme zaman aşımı DeviceClient.OperationTimeoutInMilliseconds özelliğinde depolanır.

SDK ileti alma örneği

.NET/C# SDK'sı, bu bölümde açıklanan ileti alma yöntemlerini içeren bir İleti Alma örneği içerir.

Arka uç uygulaması oluşturma

Bu bölümde, .NET için Azure IoT SDK'sında ServiceClient sınıfını kullanarak bir çözüm arka uç uygulamasından IoT cihazına ileti göndermeye yönelik temel kod açıklanmaktadır. Daha önce açıklandığı gibi, bir çözüm arka uç uygulaması bir IoT Hub'a bağlanır ve iletiler hedef cihazla kodlanmış IoT Hub'a gönderilir. IoT Hub gelen iletileri ileti kuyruğuna depolar ve iletiler IoT Hub ileti kuyruğundan hedef cihaza teslim edilir.

Çözüm arka uç uygulaması, ioT Hub'a gönderilen ve ileti kuyruğu üzerinden cihaz teslimini hedefleyen bir ileti için de teslim geri bildirimi isteyebilir ve alabilir.

Hizmeti NuGet Paketi olarak ekle

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. Gerekli IoT Hub birincil bağlantı dizesi ek olarak, CreateFromConnectionString yöntemi şu isteğe bağlı parametreleri içerecek şekilde aşırı yüklenebilir:

transportType - Amqp veya Amqp_WebSocket_Only.
transportSettings - Hizmet İstemcisi için AMQP ve HTTP proxy ayarları.
ServiceClientOptions - Başlatma sırasında hizmet istemci örneğinin yapılandırılmasına izin veren seçenekler. Daha fazla bilgi için bkz . ServiceClientOptions.

Bu örnek, IoT Hub bağlantı dizesi ve varsayılan ServiceClient aktarım kullanarak Amqp nesnesini oluşturur.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.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 token 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.

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulama amacıyla kullanılan istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

İstemci gizliliği
Sertifika
Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak 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 daha sadeleştirilmiş bir ChainedTokenCredential tercihi gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölüm DefaultAzureCredential ve İstemci gizli anahtarı kullanılarak kimlik doğrulamanın nasıl yapıldığını açıklar. Daha fazla bilgi için DefaultAzureCredential kullanmanın avantajları ve dezavantajları ile ilgili olarak 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 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 (Azure Kimlik)

using Azure.Core;
using Azure.Identity;

Bu örnekte, Microsoft Entra uygulama kaydı 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ının sonucu, bir IoT Hub bağlantı yöntemine aktarılan 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:

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

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

Bu örnekte, TokenCredential öğesi RegistryManager.Create'e bir RegistryManager nesnesi oluşturmak için geçirilir.

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.

Zaman uyumsuz bir buluttan cihaza ileti gönderme

Buluttan (IoT Hub) cihaza bir uygulamadan zaman uyumsuz ileti göndermek için sendAsync'i kullanın. Çağrı AMQP protokolü kullanılarak yapılır.

sendAsync şu parametreleri kullanır:

deviceID - Hedef cihazın dize tanımlayıcısı.
message - Buluttan cihaza ileti. İleti İleti türündedir ve buna göre biçimlendirilebilir.
timeout - İsteğe bağlı bir zaman aşımı değeri. Belirtilmezse varsayılan değer bir dakikadır.

Bu örnek, hedef cihaza 10 saniyelik zaman aşımı değeriyle bir test iletisi gönderir.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Teslimat geri bildirimi alma

Gönderen bir program, buluttan cihaza her ileti için IoT Hub'dan teslim (veya süre sonu) bildirimleri isteyebilir. Bu seçenek, gönderen programın bilgilendirme, yeniden deneme veya telafi mantığını kullanmasını sağlar. İleti geri bildirimi işlemlerinin ve özelliklerinin tam açıklaması İleti geri bildirimi sayfasında açıklanmıştır.

İleti teslimi geri bildirimi almak için:

feedbackReceiver Nesneyi oluşturma
parametresini Ack kullanarak ileti gönderme
Geri bildirim almayı bekleyin

feedbackReceiver nesnesini oluşturma

FeedbackReceiver nesnesi oluşturmak için GetFeedbackReceiver çağrısı yapın. FeedbackReceiver , hizmetlerin geri bildirim alma işlemlerini gerçekleştirmek için kullanabileceği yöntemleri içerir.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Ack parametresini kullanarak ileti gönderme

Teslim geri bildirimi almak için her iletinin teslim bildirimi Ack özelliği için bir değer içermesi gerekir. Ack özelliği şu değerlerden biri olabilir:

none (varsayılan): geri bildirim iletisi oluşturulmaz.
Positive: İleti tamamlandıysa bir geri bildirim iletisi alın.
Negative: cihaz tarafından tamamlanmadan iletinin süresi dolduysa (veya teslim sayısı üst sınırına ulaşıldıysa) bir geri bildirim iletisi alın.
Full: hem Positive hem de Negative sonuçlar için geri bildirim.

Bu örnekte, Ack özelliği Full olarak ayarlanmıştır ve bir ileti için hem olumlu hem de olumsuz teslim geri bildirimi istenmektedir.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Geri bildirim almayı bekleyin

bir CancellationTokentanımlayın. Ardından döngüde ReceiveAsync'i tekrar tekrar çağırarak teslim geri bildirim iletilerini kontrol edin. Her bir ReceiveAsync çağrısı, ServiceClient nesnesi için tanımlanan zaman aşımı süresini bekler.

ReceiveAsync Zaman aşımı süresi dolduğunda ve herhangi bir ileti alınmazsa, ReceiveAsyncnull döndürür ve döngü devam eder.
Geri bildirim iletisi alındığında, tarafından bir ReceiveAsync nesnesi döndürülür ve bu nesne, iptal belirteciyle birlikte CompleteAsync'e geçirilmelidir. CompleteAsync çağrısı, belirli Task parametresine göre gönderilen mesajı ileti kuyruğundan siler.
Gerekirse alma kodu, gönderme iletisini kuyruğa geri yerleştirmek için AbandonAsync'i çağırabilir.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

Bu örnekte bu adımları içeren bir yöntem gösterilmektedir.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

Bu geri bildirim alma deseninin, cihaz uygulamasında buluttan cihaza iletileri almak için kullanılan desene benzer olduğunu unutmayın.

Hizmet istemcisi yeniden bağlantısı

Bir özel durumla karşılaşıldığında, hizmet istemcisi bu bilgileri çağıran uygulamaya geçirir. Bu noktada, özel durum ayrıntılarını incelemeniz ve gerekli işlemleri yapmanız önerilir.

Örneğin:

Bu bir ağ özel durumuysa işlemi yeniden deneyebilirsiniz.
Bu bir güvenlik özel durumuysa (yetkisiz özel durum), kimlik bilgilerinizi inceleyin ve bunların güncel olduğundan emin olun.
Azaltma/kota aşıldı özel durumuysa, istek gönderme sıklığını izleyin veya değiştirin ya da hub örneğinizin ölçeklendirme birimini güncelleyin. Ayrıntılar için IoT Hub kotaları ve kısıtlama başlığına bakın.

İleti yeniden deneme politikası

İleti ServiceClient yeniden deneme ilkesi ServiceClient.SetRetryPolicy kullanılarak tanımlanabilir.

SDK ileti gönderme örneği

.NET/C# SDK'sı, bu bölümde açıklanan ileti gönderme yöntemlerini içeren bir Hizmet istemci örneği içerir.

Cihaz uygulaması oluşturma

Bu bölümde, Java için Azure IoT SDK'sından DeviceClient sınıfını kullanarak buluttan cihaza iletilerin nasıl alındığı açıklanmaktadır.

Java tabanlı bir cihaz uygulamasının buluttan cihaza iletileri alabilmesi için IoT Hub'a bağlanması ve ardından IoT Hub'dan gelen iletileri işlemek için bir geri çağırma dinleyicisi ve ileti işleyicisi ayarlaması gerekir.

Azure IoT Java SDK kitaplıklarını içeri aktarma

Bu makalede başvuruda bulunan kod, bu SDK kitaplıklarını kullanır.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

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 nesne örneği için şu parametreler gerekir:

connString - IoT cihazı bağlantı dizesi. Bağlantı dizesi, anahtarlar ve değerlerin '=' ile ayrıldığı ve ';' ile ayrılan bir anahtar-değer çiftleri kümesidir. Bu anahtarlar için değerler içermelidir: HostName, DeviceId, and SharedAccessKey.
Aktarım protokolü - Bağlantı DeviceClient aşağıdaki IoTHubClientProtocol aktarım protokollerinden birini kullanabilir. AMQP en çok yönlüdür, iletileri sık sık denetlemeye olanak tanır ve iletinin reddedilmesine ve iptal edilmesini sağlar. MQTT ileti reddetme veya bırakma yöntemlerini desteklemez:
- AMQPS
- AMQPS_WS
- HTTPS
- MQTT
- MQTT_WS

Örneğin:

static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

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.
DeviceClient'ı kullanarak ClientOptions bilgilerini kullanarak cihazdan IoT Hub'a bağlantıyı oluşturun.

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:

İleti geri çağırma yöntemini ayarlama

IoT Hub'dan bir ileti alındığında bilgilendirilen bir ileti işleyici yöntemi tanımlamak için setMessageCallback yöntemini kullanın.

setMessageCallback şu parametreleri içerir:

callback - Geri çağırma yöntemi adı. olabilir null.
context - isteğe bağlı bir türde bağlam. Belirtilmemişse kullanın null .

Bu örnekte, bağlam parametresi olmayan adlı callback bir MessageCallback yöntem öğesine setMessageCallbackgeçirilir.

client.setMessageCallback(new MessageCallback(), null);

İleti geri çağırma işleyicisi oluşturma

Geri çağırma iletisi işleyicisi, IoT Hub iletileri kuyruğundan geçirilen bir gelen iletiyi alır ve işler.

Bu örnekte, ileti işleyicisi gelen bir iletiyi işler ve ardından IotHubMessageResult.COMPLETE döndürür. Dönüş IotHubMessageResult.COMPLETE değeri IoT Hub'a iletinin başarıyla işlendiğini ve iletinin cihaz kuyruğundan güvenli bir şekilde kaldırılabildiğini bildirir. Cihaz, işleme başarıyla tamamlandığında geri dönmeli IotHubMessageResult.COMPLETE ve ioT Hub'a kullandığı protokolden bağımsız olarak iletinin ileti kuyruğundan kaldırılması gerektiğini bildirmelidir.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

İleti bırakma ve reddetme seçenekleri

Bir cihaza gelen çok sayıda mesajın başarıyla alınması ve başarılı bir şekilde işlenmesi gerekse de, bazen bir mesajı iptal etmek veya reddetmek gerekebilir.

AMQP ve HTTPS ile, ancak MQTT ile değil, bir uygulama şunları yapabilir:
- IotHubMessageResult.ABANDON ileti. IoT hub onu yeniden sıraya alır ve daha sonra tekrar gönderir.
- IotHubMessageResult.REJECT ileti. IoT hub'ı iletiyi yeniden sorgulamaz ve iletiyi ileti kuyruğundan kalıcı olarak kaldırır.
MQTT veya MQTT_WS kullanan istemciler ABANDON veya REJECT mesaj gönderemez.

Cihazın iletiyi tamamlamasını, bırakmasını veya reddetmesini engelleyen bir şey olursa, IoT Hub sabit bir zaman aşımı süresinden sonra iletiyi yeniden teslim için kuyruğa alır. Bu nedenle, cihaz uygulamasındaki ileti işleme mantığının idempotent (aynı operasyonda değişiklik yapmadan tekrarlayan işlemler) olması gerekir, böylece aynı iletiyi birden çok kez almak aynı sonucu verir.

Buluttan cihaza ileti yaşam döngüsü ve IoT Hub'ın buluttan cihaza iletileri nasıl işlediği hakkında daha fazla bilgi için bkz . IoT hub'ından buluttan cihaza iletiler gönderme.

Dikkat

Aktarım olarak MQTT veya AMQP yerine HTTPS kullanırsanız, DeviceClient örneği IoT Hub'dan gelen iletileri seyrek denetler (en az 25 dakikada bir). 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.

İleti durumu geri çağırma yöntemini oluşturma

Bir uygulama, cihazın bağlantı durumu değiştiğinde yürütülecek bir geri çağırma yöntemini kaydetmek için registerConnectionStatusChangeCallback kullanabilir. Bu şekilde uygulama, düşürülen iletilerin bağlantısını algılayabilir ve yeniden bağlanmayı dener.

Bu örnekte, IotHubConnectionStatusChangeCallbackLogger bağlantı durumu değişikliği geri çağırma yöntemi olarak kaydedilir.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

Geri çağırma tetiklenir ve ConnectionStatusChangeContext nesne geçirilir.

Geçerli bağlantı durumunu almak için arayın connectionStatusChangeContext.getNewStatus() .

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

Döndürülen bağlantı durumu şu değerlerden biri olabilir:

IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED

Bağlantı durumu değişikliğinin nedenini almak için arayın connectionStatusChangeContext.getNewStatusReason() .

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Bağlantı durumu değişikliğinin nedenini bulmak için arayın connectionStatusChangeContext.getCause() . getCause() herhangi bir bilgi mevcut değilse null dönebilir.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

Durum değişikliği geri çağırma yöntemi bağlantı durumu değişiklik durumunu ayıklamayı, cihaz durumunun neden değiştiğini ve bağlamı gösteren eksiksiz bir örnek için bu makalenin SDK alma ileti örneği bölümünde listelenen HandleMessages örneğine bakın.

Cihaz ile IoT Hub arasındaki bağlantıyı açma

Cihaz ile IoT Hub arasında bağlantı oluşturmak için open komutunu kullanın. Cihaz artık bir IoT Hub'a zaman uyumsuz olarak ileti gönderip alabilir. İstemci zaten açıksa yöntemi hiçbir şey yapmaz.

client.open(true);

SDK ileti alma örneği

HandleMessages: IoT hub'ınıza bağlanan ve buluttan cihaza iletiler alan Java için Microsoft Azure IoT SDK'sına dahil edilen örnek bir cihaz uygulaması.

Arka uç uygulaması oluşturma

Bu bölümde, Java için Azure IoT SDK'sından ServiceClient sınıfını kullanarak buluttan cihaza ileti gönderme açıklanmaktadır. Bir çözüm arka uç uygulaması bir IoT Hub'a bağlanır ve iletiler hedef cihazla kodlanmış IoT Hub'a gönderilir. IoT Hub gelen iletileri ileti kuyruğuna depolar ve iletiler IoT Hub ileti kuyruğundan hedef cihaza teslim edilir.

Çözüm arka uç uygulaması, ioT Hub'a gönderilen ve ileti kuyruğu üzerinden cihaz teslimini hedefleyen bir ileti için de teslim geri bildirimi isteyebilir ve alabilir.

Bağımlılık ifadesini ekle

IoT hub hizmetinizle iletişim kurmak için uygulamanızda iothub-java-service-client paketini kullanmak için bağımlılığı ekleyin:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

"Import ifadeleri ekle"

Azure IoT Java SDK'sını ve özel durum işleyicisini kullanmak için bu içeri aktarma deyimlerini ekleyin.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

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

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

Bağlantı protokollerini tanımlama

Hizmet istemcisi tarafından ioT Hub ile iletişim kurmak için kullanılan uygulama katmanı protokollerini tanımlamak için IotHubServiceClientProtocol kullanın.

IotHubServiceClientProtocol yalnızca AMQPS veya AMQPS_WS numaralandırmasını kabul eder.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

ServiceClient nesnesini oluşturma

IoT Hub bağlantı dizesini ve protokolünü sağlayan ServiceClient nesnesini oluşturun.

String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);

Uygulama ile IoT Hub arasındaki bağlantıyı açma

AMQP gönderen bağlantısını açın . Bu yöntem, uygulama ile IoT Hub arasında bağlantı oluşturur.

serviceClient.open();

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

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 sırrını kullanarak kimlik doğrulamayı açıklamaya odaklanır.

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulama amacıyla kullanılan istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

İstemci gizliliği
Sertifika
Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak 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 daha sadeleştirilmiş bir ChainedTokenCredential tercihi gibi farklı bir yöntem kullanılması önerilir. kullanmanın avantajları ve dezavantajları hakkında daha fazla bilgi için bkz: DefaultAzureCredential.

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 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 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, Microsoft Entra uygulama kaydı istemci gizli anahtarı, istemci kimliği ve kiracı kimliği değerleri ortam değişkenlerine eklenmiştir. ClientSecretCredentialBuilder kimlik bilgisi oluşturmak için bu ortam değişkenlerini kullanı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.

İleti teslim geri bildirimi için bir geri bildirim alıcısı açma

Gönderilen mesaj teslimatının IoT Hub geri bildirimini almak için bir FeedbackReceiver kullanabilirsiniz. A FeedbackReceiver, Receive yöntemi FeedbackBatch yerine Message döndüren özel bir alıcıdır.

Bu örnekte FeedbackReceiver nesnesi oluşturulur ve open() geri bildirim almak için çağrılır.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

İleti özellikleri ekleme

İsteğe bağlı olarak ileti özellikleri eklemek için setProperties kullanabilirsiniz. Bu özellikler cihaza gönderilen iletiye dahil edilir ve alındıkten sonra cihaz uygulaması tarafından ayıklanabilir.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Zaman uyumsuz ileti oluşturma ve gönderme

İleti nesnesi gönderilecek iletiyi depolar. Bu örnekte "Buluttan cihaza ileti" gönderilir.

SetDeliveryAcknowledgement kullanarak IoT Hub ileti kuyruğuna teslim edildi/teslim edilmedi bildirimi isteyin. Bu örnekte istenen onay, teslim edildi veya teslim edilmedi şeklindedir Full.

İstemciden cihaza zaman uyumsuz bir ileti göndermek için SendAsync'i kullanın. Alternatif olarak, (zaman uyumsuz değil) yöntemini kullanabilirsiniz Send , ancak bu işlev dahili olarak eşitlenir, böylece aynı anda yalnızca bir gönderme işlemine izin verilir. İleti, uygulamadan IoT Hub'a teslim edilir. IoT Hub iletiyi ileti kuyruğuna yerleştirir ve hedef cihaza teslim edilmeye hazırdır.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

İleti teslimi geri bildirimi alma

Uygulamadan bir ileti gönderildikten sonra uygulama, zaman aşımı değeriyle veya zaman aşımı değeri olmadan receive çağrısı yapabilir. Zaman aşımı değeri sağlanmazsa, varsayılan zaman aşımı kullanılır. Bu işlem, incelenebilen ileti teslimi geri bildirim özelliklerini içeren bir FeedbackBatch nesnesini geri geçirir.

Bu örnek, FeedbackBatch alıcısını oluşturur ve iletinin sıralandığı zamanı yazdırmak için getEnqueuedTimeUtc yöntemini çağırır.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

SDK ileti gönderme örnekleri

İki ileti gönderme örneği vardır:

Hizmet istemcisi örneği - İleti örneği gönder, #1.
Hizmet istemcisi örneği - İleti örneği gönder, #2.

Cihaz uygulaması oluşturma

Bu bölümde, buluttan cihaza iletilerin nasıl alındığı açıklanır.

IoTHubDeviceClient sınıfı, bir cihazdan Azure IoT Hub'a zaman uyumlu bağlantı oluşturma ve IoT Hub'dan ileti alma yöntemlerini içerir.

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

pip install azure-iot-device

Python tabanlı bir cihaz uygulamasının buluttan cihaza iletileri alabilmesi için IoT Hub'a bağlanması ve ardından IoT Hub'dan gelen iletileri işlemek için bir geri çağırma iletisi işleyicisi ayarlaması gerekir.

Cihaz içe aktarma bildirimi

Azure.iot.device SDK'sından 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

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

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

Cihaz birincil bağlantı dizesini eklemek için create_from_connection_string'ı çağırın.
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 çağrısını yapı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, 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:

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.

Yeniden bağlanmayı yönetme

IoTHubDeviceClient varsayılan olarak bırakılan bir bağlantıyı yeniden kurmaya çalışır. Yeniden bağlanma davranışı, connection_retryIoTHubDeviceClientyönetilir.

İleti işleyicisi oluşturma

Cihaza gelen iletileri işlemek için bir ileti işleyici işlevi oluşturun. Bu, geri çağırma iletisi işleyicisi olarak (sonraki adım) tarafından on_message_received atanır.

Bu örnekte, message_handler bir ileti alındığında çağrılır. İleti özellikleri (.items) bir döngü kullanılarak konsola yazdırılır.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

İleti işleyicisini atama

İleti işleyici yöntemini atamak için on_message_received yöntemini kullanın.

Bu örnekte adlı bir ileti işleyici yöntemi message_handler nesnesine IoTHubDeviceClientclient eklenir. client nesnesi, IoT Hub'dan buluttan cihaza ileti almak için bekler. Bu kod, ileti için 300 saniyeye (5 dakika) kadar bekler veya klavye tuşuna basıldığında çıkar.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK ileti alma örneği

İleti Alma - Azure IoT Hub'dan bir cihaza gönderilen Buluttan Cihaza (C2D) iletileri alın.

Arka uç uygulaması oluşturma

Bu bölümde buluttan cihaza ileti gönderme açıklanmaktadır. Bir çözüm arka uç uygulaması bir IoT Hub'a bağlanır ve iletiler hedef cihazla kodlanmış IoT Hub'a gönderilir. IoT Hub gelen iletileri ileti kuyruğuna depolar ve iletiler IoT Hub ileti kuyruğundan hedef cihaza teslim edilir.

IoTHubRegistryManager sınıfı, hizmetten gelen buluttan cihaza iletilerle etkileşim kurmak için bir arka uç uygulaması oluşturmak için gereken tüm yöntemleri kullanıma sunar. Arka uç hizmet uygulamaları oluşturmak için azure-iot-hub kitaplığı yüklenmelidir.

pip install azure-iot-hub

IoTHubRegistryManager nesnesini içeri aktarma

Aşağıdaki import deyimi ekleyin. IoTHubRegistryManager , IoT Hub Kayıt Defteri Yöneticisi işlemleri için API'ler içerir.

from azure.iot.hub import IoTHubRegistryManager

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

from_connection_string kullanarak IoT hub'ına bağlanın.

Örneğin:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

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

Microsoft Entra uygulamasını yapılandırma

Tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulama amacıyla kullanılan istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

İstemci gizliliği
Sertifika
Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak 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 daha sadeleştirilmiş bir ChainedTokenCredential tercihi gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölüm DefaultAzureCredential ve İstemci gizli anahtarı kullanılarak kimlik doğrulamanın nasıl yapıldığını açıklar. Daha fazla bilgi için DefaultAzureCredential kullanmanın avantajları ve dezavantajları ile ilgili olarak 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 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 (Azure Kimlik)

using Azure.Core;
using Azure.Identity;

Bu örnekte, Microsoft Entra uygulama kaydı 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ının sonucu, bir IoT Hub bağlantı yöntemine aktarılan 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:

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

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

Bu örnekte, TokenCredential öğesi RegistryManager.Create'e bir RegistryManager nesnesi oluşturmak için geçirilir.

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.

İleti oluşturma ve gönderme

Send_c2d_message kullanarak cihaza bulut üzerinden (IoT Hub) ileti gönderin.

send_c2d_message şu parametreleri kullanır:

deviceID - Hedef cihazın dize tanımlayıcısı.
message - Buluttan cihaza ileti. İleti türündedir str (dize).
properties - isteğe bağlı bir dict türündeki özellikler koleksiyonu. Özellikler, uygulama özelliklerini ve sistem özelliklerini içerebilir. Varsayılan değer şudur: {}.

Bu örnek, hedef cihaza bir test iletisi gönderir.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK ileti gönderme örneği

Python için Azure IoT SDK'sı, buluttan cihaza ileti göndermeyi gösteren çalışan bir hizmet uygulaması örneği sağlar. Daha fazla bilgi için, buluttan cihaza ileti göndermeyi gösteren send_message.py dosyasına bakın.

Cihaz uygulaması oluşturma

Bu bölümde, Node.js için Azure IoT SDK'sında azure-iot-device paketini kullanarak buluttan cihaza iletilerin nasıl alındığı açıklanmaktadır.

Node.js tabanlı bir cihaz uygulamasının buluttan cihaza iletileri alması için IoT Hub'a bağlanması ve ardından IoT Hub'dan gelen iletileri işlemek için bir geri çağırma dinleyicisi ve ileti işleyicisi ayarlaması gerekir. Cihaz uygulaması, cihazdan IoT Hub'a ileti bağlantısının kesilmesi durumunda bağlantı kesilmelerini algılayabilmeli ve işleyebilmelidir.

SDK paketlerini yükleme

azure-iot-device paketi, IoT cihazlarıyla arabirim oluşturan nesneler içerir. 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

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.

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:

tr-TR: Cihaz veya kimlik modülünün bağlantı dizesi ve aktarım türünü nesnesine eklemek için Client çağrısını yapın. Bağlantı dizesine x509=true ekleyerek, bir sertifikanın DeviceClientOptions öğesine eklendiğini belirtin. Ö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ı clientOptions öğesine setOptions aktarılır ve bağlantı open kullanılarak 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

Aktarım protokolü seçme

Client nesnesi şu protokolleri destekler:

Amqp
Http - Http kullanıldığında, Client örneği IoT Hub'dan mesajları seyrek olarak kontrol eder (en az 25 dakikada bir).
Mqtt
MqttWs
AmqpWs

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

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

npm install azure-iot-device-amqp --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.

Bu örnekte AMQP protokolü bir Protocol değişkene atanır. Bu Protokol değişkeni, bu makalenin Client.fromConnectionStringbağlantı dizesi ekle bölümündeki yöntemine geçirilir.

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

İleti tamamlama, reddetme ve bırakma özellikleri

seçilen protokole bağlı olarak ileti tamamlama, reddetme ve bırakma yöntemleri kullanılabilir.

AMQP ve HTTP

AMQP ve HTTP aktarımları bir iletiyi tamamlayabilir, reddedebilir veya bırakabilir:

Tamamla - Bir mesajı tamamlamak için, buluttan cihaza mesajı gönderen hizmete mesajın alındığı bildirilir. IoT Hub iletiyi ileti kuyruğundan kaldırır. Bu yöntem client.complete(message, callback function) biçimindedir.
Reddet - Bir iletiyi reddetmek için, buluttan cihaza iletiyi gönderen hizmete iletinin cihaz tarafından işlenmediği bildirilir. IoT Hub, iletiyi cihaz kuyruğundan kalıcı olarak kaldırır. Bu yöntem client.reject(message, callback function) biçimindedir.
Bırakma - Bir iletiyi bırakmak için IoT Hub hemen yeniden göndermeyi dener. IoT Hub, gelecekte kullanılmak üzere iletiyi cihaz kuyruğunda tutar. Bu yöntem client.abandon(message, callback function) biçimindedir.

MQTT

MQTT ileti tamamlama, reddetme veya bırakma işlevlerini desteklemez. Bunun yerine, MQTT varsayılan olarak bir iletiyi kabul eder ve ileti IoT Hub ileti kuyruğundan kaldırılır.

Yeniden teslim denemeleri

Cihazın iletiyi tamamlamasını, bırakmasını veya reddetmesini engelleyen bir şey olursa, IoT Hub sabit bir zaman aşımı süresinden sonra iletiyi yeniden teslim için kuyruğa alır. Bu nedenle, cihaz uygulamasındaki ileti işleme mantığının idempotent (aynı operasyonda değişiklik yapmadan tekrarlayan işlemler) olması gerekir, böylece aynı iletiyi birden çok kez almak aynı sonucu verir.

İstemci nesnesi oluşturma

Yüklü paketi kullanarak bir Client nesne oluşturun.

Örneğin:

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

Protokol nesnesi oluşturma

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

Bu örnekte AMQP protokolü atanır:

const Protocol = require('azure-iot-device-amqp').Amqp;

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

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

connStr - Cihaz bağlantı dizesi.
transportCtor - Aktarım protokolü.

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

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

Gelen ileti işleyicisi oluşturma

Gelen her ileti için ileti işleyicisi çağrılır.

Bir ileti başarıyla alındıktan sonra AMQP veya HTTP aktarımı kullanılıyorsa ioT Hub'a iletinin ileti kuyruğundan kaldırılabildiğini bildirmek için yöntemini çağırın client.complete .

Örneğin, bu ileti işleyicisi ileti kimliğini ve ileti gövdesini konsola yazdırır, ardından IoT Hub'a iletiyi işlediğini ve cihaz kuyruğundan güvenli bir şekilde kaldırılabildiğini bildirmek için çağırır client.complete . MQTT aktarımı kullanıyorsanız complete çağrısı gerekli değildir ve atlanabilir. AMQP veya HTTPS aktarımı için bir çağrı yapılması gereklidir.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Bağlantı bağlantısı kesme işleyicisi oluşturma

Bağlantı kesildiğinde bağlantı kesme işleyicisi çağrılır. Bağlantı kesme işleyicisi, yeniden bağlanma kodu uygulamak için kullanışlıdır.

Bu örnek, konsolda bağlantı kesilme hata mesajını yakalar ve görüntüler.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Olay dinleyicilerini ekle

.on yöntemini kullanarak bu olay dinleyicilerini belirtebilirsiniz.

Bağlantı işleyicisi
Hata işleyicisi
Bağlantı kesme işleyicisi
İleti işleyicisi

Bu örnek, daha önce tanımlanan ileti ve bağlantı kesme işleyicilerini içerir.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

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 çağırmak için kullanın .catch(err) .

Örneğin:

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

SDK cihaz örnekleri

Node.js için Azure IoT SDK'sı, ileti alma işlemini işleyen bir cihaz uygulamasının çalışma örneğini sağlar. Daha fazla bilgi için bkz.

simple_sample_device - IoT hub'ınıza bağlanan ve buluttan cihaza iletileri alan bir cihaz uygulaması.

Arka uç uygulaması oluşturma

Bu bölümde buluttan cihaza ileti gönderme açıklanmaktadır. Daha önce açıklandığı gibi, bir çözüm arka uç uygulaması bir IoT Hub'a bağlanır ve iletiler hedef cihazla kodlanmış IoT Hub'a gönderilir. IoT Hub gelen iletileri ileti kuyruğuna depolar ve iletiler IoT Hub ileti kuyruğundan hedef cihaza teslim edilir.

Çözüm arka uç uygulaması, ioT Hub'a gönderilen ve ileti kuyruğu üzerinden cihaz teslimini hedefleyen bir ileti için de teslim geri bildirimi isteyebilir ve alabilir.

Hizmet SDK'sı paketini yükleme

azure-iothub paketi, IoT Hub ile arabirim oluşturan nesneler içerir. Bu makalede, IoT Hub aracılığıyla bir uygulamadan cihaza ileti gönderen sınıf kodu açıklanmaktadır Client .

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

npm install azure-iothub --save

İstemci ve ileti modüllerini yükleme

Client paketinden Client sınıfını kullanarak bir azure-iothub nesnesi bildirin.

Message paketinden Message sınıfını kullanarak bir azure-iot-common nesnesi bildirin.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

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

IoT hub'ına bağlanmak için fromConnectionString komutunu kullanın.

Bu örnekte, serviceClient nesnesi aktarım türüyle Amqp oluşturulur.

var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

İstemci bağlantısını açma

Uygulama ile ClientIoT Hub arasında bir bağlantı açmak için open yöntemini çağırın.

open ile veya işlem tamamlandığında çağrılan open bir geri çağırma işlevi belirtilmeden çağrılabilir.

Bu örnekte open yöntemi isteğe bağlı bir açık bağlantı err geri çağırma işlevi içerir. Açık bir hata oluşursa bir hata nesnesi döndürülür. Açık bağlantı başarılı olursa bir null geri çağırma değeri döndürülür.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

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

Tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış bir Microsoft Entra uygulaması ayarlamanız gerekir. Uygulama, arka uç uygulaması tarafından kimlik doğrulama amacıyla kullanılan istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulaması yapılandırmaları şunlardır:

İstemci gizliliği
Sertifika
Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak 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 daha sadeleştirilmiş bir ChainedTokenCredential tercihi gibi farklı bir yöntem kullanılması önerilir. Kolaylık olması için, bu bölüm DefaultAzureCredential ve İstemci gizli anahtarı kullanılarak kimlik doğrulamanın nasıl yapıldığını açıklar. 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 birden çok kimlik bilgisi türünü sırayla kullanmayı dener.

Microsoft Entra bu paketi gerektirir:

npm install --save @azure/identity

Bu örnekte, Microsoft Entra uygulama kaydı istemci sırrı, istemci kimliği ve kiracı kimliği ortam 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, bir IoT Hub bağlantı yöntemine aktarılan 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:

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 belirteci

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

İleti oluşturma

İleti nesnesi zaman uyumsuz buluttan cihaza iletisini içerir. İleti işlevselliği AMQP, MQTT ve HTTP üzerinde aynı şekilde çalışır.

İleti nesnesi, bu özellikler de dahil olmak üzere çeşitli özellikleri destekler. Tam liste için ileti özelliklerine bakın.

ack - Teslimat geri bildirimi. Sonraki bölümde açıklanmıştır.
properties - Özel ileti özelliklerini depolamaya yönelik dize anahtarlarını ve değerlerini içeren bir eşleme.
messageId - İki yönlü iletişimi ilişkilendirmek için kullanılır.

İleti nesnesi örneği oluşturulurken ileti gövdesini ekleyin. Bu örnekte bir 'Cloud to device message.' ileti eklenir.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Teslim bildirimi

Gönderen bir program, buluttan cihaza her ileti için IoT Hub'dan teslim (veya süre sonu) bildirimleri isteyebilir. Bu seçenek, gönderen programın bilgilendirme, yeniden deneme veya telafi mantığını kullanmasını sağlar. İleti geri bildirimi işlemlerinin ve özelliklerinin tam açıklaması İleti geri bildirimi sayfasında açıklanmıştır.

İleti geri bildirimi almak isteyen her mesaj, teslim onayı ack özelliği için bir değer içermelidir. ack özelliği şu değerlerden biri olabilir:

none (varsayılan): geri bildirim iletisi oluşturulmaz.
sent: İleti tamamlandıysa bir geri bildirim iletisi alın.
cihaz tarafından bitirilmeden iletinin süresi dolduysa (veya maksimum teslimat sayısına ulaşıldıysa) bir geri bildirim iletisi alın.
full: hem gönderilen hem de gönderilmeyen sonuçlar için geri bildirim.

Bu örnekte, ack özelliği full olarak ayarlanmıştır ve bir ileti için hem gönderilmiş hem de gönderilmemiş iletiler için teslimat geri bildirimi talep edilmektedir.

message.ack = 'full';

İleti geri bildirim alıcısını bağlama

Mesaj geri bildirim alıcı geri çağırma fonksiyonu, Client'ye getFeedbackReceiver kullanılarak bağlanır.

İleti geri bildirimi alıcısı iki argüman alır:

Hata nesnesi (null olabilir)
AmqpReceiver nesnesi, istemci tarafından yeni geri bildirim iletileri alındığında olaylar yayar.

Bu örnek fonksiyon, bir teslimat geri bildirim mesajını kabul eder ve konsola yazdırır.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Bu kod, geri bildirim geri çağırma fonksiyonunu receiveFeedback kullanarak Client hizmet getFeedbackReceiver nesnesine bağlar.

serviceClient.getFeedbackReceiver(receiveFeedback);

İleti tamamlama sonuçları işleyicisi tanımlama

İleti gönderme tamamlama geri çağırma işlevi, her ileti gönderildikten sonra çağrılır.

Bu örnek işlev, ileti send işlemi sonuçlarını konsola yazdırır. Bu örnekte, printResultFor işlevi, bir parametre olarak sonraki bölümde açıklanan send işlevine sağlanır.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

İleti gönderme

IoT Hub aracılığıyla cihaz uygulamasına zaman uyumsuz bir buluttan cihaza ileti göndermek için send işlevini kullanın.

send şu parametreleri destekler:

deviceID - Hedef cihazın cihaz kimliği.
message - Cihaza gönderilecek iletinin gövdesi.
done - İşlem tamamlandığında çağrılacak isteğe bağlı işlev. Done'ın iki bağımsız değişkenle çağrıldığı:
- Hata nesnesi (null olabilir).
- Taşıma sürecine özgü yanıt nesnesi, günlük tutma veya hata ayıklama için kullanışlıdır.

Bu kod, IoT Hub aracılığıyla cihaz uygulamasına buluttan cihaza ileti göndermeyi çağırır send . Önceki bölümde tanımlanan geri çağırma işlevi printResultFor , teslim onay bilgilerini alır.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

Bu örnekte, cihazınıza ileti gönderme ve cihaz buluttan cihaza iletisini kabul ettiğinde geri bildirim iletisini işleme işlemleri gösterilmektedir:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

SDK ileti gönderme örneği

Node.js için Azure IoT SDK'sı, ileti gönderme görevlerini işleyen bir hizmet uygulamasının çalışma örneklerini sağlar. Daha fazla bilgi için bkz.

send_c2d_message.js - IoT Hub aracılığıyla bir cihaza C2D iletileri gönderin.

Aracılığıyla paylaş

Buluttan cihaza ileti gönderme ve alma

Genel bakış

İleti sırasını anlama

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

Geri Çağrı

Yoklama

CompleteAsync yöntemi

Mesajı terket, reddet veya süresi dolsun

Yoklama döngüsü

Mesaj tekrar deneme politikasını alma

SDK ileti alma örneği

Arka uç uygulaması oluşturma

Hizmeti NuGet Paketi olarak ekle

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

Zaman uyumsuz bir buluttan cihaza ileti gönderme

Teslimat geri bildirimi alma

feedbackReceiver nesnesini oluşturma

Ack parametresini kullanarak ileti gönderme

Geri bildirim almayı bekleyin

Hizmet istemcisi yeniden bağlantısı

İleti yeniden deneme politikası

SDK ileti gönderme örneği

Cihaz uygulaması oluşturma

Azure IoT Java SDK kitaplıklarını içeri aktarma

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

İleti geri çağırma yöntemini ayarlama

İleti geri çağırma işleyicisi oluşturma

İleti bırakma ve reddetme seçenekleri

İleti durumu geri çağırma yöntemini oluşturma

Cihaz ile IoT Hub arasındaki bağlantıyı açma

SDK ileti alma örneği

Arka uç uygulaması oluşturma

Bağımlılık ifadesini ekle

"Import ifadeleri ekle"

IoT Hub'a bağlanma

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

Bağlantı protokollerini tanımlama

ServiceClient nesnesini oluşturma

Uygulama ile IoT Hub arasındaki bağlantıyı açma

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

İleti teslim geri bildirimi için bir geri bildirim alıcısı açma

İleti özellikleri ekleme

Zaman uyumsuz ileti oluşturma ve gönderme

İleti teslimi geri bildirimi alma

SDK ileti gönderme örnekleri

Cihaz uygulaması oluşturma

Cihaz içe aktarma bildirimi

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

Yeniden bağlanmayı yönetme

İleti işleyicisi oluşturma

İleti işleyicisini atama

SDK ileti alma örneği

Arka uç uygulaması oluşturma

IoTHubRegistryManager nesnesini içeri aktarma

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