Azure IoT Hub ile bir cihazdan buluta dosya yükleme

Bu makalede şunların nasıl yapılacağını gösterilmektedir:

• Azure IoT cihazı ve hizmet SDK'ları kullanarak Azure Blob Depolama'ya dosya yüklemek için IoT Hub'ın dosya yükleme özelliklerini kullanın.
• IoT Hub'a dosyanın başarıyla karşıya yüklendiğini bildirin ve Azure IoT hizmeti SDK'larını kullanarak IoT Hub'dan dosya yükleme bildirimlerini almak için bir arka uç hizmeti oluşturun.

Bazı senaryolarda, cihazlarınızın gönderdiği verileri IoT Hub'ın kabul ettiği nispeten küçük cihazdan buluta mesajlara kolayca eşleyemezsiniz. IoT Hub'daki dosya yükleme yetenekleri, büyük veya karmaşık verileri buluta taşımanıza olanak tanır. Örneğin:

• Videolar
• Resimleri içeren büyük dosyalar
• Yüksek frekansta örneklenen titreşim verileri
• Bazı biçimde önceden işlenmiş veri

Bu dosyalar genellikle bulutta, Azure Data Factory veya Hadoop yığını gibi araçlar kullanılarak toplu işleme tabi tutulur. Dosyaları bir cihazdan yüklemeniz gerektiğinde, IoT Hub'ın güvenlik ve güvenilirliğinden yine de faydalanabilirsiniz. Bu makale size nasıl olduğunu gösteriyor.

Bu makale, bu makale içerisinde atıfta bulunulan çalıştırılabilir SDK örneklerini tamamlamak amacıyla hazırlanmıştır.

Detaylı bilgi için, bakınız:

• IoT Hub ile dosya yüklemelerine genel bakış
• Azure Blob Depolama’ya giriş
• Azure IoT SDK’ları

Önkoşullar

• Bir IoT hub'ı. Bazı SDK çağrıları, IoT Hub birincil bağlantı dizesini gerektirir, bu yüzden bağlantı dizgesini not edin.

• Kayıtlı bir cihaz. Bazı SDK çağrıları cihazın birincil bağlantı dizisini gerektirir, bu yüzden bağlantı dizisini not almayı unutmayın.

• IoT Hub Servis Bağlantısı izni - Dosya yükleme bildirim mesajlarını almak için arka uç hizmetinizin Servis Bağlantısı iznine ihtiyacı var. Varsayılan olarak, her IoT Hub bu izni veren hizmet adlı bir paylaşılan erişim ilkesiyle oluşturulur. Daha fazla bilgi için Connect to an IoT hub bölümüne bakın.

• IoT hub'ınızdaki dosya yüklemeyi yapılandırmak için bir Azure Storage hesabı ve Azure Blob Storage konteyneri bağlayın. Bunları Azure portal, Azure CLI veya Azure PowerShell kullanarak yapılandırabilirsiniz.

Genel Bakış

Bu kılavuz iki bölümden oluşur:

• Bir cihaz uygulamasından dosya yükleyin
• Arka uç uygulamasında dosya yükleme bildirimi alma

Bir cihaz uygulamasından dosya yükleyin

Bu bölüm, bir cihazdan Azure IoT SDK for .NET'te yer alan DeviceClient sınıfını kullanarak bir dosyanın bir IoT hub'a nasıl yükleneceğini açıklar.

Bu cihazdan IoT hub'a dosya yüklemek için şu prosedürü izleyin:

1. IoT merkezi ile bağlantı kur
2. IoT hub'dan bir SAS URI alın
3. Dosyayı Azure depolamaya yükleme
4. Dosya yükleme durumu hakkında IoT hub'ı bilgilendir

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması, IoT Hub ile aşağıdaki yöntemlerle kimlik doğrulayabilir:

• X.509 sertifika
• Paylaşılan erişim anahtarı

X.509 sertifikası kullanarak kimlik doğrula

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

1. DeviceAuthenticationWithX509Certificate'i kullanarak cihaz ve sertifika bilgilerini içeren bir nesne oluşturun. DeviceAuthenticationWithX509Certificate ikinci parametre olarak DeviceClient.Create'ye aktarılır (adım 2).

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

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

Bu örnek, açıklık için sertifika giriş parametresi değerlerini yerel değişkenler olarak gösterir. Üretim sisteminde, hassas giriş parametrelerini ortam değişkenlerinde veya daha güvenli bir depolama yerinde saklayın. Örneğin, ana bilgisayar adı ortam değişkenini okumak için Environment.GetEnvironmentVariable("HOSTNAME") kullanın.

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 bakınız:

• X.509 sertifikalarıyla kimlik doğrulaması
• Eğitim: Test için sertifikaları oluşturun ve yükleyin

Kod örnekleri

Cihaz X.509 sertifika kimlik doğrulama örneklerini çalıştırmak için bkz:

• X.509 sertifikası ile bağlan
• DeviceClientX509AuthenticationE2ETests (X509 Kimlik Doğrulama E2E Testleri)
• Yönlendirmeli proje - IoT Hub Cihaz Sağlama Servisi ile IoT cihazlarını güvenli ve geniş ölçekte sağlama

Paylaşılan erişim anahtarı kullanarak kimlik doğrula

CreateFromConnectionString işlevini çağırarak cihaza bağlanın. Cihazın birincil bağlantı dizesini iletin.

AMQP varsayılan taşıma protokolüdür.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

IoT hub'dan bir SAS URI alın

Dosya yükleme ayrıntılarını almak için GetFileUploadSasUriAsync işlevini çağırın. Sonraki adımda, bir cihazdan Blob Depolama alanına dosya yüklemek için SAS URI kullanılır.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Azure depolamaya bir dosya yükleyin

Azure depolamaya dosya yüklemek için:

1. Bir dosya yükleme URI'sını geçirerek bir blockBlobClient nesnesi oluşturun.

2. Dosyayı Blob Depolama'ya yüklemek için UploadAsync yöntemini kullanarak SAS URI'sini iletin. İsteğe bağlı olarak Blob karşıya yükleme seçenekleri ve iptal belirteci parametreleri ekleyebilirsiniz.

Azure Blob istemcisi, dosyayı Azure Depolama alanına yüklemek için her zaman protokol olarak HTTPS kullanır.

Bu örnekte, BlockBlobClient bir Azure Depolama blok Blob istemcisi oluşturmak ve dosyayı yüklemek için SAS URI'si alır.

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

Dosya yükleme durumu hakkında IoT hub'ı bilgilendir

IoT hub'ına cihaz istemcisinin karşıya yüklemeyi tamamladığını ve bir FileUploadCompletionNotification nesnesi geçirdiğini bildirmek için CompleteFileUploadAsync kullanın. Bayrak IsSuccess , karşıya yüklemenin başarılı olup olmadığını gösterir. Bildirim alındıktan sonra, IoT hub'ı karşıya yüklemeyle ilişkili kaynakları (SAS URI'si) serbest bırakır.

Dosya yükleme bildirimleri etkinleştirildiğinde, IoT hub dosya yükleme bildirimi için yapılandırılmış arka plan servislerine dosya yükleme bildirimi mesajı gönderir.

var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

SDK dosya yükleme örneği

SDK, bu dosya karşıya yükleme örneğini içerir.

Bir arka uç uygulamasında bir dosya yükleme bildirimi alın

IoT hub'ından dosya karşıya yükleme bildirim iletileri almak için bir arka uç hizmeti oluşturabilirsiniz.

ServiceClient sınıfı, hizmetlerin dosya yükleme bildirimleri almasını sağlamak için kullanılabilecek yöntemler içerir.

Hizmet NuGet Paketini ekle

Backend hizmet uygulamaları Microsoft.Azure.Devices NuGet paketine ihtiyaç duyar.

IoT merkezi ile bağlantı kur

Bir back-end hizmeti, aşağıdaki yöntemlerle IoT Hub'a bağlayabilirsiniz:

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

Önemli

Bu makale, paylaşılan bir erişim imzası kullanarak bir hizmete bağlanmanın adımlarını içerir. Bu kimlik doğrulama yöntemi, test ve değerlendirme için uygundur, ancak bir hizmete Microsoft Entra Kimliği veya yönetilen kimliklerle 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 politikası kullanarak bağlanın

Bir arka uç uygulamayı bir cihaza CreateFromConnectionString kullanarak bağlayın. Uygulamanızın servis bağlantısı iznine ihtiyacı var. Bu paylaşılan erişim politikası bağlantı dizesini fromConnectionString parametresi olarak sağlayın. Daha fazla bilgi için IoT Hub'a paylaşılan erişim imzalarıyla erişimi kontrol etme başlıklı belgede paylaşılan erişim politikalarına göz atın.

Örneğin:

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

Microsoft Entra kullanarak bağlanın

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve bir güvenlik belirteci kimlik bilgisi alması gerekir. Bu belirteç, bir IoT Hub bağlanma yöntemine iletilir. IoT Hub için Microsoft Entra'yı kurmak ve kullanmak hakkında genel bilgi için, Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme bölümüne bakın.

Microsoft Entra uygulamasını yapılandırma

Bir Microsoft Entra uygulaması kurmanız gerekmektedir ve bu uygulama tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış olmalıdır. Uygulama, istemci sırrı (client secret) gibi, arka uç uygulama tarafından kimlik doğrulama amacıyla kullanılan parametreler içerir. Mevcut uygulama kimlik doğrulama yapılandırmaları şunlardır:

• İstemci sırrı
• Sertifika
• Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub Twin Contributor, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için gereklidir. Daha fazla bilgi için, Manage access to IoT Hub by using Azure RBAC role assignment bölümüne bakın.

Daha fazla bilgi için Microsoft Entra uygulaması kurulumu hakkında Hızlı Başlangıç: Microsoft kimlik platformuyla bir uygulama kaydedin bölümüne bakın.

VarsayılanAzureKimliği kullanarak kimlik doğrulaması yap

tr-TR: Bir arka uç uygulamasını kimlik doğrulamak için Microsoft Entra'yı kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya indirgenmiş bir ChainedTokenCredential dahil olmak üzere farklı bir yöntemin 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 artıları ve eksileri hakkında VarsayılanAzureKimlik Bilgileri Kullanım Kılavuzu bölümünü inceleyin.

DefaultAzureCredential farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortamı temel alarak uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi bulana kadar, birden fazla kimlik bilgisi türünü sırayla kullanmaya çalışır.

Microsoft Entra, bu NuGet paketlerini ve karşılık gelen using ifadelerini gerektirir.

• Azure.Core
• Azure.Identity (Azure Kimlik)

using Azure.Core;
using Azure.Identity;

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

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

Ortaya çıkan TokenCredential, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK client için IoT Hub'a bağlanma metoduna geçirilebilir.

• İş İstemcisi
• Kayıt Defteri Yöneticisi
• DigitalTwinClient (Dijitalİkiz İstemci)
• Hizmet İstemcisi

Bu örnekte TokenCredential, ServiceClient.Create bağlantı nesnesi oluşturulmak üzere 'ye iletilir.

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

Bu örnekte, TokenCredentialRegistryManager.Create'e RegistryManager nesnesi oluşturmak için aktarılır.

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

Kod örneği

Microsoft Entra hizmeti doğrulaması için çalışan bir örnek görmek için Rol tabanlı kimlik doğrulama örneği kısmına bakın.

Dosya yükleme bildirimi al

Dosya yükleme bildirimi almak için:

1. Bir CancellationToken oluşturun.
2. Bir bildirim alıcısı oluşturmak için GetFileNotificationReceiver'ı çağırın.
3. ReceiveAsync ile bir döngü kullanarak dosya yükleme bildirimini bekleyin.

Örneğin:

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    if (fileUploadNotification == null) continue;
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine("Received file upload notification: {0}", 
        string.Join(", ", fileUploadNotification.BlobName));
    Console.ResetColor();
    await notificationReceiver.CompleteAsync(fileUploadNotification);
}

SDK dosyası yükleme alıcısı örneği

SDK, bu dosya yükleme alıcısı örneğini içerir.

Genel Bakış

Bu kılavuz iki bölümden oluşur:

• Bir cihaz uygulamasından dosya yükleyin
• Arka uç uygulamasında dosya yükleme bildirimi alma

Bir cihaz uygulamasından dosya yükleyin

Bu bölüm, Java için Azure IoT SDK'sından DeviceClient sınıfını kullanarak bir cihazdan bir IoT hub'a nasıl dosya yükleneceğini açıklar.

Bu cihazdan IoT hub'a dosya yüklemek için şu prosedürü izleyin:

1. Cihazı IoT Hub'a bağlayın
2. IoT hub'dan bir SAS URI alın
3. Dosyayı Azure Depolama'ya yükle
4. Dosya yükleme durumu bildirimini IoT merkezine gönder

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması, IoT Hub ile aşağıdaki yöntemlerle kimlik doğrulayabilir:

• X.509 sertifika
• Paylaşılan erişim anahtarı

X.509 sertifikası kullanarak kimlik doğrula

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

1. buildSSLContext kullanarak SSLContext nesnesini derleyin.
2. SSLContext bilgisini bir ClientOptions nesnesine ekleyin.
3. Cihazdan-IoT Hub'a bağlantı oluşturmak için bilgilerini kullanarak ClientOptions'i çağırın.

Bu örnek, açıklık için sertifika giriş parametresi değerlerini yerel değişkenler olarak gösterir. Üretim sisteminde, hassas giriş parametrelerini ortam değişkenlerinde veya daha güvenli bir depolama yerinde saklayın. Örneğin, bir ortak anahtar sertifikası dizesi ortam değişkenini okumak için Environment.GetEnvironmentVariable("PUBLICKEY") kullanın.

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 bakınız:

• X.509 sertifikalarıyla kimlik doğrulaması
• Eğitim: Test için sertifikaları oluşturun ve yükleyin

Kod örnekleri

Cihaz X.509 sertifika kimlik doğrulama örneklerini çalıştırmak için bkz:

• Gönder-al x509 örneği
• x509 olayını gönder

Paylaşılan erişim anahtarı kullanarak kimlik doğrula

Dosya yükleme işlemleri her zaman HTTPS kullanır, ancak DeviceClient telemetri, cihaz yöntemi ve cihaz ikilisi gibi diğer hizmetler için IotHubClientProtocol'u tanımlayabilir.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Cihaz birincil bağlantı dizesini kullanarak cihaza bağlanmak için DeviceClient öğesini oluşturun.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

IoT hub'dan bir SAS URI alın

getFileUploadSasUri çağrısını yaparak bir FileUploadSasUriResponse nesnesi edinin.

FileUploadSasUriResponse, bu yöntemleri ve dönüş değerlerini içerir. Döndürülen değerler dosya yükleme yöntemlerine geçirilebilir.

Yöntem	dönüş değeri
getCorrelationId()	Korelasyon Kimliği
getContainerName()	Konteyner adı
getBlobName()	Blob adı
getBlobUri()	Blob URI'si

Örneğin:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Dosyayı Azure Depolama'ya yükle

Blob URI uç noktasını BlobClientBuilder.buildclient'e geçirin ve BlobClient nesnesini oluşturun.

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Dosyayı Blob Depolama alanına yüklemek için uploadFromFile öğesini çağırın.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Dosya yükleme durumu bildirimini IoT merkezine gönder

Dosya karşıya yükleme girişiminden sonra IoT hub'ına bir karşıya yükleme durumu bildirimi gönderin.

Bir FileUploadCompletionNotification nesnesi oluşturun. correlationId ve isSuccess dosya yükleme başarı durumunu iletin. Dosya yükleme başarılı olduğunda bir isSuccesstrue değeri, olmadığında ise bir false değeri geçirin.

FileUploadCompletionNotification dosya yükleme başarısız olsa bile çağrılmalıdır. IoT hub, herhangi bir anda etkin olmasına izin verilen sabit bir SAS URI sayısına sahiptir. Dosya yüklemesini tamamladığınızda, başka SAS URI'leri oluşturulabilmesi için SAS URI'nizi serbest bırakmalısınız. Eğer bir SAS URI'si bu API aracılığıyla serbest bırakılmazsa, bir IoT hub üzerinde SAS URI'lerinin ne kadar süreyle yaşamaları gerektiğine göre, sonunda kendiliğinden serbest bırakılır.

Bu örnek başarılı bir durumu geçer.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

İstemciyi kapat

client kaynaklarını serbest bırak.

client.closeNow();

Bir backend uygulaması oluştur.

Bu bölüm, arka uç uygulamasında dosya yükleme bildirimini nasıl alacağınızı açıklamaktadır.

ServiceClient sınıfı, hizmetlerin dosya yükleme bildirimleri almasını sağlamak için kullanılabilecek yöntemler içerir.

Import ifadeleri ekle

Bu import ifadelerini, Azure IoT Java SDK'sını ve istisna yöneticisini kullanmak için ekleyin.

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

IoT Hub'a bağlanma

Bir back-end hizmeti, aşağıdaki yöntemlerle IoT Hub'a bağlayabilirsiniz:

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

Önemli

Bu makale, paylaşılan bir erişim imzası kullanarak bir hizmete bağlanmanın adımlarını içerir. Bu kimlik doğrulama yöntemi, test ve değerlendirme için uygundur, ancak bir hizmete Microsoft Entra Kimliği veya yönetilen kimliklerle 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 politikası kullanarak bağlanın

Bağlantı protokolünü tanımla

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.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

ServiceClient nesnesini oluşturun

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

Bir cihazdaki dosyayı IoT Hub'a yüklemek için, hizmetinizin hizmet bağlantısı izni olması gerekir. Varsayılan olarak, her IoT Hub bu izni veren hizmet adlı bir paylaşılan erişim ilkesiyle oluşturulur.

ServiceClient oluşturucusuna parametre olarak paylaşılan erişim ilkesini sağlayın. Daha fazla bilgi için IoT Hub'a paylaşılan erişim imzalarıyla erişimi kontrol etme başlıklı belgede paylaşılan erişim politikalarına göz atın.

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

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

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

serviceClient.open();

Microsoft Entra kullanarak bağlanın

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve bir güvenlik belirteci kimlik bilgisi alması gerekir. Bu belirteç, bir IoT Hub bağlanma yöntemine iletilir. IoT Hub için Microsoft Entra'yı kurmak ve kullanmak hakkında genel bilgi için, Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme bölümüne bakın.

Java SDK kimlik doğrulaması hakkında genel bir bakış için Java ile Azure kimlik doğrulaması ve Azure Kimlik konusuna bakın.

Basitlik için bu bölüm, istemci gizliliği kullanarak kimlik doğrulamayı tanımlamaya odaklanıyor.

Microsoft Entra uygulamasını yapılandırma

Bir Microsoft Entra uygulaması kurmanız gerekmektedir ve bu uygulama tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış olmalıdır. Uygulama, istemci sırrı (client secret) gibi, arka uç uygulama tarafından kimlik doğrulama amacıyla kullanılan parametreler içerir. Mevcut uygulama kimlik doğrulama yapılandırmaları şunlardır:

• İstemci sırrı
• Sertifika
• Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub Twin Contributor, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için gereklidir. Daha fazla bilgi için, Manage access to IoT Hub by using Azure RBAC role assignment bölümüne bakın.

Daha fazla bilgi için Microsoft Entra uygulaması kurulumu hakkında Hızlı Başlangıç: Microsoft kimlik platformuyla bir uygulama kaydedin bölümüne bakın.

VarsayılanAzureKimliği kullanarak kimlik doğrulaması yap

tr-TR: Bir arka uç uygulamasını kimlik doğrulamak için Microsoft Entra'yı kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya indirgenmiş bir ChainedTokenCredential dahil olmak üzere farklı bir yöntemin kullanılması önerilir. Daha fazla bilgi için DefaultAzureCredential kullanımının avantajları ve dezavantajları hakkında, Azure Identity istemci kitaplığındaki kimlik bilgisi zincirlerine ilişkin belgeler bölümüne bakın.

DefaultAzureCredential, farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortama bağlı olarak uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi bulana kadar, birden fazla kimlik bilgisi türünü sırayla kullanmaya çalışır.

Microsoft Entra uygulama kimlik bilgilerini DefaultAzureCredentialBuilder kullanarak doğrulayabilirsiniz. Bağlantı parametrelerini, örneğin istemci gizli anahtarı, kiracı kimlik numarası (tenantID), istemci kimliği (clientID) ve istemci gizli değerlerini çevresel değişkenler olarak kaydedin. TokenCredential oluşturulduktan sonra, 'credentials' parametresi olarak ServiceClient veya başka bir oluşturucuya iletin.

Bu örnekte, DefaultAzureCredentialBuilderDefaultAzureCredential'de açıklanan listeden bir bağlantıyı kimlik doğrulamaya çalışır. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, ServiceClient gibi bir yapıcıya iletilen bir güvenlik belirteci kimliğidir.

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

ClientSecretCredentialBuilder kullanarak kimlik doğrulaması yap

İstemci gizli bilgilerini kullanarak bir kimlik bilgisi oluşturmak için ClientSecretCredentialBuilder kullanabilirsiniz. Başarılı olursa, bu yöntem 'kimlik bilgisi' parametresi olarak ServiceClient veya başka bir yapıcıya aktarılabilen bir TokenCredential döndürür.

Bu örnekte, Microsoft Entra uygulama kaydı istemci sırrı, istemci kimliği ve kiracı kimliği değerleri, ortam değişkenlerine eklendi. 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:

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

Kod örnekleri

Microsoft Entra hizmeti kimlik doğrulaması için çalışan örnekler için, Rol tabanlı kimlik doğrulama örneği'ne bakın.

Dosya yükleme durumunu kontrol et

Dosya yükleme durumunu kontrol etmek için:

1. Bir getFileUploadNotificationReceiver nesnesi oluşturun.
2. Bağlanmak için aç kullanın IoT hub'a.
3. Dosya yükleme durumunu kontrol etmek için receive çağrısını yapın. Bu yöntem bir fileUploadNotification nesnesi döndürür. Yükleme bildirimi alındığında, fileUploadNotification yöntemlerini kullanarak yükleme durumu alanlarını görüntüleyebilirsiniz.

Örneğin:

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

SDK dosya yükleme örnekleri

İki Java dosyası yükleme örneği vardır.

Paketleri yükleme

Azure-iot-device kütüphanesi, ilgili herhangi bir kod çağrılmadan önce yüklenmelidir.

pip install azure-iot-device

Dosya yüklemesini gerçekleştirmek için azure.storage.blob paketi kullanılır.

pip install azure.storage.blob

Cihaz uygulamasından dosya yükle

Bu bölüm, bir cihazdan bir IoT hub'ına dosya yüklemeyi, Python için Azure IoT SDK'sındaki IoTHubDeviceClient sınıfını kullanarak nasıl yapacağınızı açıklar.

Kütüphaneleri içe aktar

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması, IoT Hub ile aşağıdaki yöntemlerle kimlik doğrulayabilir:

• X.509 sertifika
• Paylaşılan erişim anahtarı

X.509 sertifikası kullanarak kimlik doğrula

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

1. create_from_x509_certificate kullanarak X.509 sertifika parametrelerini ekleyin.
2. Cihaz istemcisini bağlamak için connect çağrısında bulunun.

Bu örnek, açıklık için sertifika giriş parametresi değerlerini yerel değişkenler olarak gösterir. Üretim sisteminde, hassas giriş parametrelerini ortam değişkenlerinde veya daha güvenli bir depolama yerinde saklayın. Örneğin, ana bilgisayar adı ortam değişkenini okumak için os.getenv("HOSTNAME") kullanın.

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

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

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

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

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

# Connect to IoT Hub
await device_client.connect()

Sertifika kimlik doğrulaması hakkında daha fazla bilgi için bakınız:

• X.509 sertifikalarıyla kimlik doğrulaması
• Eğitim: Test için sertifikaları oluşturun ve yükleyin

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.

Paylaşılan erişim anahtarı kullanarak kimlik doğrula

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

1. Cihazın birincil bağlantı dizesini eklemek için create_from_connection_string fonksiyonunu çağırın.
2. Cihaz istemcisini bağlamak için connect çağrısını 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()

Blob Depolama bilgilerini alma

get_storage_info_for_blob işlevini çağırarak bir Azure Depolama hesabıyla bağlantılı IoT merkezinden bilgi alın. Bu bilgi, ana bilgisayar adı, konteyner adı, blob adı ve bir SAS belirteci içerir. get_storage_info_for_blob yöntemi ayrıca bir correlation_id döndürür, bu notify_blob_upload_status yönteminde kullanılır. correlation_id IoT Hub'un üzerinde çalıştığınız Blob'u işaretleme şeklidir.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Bir dosyayı Blob Depolama Alanına yükleyin

Blob Depolama'ya dosya yüklemek için:

1. Bir from_blob_url kullanarak, bir blob URL'sinden bir BlobClient nesnesi oluşturun.
2. Dosyayı Blob Depolama Alanına yüklemek için upload_blob çağırın.

Bu örnek, bir blob_info'i başlatmak için kullandığı bir URL oluşturmak amacıyla yapısını ayrıştırır. Ardından dosyayı Blob Depolama'ya yüklemek için çağırır upload_blob .

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

IoT merkezi'ne yükleme durumunu bildir

Kullanıcıları Blob Depolama operasyonunun durumu hakkında IoT merkezini bilgilendirmek için notify_blob_upload_status'u kullanın. Yöntemi ile elde edilen correlation_id'i geçir. IoT hub, dosya yükleme görevinin durumu hakkında bir bildirim bekleyen herhangi bir hizmeti bilgilendirmek için correlation_id kullanılır.

Bu örnek, IoT hub'a başarılı bir dosya yüklemesi bildiriminde bulunur:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Cihaz istemcisini kapatın

İstemciyi kapat. Bu yöntem çağrıldığında, daha fazla istemci çağrısı girişimi bir ClientError hatasının oluşmasıyla sonuçlanır.

device_client.shutdown()

SDK dosya yükleme örnekleri

SDK iki dosya yükleme örneği içerir:

• Blob'a yükleme
• X.509 sertifikası kullanarak blob'a yükleme

Genel Bakış

Bu makale, bir dosyayı yüklemek için cihaz uygulaması oluşturmak ve arka uç servis uygulamasının dosya yükleme bildirimini almasını sağlamak amacıyla Azure IoT SDK for Node.js nasıl kullanılacağını açıklar.

Bir cihaz uygulaması oluşturun

Bu bölümde, Node.jsiçin Azure IoT SDK'sındaki azure-iot-device paketini kullanarak bir cihazdan IoT hub'ına nasıl dosya yükleneceği açıklanmaktadır.

SDK paketlerini yükleme

Bu komutu çalıştırarak azure-iot-device cihaz SDK'sını, azure-iot-device-mqtt ve @azure/storage-blob paketlerini geliştirme makinenize kurabilirsiniz.

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

azure-iot-device paketi, IoT cihazlarıyla arabirim kurmak için nesneler içerir.

Bu cihazdan IoT hub'a dosya yüklemek için şu prosedürü izleyin:

1. Cihazı IoT Hub'a bağlayın
2. IoT Hub'dan bir Blob paylaşımlı erişim imza (SAS) belirteci alın.
3. Dosyayı Azure Depolama'ya yükle
4. Dosya yükleme durumu bildirimini IoT merkezine gönder

Modüller oluştur

Yüklü paketleri kullanarak, Client, Protocol, errors ve path üst başlıklarını oluşturun.

const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

IoT Hub’a cihaz bağlama

Bir cihaz uygulaması, IoT Hub ile aşağıdaki yöntemlerle kimlik doğrulayabilir:

• X.509 sertifika
• Paylaşılan erişim anahtarı

X.509 sertifikası kullanarak kimlik doğrula

X.509 sertifikası, cihazdan IoT Hub bağlantı taşımasına eklenmiştir.

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

1. Cihaz veya kimlik modülü bağlantı dizesi ve taşıma türünü nesnesine eklemek için Client çağırın. Bağlantı dizesine bir x509=true ekleyerek bir sertifikanın DeviceClientOptions eklendiğini belirtin. Örneğin:

   • Bir cihaz bağlantı dizesi:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • Bir 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ı ile bir JSON değişken yapılandırın ve bunu DeviceClientOptions'a iletin.

3. setOptions çağırarak istemci iletişimine bir X.509 sertifikası ve anahtar (ve isteğe bağlı olarak parola) ekleyin.

4. Cihazdan IoT Hub'a bağlantıyı açmak için open çağrısını yapın.

Bu örnek, bir JSON değişkeni içinde sertifika yapılandırma bilgilerini gösterir. Sertifika yapılandırması clientOptions, setOptions'e geçirilir 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 bakınız:

• X.509 sertifikalarıyla kimlik doğrulaması
• Test etmek için sertifikalar oluşturun ve yükleyin

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

Taşıma protokolü seçin

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 Amqp protokolünü yükler:

npm install azure-iot-device-amqp --save

MQTT, AMQP ve HTTPS desteği arasındaki farklar hakkında daha fazla bilgi için Cihaza bulut iletişim rehberi ve Bir iletişim protokolü seçin bölümlerine bakın.

Bir istemci nesnesi oluştur.

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

Örneğin:

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

Bir protokol nesnesi oluştur

Yüklü bir taşıma paketi kullanarak bir Protocol nesnesi oluşturun.

Bu örnekte AMQP protokolü atanır:

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

Cihaz bağlantı dizesini ve taşıma protokolünü ekleyin

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

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

Bu örnek Amqp taşıma protokolünü kullanır.

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

IoT Hub'a bağlantıyı aç

Bir IoT cihazı ile IoT Hub arasındaki bağlantıyı açmak için open yöntemini kullanın.

Örneğin:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

IoT hub'dan bir SAS belirteci al

IoT hub'ından bağlı depolama hesabı SAS belirtecini almak için getBlobSharedAccessSignature kullanın.

Örneğin:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Dosyayı IoT hub'a yükle

Bir cihazdan IoT hub'ına dosya yüklemek için:

1. Akış işlem hattı oluşturma
2. Blob URL'sini oluşturun
3. Blob Depolama'ya dosya yüklemek için bir BlockBlobClient oluşturma
4. Dosyayı Blob Depolama'ya yüklemek için uploadFile fonksiyonunu çağırın.
5. notifyBlobUploadStatus çağırarak IoT hub'a yüklemenin başarılı olup olmadığını bildirin.

Örneğin:

// Open the pipeline
const pipeline = newPipeline(new AnonymousCredential(), {
retryOptions: { maxTries: 4 },
telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
keepAliveOptions: { enable: false }
});

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

// Create the BlockBlobClient for file upload to Blob Storage
const blobClient = new BlockBlobClient(blobUrl, pipeline);

// Setup blank status notification arguments to be filled in on success/failure
let isSuccess;
let statusCode;
let statusDescription;

const uploadStatus = await blobClient.uploadFile(localFilePath);
console.log('uploadStreamToBlockBlob success');

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Yerel dosyayı blob deposuna yükle

Bir bilgisayardan blob depolamasına yerel bir dosya yükleyebilirsiniz.

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

SDK dosya yükleme örneği

SDK, gelişmiş blob'a yükleme örneği içerir.

Bir backend uygulaması oluştur.

Bu bölümde, bir arka uç uygulamasında dosya yükleme bildirimlerinin nasıl alınacağı açıklanmaktadır.

ServiceClient sınıfı, hizmetlerin dosya yükleme bildirimleri almasını sağlamak için kullanılabilecek yöntemler içerir.

Servis SDK paketini yükle

Bu komutu çalıştırarak azure-iothub'u geliştirme makinenize yükleyin.

npm install azure-iothub --save

IoT merkezi ile bağlantı kur

Bir back-end hizmeti, aşağıdaki yöntemlerle IoT Hub'a bağlayabilirsiniz:

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

Önemli

Bu makale, paylaşılan bir erişim imzası kullanarak bir hizmete bağlanmanın adımlarını içerir. Bu kimlik doğrulama yöntemi, test ve değerlendirme için uygundur, ancak bir hizmete Microsoft Entra Kimliği veya yönetilen kimliklerle 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 politikası kullanarak bağlanın

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

Cihazdan dosya yüklemek için, hizmetinizin service connect iznine ihtiyacı vardır. Varsayılan olarak, her IoT Hub bu izni veren hizmet adlı bir paylaşılan erişim ilkesiyle oluşturulur.

CreateFromConnectionString için bir parametre olarak, hizmet paylaşımlı erişim politikası bağlantı dizgesini sağlayın. Daha fazla bilgi için IoT Hub'a paylaşılan erişim imzalarıyla erişimi kontrol etme başlıklı belgede paylaşılan erişim politikalarına göz atın.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Microsoft Entra kullanarak bağlanın

Microsoft Entra kullanan bir arka uç uygulamasının IoT Hub'a bağlanmadan önce başarıyla kimlik doğrulaması yapması ve bir güvenlik belirteci kimlik bilgisi alması gerekir. Bu belirteç, bir IoT Hub bağlanma yöntemine iletilir. IoT Hub için Microsoft Entra'yı kurmak ve kullanmak hakkında genel bilgi için, Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme bölümüne bakın.

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

• Azure üzerinde kullanıcı kimlik doğrulama ile çalışmaya başlama
• JavaScript için Azure Identity istemci kitaplığı

Microsoft Entra uygulamasını yapılandırma

Bir Microsoft Entra uygulaması kurmanız gerekmektedir ve bu uygulama tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış olmalıdır. Uygulama, istemci sırrı (client secret) gibi, arka uç uygulama tarafından kimlik doğrulama amacıyla kullanılan parametreler içerir. Mevcut uygulama kimlik doğrulama yapılandırmaları şunlardır:

• İstemci sırrı
• Sertifika
• Birleşik kimlik belgesi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, IoT Hub Twin Contributor, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için gereklidir. Daha fazla bilgi için, Manage access to IoT Hub by using Azure RBAC role assignment bölümüne bakın.

Daha fazla bilgi için Microsoft Entra uygulaması kurulumu hakkında Hızlı Başlangıç: Microsoft kimlik platformuyla bir uygulama kaydedin bölümüne bakın.

VarsayılanAzureKimliği kullanarak kimlik doğrulaması yap

tr-TR: Bir arka uç uygulamasını kimlik doğrulamak için Microsoft Entra'yı kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya indirgenmiş bir ChainedTokenCredential dahil olmak üzere farklı bir yöntemin 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. DefaultAzureCredential kullanmanın avantajları ve dezavantajları hakkında daha fazla bilgi için JavaScript için Azure Identity istemci kitaplığı'ndaki Kimlik Bilgisi Zincirleri bölümüne bakın.

DefaultAzureCredential, farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortama bağlı olarak uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi bulana kadar, birden fazla kimlik bilgisi türünü sırayla kullanmaya çalışır.

Microsoft Entra bu paketi gerektirir:

npm install --save @azure/identity

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

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

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

Ortaya çıkan kimlik bilgisi jetonu, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanmak üzere fromTokenCredential'a iletilebilir.

• Kayıt Defteri
• Müşteri
• İş İstemcisi

fromTokenCredential iki parametre gerektirir:

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

Bu örnekte, Azure kimlik bilgisi DefaultAzureCredential kullanılarak alınır. Ardından, IoT Hub ile bağlantı oluşturmak için Azure etki alanı URL'si ve kimlik bilgisi Registry.fromTokenCredential'a 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ğrulama için çalışan örnekler görmek için, Azure identity examples bölümüne bakın.

Dosya yükleme bildirimi geriçağırım alıcısı oluştur.

Bir dosya yükleme bildirimi geri arama alıcısı oluşturmak için:

1. Çağır getFileNotificationReceiver. Bildirim mesajları alındığında çağrılan bir dosya yükleme geri çağırma yönteminin adını belirtin.
2. Geri çağrı yönteminde dosya yükleme bildirimlerini işleyin.

Bu örnek, bir bildirim geri çağırma alıcısını kurar. Alıcı, dosya yükleme durumu bilgilerini yorumlar ve konsola bir durum mesajı yazdırır.

//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
if (err) {
  console.error('error getting the file notification receiver: ' + err.toString());
} else {
  receiver.on('message', function (msg) {
    console.log('File upload from device:')
    console.log(msg.getData().toString('utf-8'));
    receiver.complete(msg, function (err) {
      if (err) {
        console.error('Could not finish the upload: ' + err.message);
      } else {
        console.log('Upload complete');
      }
    });
  });
}

SDK dosya yükleme bildirim örneği

SDK bir dosya yükleme örneği içerir.