Buluttan cihaza ileti gönderme ve alma

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:

• Geri çağırma: Cihaz uygulaması, bir ileti geldiğinde hemen çağrılan zaman uyumsuz bir ileti 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 denetler. Döngü sürekli olarak yürütülür ve iletiler denetleniyor.

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

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- ve ModuleClientiçin çeşitli aktarıma özgü ayarları tanımlamak için DeviceClient kullanılan arabirim. Daha fazla bilgi için bkz . ITransportSettings Arabirimi.
• 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:

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

Geri Arama

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

SDK yöntemlerinin Http1 alınan iletileri yine de yoklaması gerekeceğinden, geri çağırma ilkesini yenen protokol seçeneği geri çağırmaları desteklemez.

Bu örnekte, SetReceiveMessageHandlerAsync her ileti alındığında çağrılan adlı OnC2dMessageReceivedAsyncbir 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.");

Yoklamanın Karşılaştırması

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

çağrısı ReceiveAsync şu formları alabilir:

• ReceiveAsync() - Devam etmeden önce ileti için varsayılan zaman aşımı süresini bekleyin.
• ReceiveAsync (Timespan) - Belirli bir zaman aşımını kullanarak cihaz kuyruğundan bir ileti alın.
• ReceiveAsync (CancellationToken) - İptal belirteci 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, sık sık (en az 25 dakikada bir) iletileri denetleyan aralıklı olarak bağlı cihazlardır. Daha fazla HTTP 1 verilmesi, IoT Hub'ın istekleri azaltmasını sağlar. 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.

İletiyi bırakma, reddetme veya zaman aşımı

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 tutulmasına neden olur.
• 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 bir kez etkili 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ü

Yoklama kullanarak, uygulama durdurulana kadar yeni iletileri denetlemek için yöntemini tekrar tekrar çağıran ReceiveAsync 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. Zaman aşımına uğradıysa ReceiveAsync bir null değer döndürülür ve döngü devam eder.

bir ileti alındığında, tarafından CompleteAsync'e geçirilmesi gereken bir Görev nesnesi döndürülürReceiveAsync. IoT Hub'a CompleteAsync belirtilen iletiyi parametresine göre ileti kuyruğundan silmesini 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 ();
}

İleti yeniden deneme ilkesini 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.

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. 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 Amqp aktarım kullanarak nesnesini oluştururServiceClient.

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

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

Teslim 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 Negative hem de Positive sonuçlar için geri bildirim.

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

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 çağrısı ReceiveAsync nesne için ServiceClient tanımlanan zaman aşımı süresini bekler.

• ReceiveAsync İleti alınmadan zaman aşımı süresi dolarsa, ReceiveAsync döndürür null ve döngü devam eder.
• Geri bildirim iletisi alınırsa, iptal belirteci ile birlikte CompleteAsync'e geçirilmesi gereken tarafından bir Görev nesnesi döndürülürReceiveAsync. Belirtilen gönderilen iletiyi parametresine göre Task ileti kuyruğundan silme çağrısıCompleteAsync.
• 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 ve/veya değiştirin ya da hub örneği ölçek biriminizi güncelleştirin. Ayrıntılar için bkz . IoT Hub kotaları ve azaltma .

İleti yeniden deneme ilkesi gönder

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

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ğerler '=' ile ayrılmış olarak ';' ile ayrılmış 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:

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

İ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- türünde objectisteğe bağlı bir bağlam. Belirtilmemişse kullanın null .

Bu örnekte, bağlam parametresi olmayan adlı MessageCallback bir callback 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 iletinin başarıyla alınması ve ile sonuçlanması gerekse de IotHubMessageResult.COMPLETE, iletiyi bırakmak veya reddetmek gerekebilir.

• AMQP ve HTTPS ile ancak MQTT ile bir uygulama şunları yapabilir:
  • IotHubMessageResult.ABANDON iletisini seçin. IoT hub'ı yeniden sorgular ve daha sonra yeniden gönderir.
  • IotHubMessageResult.REJECT iletisini seçin. IoT hub'ı iletiyi yeniden sorgulamaz ve iletiyi ileti kuyruğundan kalıcı olarak kaldırır.
• İstemciler veya iletileri kullanıyor MQTT veya MQTT_WS kullanamıyorABANDON.REJECT

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 bir kez etkili 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.

İ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 bir 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 yoksa geri dönebilir null .

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.

Dependency deyimini ekleme

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>

İçeri aktarma deyimleri ekleme

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

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.

IotHubServiceClientProtocolyalnızca veya AMQPS_WS numaralandırmasını AMQPS kabul eder.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

ServiceClient nesnesini oluşturma

Iot Hub bağlantı dizesi ve protokol sağlayarak 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 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.

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

IoT Hub geri bildirimine ileti teslimi göndermek için FeedbackReceiver kullanabilirsiniz. AFeedbackReceiver, yöntemi yerine bir FeedbackBatch döndüren Receive özel bir Messagealıcıdır.

Bu örnekte nesnesi FeedbackReceiver oluşturulur ve open() geri bildirim beklemek için deyimi ç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 bir "Buluttan cihaza ileti" teslim edilir.

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 alma ç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, alıcıyı FeedbackBatch oluşturur ve getEnqueuedTimeUtc çağrılarını çağırarak iletinin sıralandığı zamanı yazdırmaktadı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ç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.

Yeniden bağlantıyı işleme

IoTHubDeviceClient varsayılan olarak bırakılan bir bağlantıyı yeniden kurmaya çalışır. Yeniden bağlanma davranışı, connection_retry ve connection_retry_interval parametreler tarafından IoTHubDeviceClientyö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

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

İ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 - türündeki dictisteğe bağlı bir özellik 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 bkz . buluttan cihaza ileti göndermeyi gösteren send_message.py .

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ı

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

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

• Tamamlandı - bir iletiyi tamamlamak için, buluttan cihaza iletisini gönderen hizmete iletinin alındığı bildirilir. IoT Hub iletiyi ileti kuyruğundan kaldırır. yöntemi biçimindedir client.complete(message, callback function).
• 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. yöntemi biçimindedir client.reject(message, callback function).
• 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. yöntemi biçimindedir client.abandon(message, callback function).

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 bir kez etkili 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 çağrısı complete gerekli değildir ve atlanabilir. AMQP veya HTTPS aktarımı için çağrısıcomplete 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, konsolun bağlantısını kesme hata iletisini yakalar ve görüntüler.

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

Olay dinleyicileri ekleme

.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

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

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

'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

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 yöntemi isteğe open bağlı err bir açık bağlantı 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 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.

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

• sent: İleti tamamlandıysa bir geri bildirim iletisi alın.

• : 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 gönderilen hem de gönderilmeyen sonuçlar için geri bildirim.

Bu örnekte özelliği olarak ack ayarlanmıştır fullve bir ileti için hem gönderilmiş hem de gönderilmemiş ileti teslim geri bildirimi istemektedir.

message.ack = 'full';

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

İleti geri bildirim alıcı geri çağırma işlevi getFeedbackReceiver kullanılarak öğesine bağlanırClient.

İleti geri bildirimi alıcısı iki bağımsız değişken alır:

• Hata nesnesi (null olabilir)
• AmqpReceiver nesnesi - İstemci tarafından yeni geri bildirim iletileri alındığında olayları yayar.

Bu örnek işlev konsola bir teslim geri bildirim iletisi alır ve 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 işlevini kullanarak getFeedbackReceiverhizmet Client nesnesine bağlarreceiveFeedback.

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 işlev, printResultFor sonraki bölümde açıklanan işleve send bir parametre olarak 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. Bitti, iki bağımsız değişkenle çağrılır:
  • Hata nesnesi (null olabilir).
  • aktarıma özgü yanıt nesnesi günlüğe kaydetme 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.