IoT Hub ile dosyaları karşıya yükleme

Cihaz verilerinizi kabul eden görece küçük cihazdan buluta iletilerine kolayca IoT Hub vardır. Örneğin, büyük medya dosyaları göndermek veya aralıklı olarak bağlı cihazlar tarafından karşıya yüklenen ya da bant genişliğinden tasarruf etmek için toplanmış ve sıkıştırılmış büyük telemetri toplu işleri gönderme.

Bir cihazdan büyük dosyaları karşıya yüklemeniz gerektirse de bu dosyaların güvenliğini ve güvenilirliğini IoT Hub. Bununla birlikte, iletilere kendisi aracılığıyla aracılık IoT Hub, ilişkili bir Azure depolama hesabına dağıtıcı olarak davranır. IoT Hub, bir cihaz karşıya dosya yükleme işlemi tamamlandıktan sonra arka uç hizmetleri için bildirim de sağlanmıştır.

Bildirilen özellikleri, cihazdan buluta iletileri veya dosya yüklemelerini ne zaman kullanabileceğinizi karar verirken yardıma ihtiyacınız varsa bkz. Cihazdan buluta iletişim kılavuzu.

Önemli

X.509 sertifika yetkilisi (CA) kimlik doğrulaması kullanan cihazlarda dosya karşıya yükleme işlevi genel önizlemededir ve önizleme modu etkinleştirilmelidir. Genel olarak X.509 parmak izi kimlik doğrulaması kullanan cihazlarda kullanılabilir. IoT Hub ile X.509 kimlik doğrulaması hakkında daha fazla bilgi edinmek için bkz. Desteklenen X.509 sertifikaları.

Dosya karşıya yüklemeye genel bakış

IoT hub'ı, blob kapsayıcısı ve hub ile önceden yapılandırılmış Azure depolama hesabı için karşıya yükleme başına temelinde paylaşılan erişim imzası (SAS) URL'leri sağlayarak bağlı cihazlardan dosya yüklemelerini kolaylaştırır. IoT Hub ile dosya yüklemelerini kullanmanın üç parçası vardır: IoT hub' ınıza bir Azure depolama hesabını ve blob kapsayıcısı önceden yapılandırma, cihazlardan dosya yükleme ve isteğe bağlı olarak arka uç hizmetlerine tamamlanmış dosya yüklemelerini bildirme.

Dosya karşıya yükleme özelliğini kullanamadan önce bir Azure depolama hesabını ve blob kapsayıcıyı IoT hub'ı ile ilişkilendirmeniz gerekir. IoT Hub'nin Azure depolama ile kimlik doğrulamasını, IoT hub'ını cihazlara iletirken kullandığı SAS URL'lerinin yaşam süresi (TTL) ve arka uç hizmetlerinize dosya yükleme bildirimlerinin nasıl olduğunu kontrol etmek için de ayarları yapılandırabilirsiniz. Daha fazla bilgi edinmek için bkz. Azure depolama hesabını IoT Hub.

Cihazlar, ilişkili blob kapsayıcıya dosya yüklemek için üç adımlı bir işlemi takip eder:

  1. Cihaz, IoT hub'ı ile dosya yüklemeyi başlatıyor. İstekte blob adını geçer ve karşılığında SAS URI'si ile bağıntı kimliğini alır. SAS URI'si, Azure depolama için blob kapsayıcısı içinde istenen blobda cihaza okuma-yazma iznini olan bir SAS belirteci içerir. Ayrıntılar için bkz. Cihaz: Dosya yüklemesi başlatma.

  2. Cihaz, dosyayı blob kapsayıcıya yüklemek için Azure blob depolama API'lerini güvenli bir şekilde çağıracak SAS URI'sını kullanır. Ayrıntılar için bkz. Cihaz: Azure Upload API'lerini kullanan bir dosya.

  3. Dosya karşıya yükleme işlemi tamamlandığında cihaz, karşıya yükleme işlemini başlattığında IoT hub'larından aldığı bağıntı kimliğini IoT Hub durumunu IoT hub'larına iletir. Ayrıntılar için bkz. Cihaz: Tamamlanan IoT Hub için bildirim.

Arka uç hizmetleri, IoT hub'ın hizmete yönelik dosya karşıya yükleme bildirim uç noktası üzerinde dosya karşıya yükleme bildirimlerine abone olabilir. IoT hub' ınıza bu bildirimleri etkinleştirdiyseniz, bir cihaz hub'a dosya yüklemesi tamamlamış olduğunu her bildirildiğinde bu uç noktada bunları teslim alır. Hizmetler, blob verilerini daha fazla işlemeyi tetiklemek için bu bildirimleri kullanabilir. Ayrıntılar için bkz. Hizmet: Dosya karşıya yükleme bildirimleri.

Dosya karşıya yükleme, Azure IoT cihazı ve hizmet SDK'leri tarafından tam olarak de destekler. Ayrıntılar için bkz. SDK kullanarak dosya yükleme.

Dosya karşıya yükleme kotaları ve sınırları

IoT Hub bir süre içinde başlatıldığı dosya karşıya yükleme sayısına kısıtlama sınırları yükler. Eşik, SKU'ya ve IoT hub'ın birim sayısına göredir. Ayrıca, her cihaz aynı anda 10 eşzamanlı etkin dosya karşıya yükleme ile sınırlıdır. Daha fazla bilgi için bkz. Azaltma ve kotalar.

Azure depolama hesabını depolama hesabıyla IoT Hub

Dosya yükleme özelliklerini kullanmak için bir Azure depolama hesabı ve blob kapsayıcısı ile IoT hub'ını ilişkilendirmeniz gerekir. IoT hub'ınıza kayıtlı cihazlardan karşıya yüklenen tüm dosya yüklemeleri bu kapsayıcıya gider. IoT hub' ınıza bir depolama hesabı ve blob kapsayıcısı yapılandırmak için bkz. Azure portalile dosya yüklemelerini yapılandırma, Azure CLIile dosya yüklemelerini yapılandırma veya PowerShell ile dosya yüklemelerini yapılandırma. Dosya karşıya yüklemelerini program aracılığıyla IoT Hub yönetim API'lerini de kullanabilirsiniz.

Portalı kullanıyorsanız, yapılandırma sırasında bir depolama hesabı ve kapsayıcı oluşturabilirsiniz. Aksi takdirde, depolama hesabı oluşturmak için Azure depolama belgelerinde Depolama hesabı oluşturma'ya bakın. Depolama hesabınız olduktan sonra, Azure blob depolama hızlı başlangıçlarında blob kapsayıcısı oluşturma hakkında bilgi edinebilirsiniz.

Dosya karşıya yükleme ve dosya karşıya yükleme bildirimlerinin davranışını kontrol altına alan birkaç farklı ayar daha vardır. Aşağıdaki bölümlerde kullanılabilir tüm ayarlar listelanmıştır. Dosya karşıya yüklemelerini yapılandırmak için Azure portal, Azure CLI, PowerShell veya yönetim API'lerini mi kullandığınıza bağlı olarak, bu ayarlardan bazıları kullanılamıyor olabilir. Dosya karşıya yükleme tamamlandığında arka uç hizmetlerinize bildirim gönderilmek için enableFileUploadNotifications ayarını ayarlandıktan emin olun.

Iot Hub depolama ve kimlik doğrulama ayarları

Aşağıdaki ayarlar bir depolama hesabını ve kapsayıcıyı IoT hub'ınız ile ilişkilendirmek ve hub'ın Azure depolama ile kimlik doğrulamasını denetlemeyi sağlar. Bu ayarlar, cihazların Azure depolama ile kimlik doğrulamasını etkilemez. Cihazlar her zaman kimlik doğrulamasından alınan SAS URI'sinde sunulan SAS belirtec IoT Hub.

Özellik Açıklama Aralık ve varsayılan
storageEndpoints.$default.authenticationType Azure depolama ile IoT Hub doğrulamasını kontrol eder. Olası değerler keyBased ve identityBased değerleridir. Varsayılan: keyBased.
storageEndpoints.$default.connectionString Dosya karşıya yüklemeleri için kullanmak üzere Azure depolama hesabına bağlantı dizesi. Varsayılan: Boş dize.
storageEndpoints.$default.containerName Dosyaları karşıya yüklemek için kapsayıcının adı. Varsayılan: Boş dize.
storageEndpoints.$default.identity Kimlik tabanlı kimlik doğrulaması için kullanılan yönetilen kimlik. Olası [system] değerler, sistem tarafından atanan yönetilen kimliğe veya kullanıcı tarafından atanan yönetilen kimlik için kaynak kimliğine yöneliktir. Değer, anahtar tabanlı kimlik doğrulaması için kullanılmaz. Varsayılan: null.

Dosya karşıya yükleme ayarları

Aşağıdaki ayarlar, cihazdan karşıya dosya yüklemelerini kontrol edin.

Özellik Açıklama Aralık ve varsayılan
storageEndpoints.$default.ttlAsIso8601 Etki alanı tarafından oluşturulan SAS URL'leri için varsayılan TTL IoT Hub. ISO_8601 48 saate (en az 1 dakika) kadar zaman aralığı. Varsayılan: 1 saat.

Dosya karşıya yükleme bildirimi ayarları

Aşağıdaki ayarlar, arka uç hizmetleri için dosya yükleme bildirimlerini kontrol edin.

Özellik Açıklama Aralık ve varsayılan
enableFileUploadNotifications Dosya karşıya yükleme bildirimlerinin dosya bildirimleri uç noktasına yazılıp yazıl olmadığını kontrol eder. Bool. Varsayılan: False.
fileNotifications.ttlAsIso8601 Dosya karşıya yükleme bildirimleri için varsayılan TTL. ISO_8601 48 saate (en az 1 dakika) kadar zaman aralığı. Varsayılan: 1 saat.
fileNotifications.lockDuration Dosya karşıya yükleme bildirimleri kuyruğu için kilitleme süresi. 5 ile 300 saniye arasında. Varsayılan: 60 saniye.
fileNotifications.maxDeliveryCount Dosya karşıya yükleme bildirim kuyruğu için en fazla teslim sayısı. 1 ile 100 arasında. Varsayılan: 100.

SDK kullanarak karşıya dosya yükleme

Aşağıdaki nasıl yapılır kılavuzları, Azure IoT cihazı ve hizmet SDK'lerini kullanarak dosyaları karşıya yüklemek için eksiksiz, adım adım yönergeler sağlar. Depolama hesabını bir IoT hub'ı ile ilişkilendirmek için Azure portal'nin nasıl kullanılası ve kod parçacıkları içerdiği veya karşıya yüklemede size yol gösterecek örneklere başvurarak nasıl kullanabileceğinizi gösterir.

Nasıl yapılır kılavuzu Cihaz SDK'sı örneği Hizmet SDK'sı örneği
.NET Yes Yes
Java Yes Yes
Node.js Yes Yes
Python Yes Hayır (desteklenmiyor)

Not

C cihaz SDK'sı, dosya yüklemelerini gerçekleştirmek için cihaz istemcide tek bir çağrı kullanır. Daha fazla bilgi için bkz. IoTHubDeviceClient_UploadToBlobAsync() ve IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Bu işlevler, karşıya dosya yükleme işleminin tüm yönlerini tek bir çağrıda gerçekleştirir; karşıya yükleme işlemini başlatarak, dosyayı Azure depolamaya yükler ve tamamlandığında IoT Hub bildirim alır. Başka bir ifadeyle, cihazın IoT Hub iletişim kurmak için hangi protokolü kullanıyorsa, bu işlevler Azure depolama API'lerini çağırana kadar Azure depolama ile HTTPS üzerinden iletişim kurabilecek olması da gerekir.

Cihaz: Karşıya dosya yükleme başlatma

Cihaz, dosya yüklemesini başlatmak Upload SAS URI'si REST API veya cihaz SDK'lerinden birinin eşdeğer API'sini çağırır.

Desteklenen protokoller: AMQP, AMQP-WS, MQTT, MQTT-WS ve HTTPS
nokta: {iot hub}.azure-devices.net/devices/{deviceId}/files
Yöntem: POST

{
    "blobName":"myfile.txt"
}

Özellik Açıklama
blobName SAS URI'si oluşturmak için blob adı.

IoT Hub, cihazın Azure depolama ile kimlik doğrulaması yapmak için kullanabileceği bir SAS URI'sinde bağıntı kimliği ve öğeleriyle yanıt verir. Bu yanıt, hedef IoT hub'ını azaltma sınırlarına ve cihaz başına karşıya yükleme sınırlarına tabi olur.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}

Özellik Açıklama
correlationId Karşıya dosya yükleme tam bildirimini gönderirken cihazın IoT Hub.
Hostname IoT hub'da yapılandırılan depolama hesabının Azure depolama hesabı ana bilgisayar adı
containerName IoT hub'sinde yapılandırılan blob kapsayıcının adı.
blobName Blob'un kapsayıcıda depolandığı konum. Ad şu biçimdedir: {device ID of the device making the request}/{blobName in the request}
sasToken Azure depolama ile blob üzerinde okuma-yazma erişimi izni vermek için bir SAS belirteci. Belirteç, IoT Hub tarafından oluşturulur ve IoT Hub.

Yanıt aldığında cihaz:

  • Karşıya yükleme tamamlandığında IoT hub'a dosya yükleme tamamlama bildirimine dahil edilecek bağıntı kimliğini kaydeder.

  • Azure depolama ile kimlik doğrulaması yapmak için kullandığı blob için sas URI'sı oluşturmak için diğer özellikleri kullanır. SAS URI'si, istenen blob için kaynak URI'lerini ve SAS belirteci içerir. Şu formu alır: https://{hostName}/{containerName}/{blobName}{sasToken} sasToken (Yanıtta yer alan özelliği, baştaki '?' karakterini içerir.) Küme ayraçları dahil değildir.

    Örneğin, yukarıdaki örnekte döndürülen değerler için SAS URI'sı şu şekildedir: https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

    SAS URI'si ve SAS belirteci hakkında daha fazla bilgi için Azure depolama belgelerinde Hizmet SAS'ı oluşturma'ya bakın.

Cihaz: Upload Azure depolama API'lerini kullanan bir dosya

Cihaz, Azure Blob depolama REST API'lerini veya eşdeğer Azure depolama SDK API'lerini kullanarak dosyayı Azure depolamadaki bloba yükler.

Desteklenen protokoller: HTTPS

Aşağıdaki örnekte küçük bir blok blobu oluşturmak veya güncelleştirmek için Bir Blob Koy isteği yer amektedir. Bu istek için kullanılan URI'nin, önceki bölümde IoT Hub tarafından döndürülen SAS URI'si olduğunu fark edin. Üst x-ms-blob-type bilgi, bu isteğin blok blobu için olduğunu gösterir. İstek başarılı olursa Azure depolama bir 201 Created döndürür.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

Azure depolama API'leriyle çalışmak bu makalenin kapsamının dışındadır. Bu bölümün önceki kısımlarında bağlantılı olan Azure Blob depolama REST API'lere ek olarak, başlamanıza yardımcı olacak aşağıdaki belgeleri keşfedebilirsiniz:

Cihaz: Tamamlanan IoT Hub durumu bildirme

Cihaz, dosya yüklemesini tamamlayan Upload Durum REST API'si veya cihaz SDK'larından biri içinde eşdeğer API'yi çağırır. Karşıya yüklemenin başarılı veya başarısız olması IoT Hub cihazın dosya karşıya yükleme durumunu güncelleştirmesi gerekir.

Desteklenen protokoller: AMQP, AMQP-WS, MQTT, MQTT-WS ve HTTPS
nokta: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Yöntem: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

Özellik Açıklama
correlationId İlk SAS URI isteğinde alınan bağıntı kimliği.
isSuccess Dosya karşıya yüklemenin başarılı olup olmadığını gösteren bir boole değeri.
statusCode Dosya karşıya yüklemenin durum kodunu temsil eden bir tamsayı. Genellikle üç basamak; Örneğin, 200 veya 201.
statusDescription Dosya karşıya yükleme durumunun açıklaması.

Cihazdan dosya karşıya yükleme tam bildirimi aldığında şu IoT Hub:

  • Dosya karşıya yükleme bildirimleri yapılandırılmışsa arka uç hizmetleri için bir dosya yükleme bildirimi tetikler.

  • Dosya karşıya yükleme ile ilişkili kaynakları serbest bırakma. Bildirim almadan IoT Hub, karşıya yüklemeyle ilişkili SAS URI'sini yaşam süresi (TTL) süresi dolana kadar kaynakları koruyabilirsiniz.

Hizmet: Dosya karşıya yükleme bildirimleri

IoT hub' ınıza dosya yükleme bildirimleri etkinleştirildiyse, bir cihazdan dosya yüklemenin tamamlandıktan sonra bildirim aldığında arka uç hizmetleri için bir bildirim iletisi oluşturulur. IoT Hub karşıya yükleme bildirimlerini hizmete yönelik bir uç nokta üzerinden iletir. Dosya karşıya yükleme bildirimleri için alma semantiği buluttan cihaza iletileriyle aynıdır ve aynı ileti yaşam döngüsüne sahip olur. Hizmet SDK'leri, dosya karşıya yükleme bildirimlerini işlemek için API'leri ortaya çıkarır.

Desteklenen protokoller AMQP, AMQP-WS
nokta: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Yöntem AL

Dosya karşıya yükleme bildirim uç noktası üzerinden alınan her ileti bir JSON kaydıdır:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
Özellik Açıklama
enqueuedTimeUtc Bildirimin ne zaman oluşturulacaklarını gösteren zaman damgası.
deviceId Dosyayı karşıya yüken cihazın Cihaz Kimliği.
blobUri Karşıya yüklenen dosyanın URI'si.
blobName Karşıya yüklenen dosyanın adı. Ad şu biçimdedir: {device ID of the device}/{name of the blob}
lastUpdatedTime Dosyanın en son ne zaman güncelleştirilmiş olduğunu gösteren zaman damgası.
blobSizeInBytes Karşıya yüklenen dosyanın bayt cinsinden boyutunu temsil eden bir tamsayı.

Hizmetler, karşıya yüklemeleri yönetmek için bildirimleri kullanabilir. Örneğin, blob verilerini kendi işlemelerini tetikler, diğer Azure hizmetlerini kullanarak blob verilerini işlemeyi tetikler veya daha sonra gözden geçirmek için dosya yükleme bildirimini günlüğe yükleyebilirler.

Sonraki adımlar