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

Cihaz verilerinizi, kabul IoT Hub görece küçük cihazdan buluta iletilere kolayca eşleyemezseniz birçok senaryo vardır. Örneğin, video gibi büyük medya dosyaları gönderme; veya aralıklı olarak bağlı cihazlar tarafından karşıya yüklenen veya bant genişliğinden tasarruf etmek için toplanmış ve sıkıştırılmış büyük telemetri toplu işlemlerini gönderme.

Bir cihazdan büyük dosyaları karşıya yüklemeniz gerektiğinde, IoT Hub güvenliğini ve güvenilirliğini kullanmaya devam edebilirsiniz. Ancak IoT Hub, iletilerin kendisi aracılığıyla aracılık etmek yerine ilişkili Bir Azure depolama hesabına dağıtıcı görevi görür. IoT Hub, bir cihaz dosya yükleme işlemini tamamladığında arka uç hizmetlerine bildirim de sağlayabilir.

Bildirilen özellikleri, cihazdan buluta iletileri veya dosya yüklemelerini ne zaman kullanacağınıza 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 yükleme işlevi genel önizleme aşamasındadır ve önizleme modunun etkinleştirilmesi gerekir. Azure Cihaz Sağlama Hizmeti ile X.509 parmak izi kimlik doğrulaması veya X.509 sertifika kanıtlama kullanan cihazlarda genel olarak 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'ı, bağlı cihazlardan blob kapsayıcısı ve hub ile önceden yapılandırılmış Azure depolama hesabı için karşıya yükleme başına paylaşılan erişim imzası (SAS) URI'leri sağlayarak dosya yüklemelerini kolaylaştırır. dosya yüklemelerini IoT Hub ile kullanmanın üç bölümü vardır: IoT hub'ınızda bir Azure depolama hesabını ve blob kapsayıcısını önceden yapılandırma, cihazlardan dosyaları karşıya yükleme ve isteğe bağlı olarak arka uç hizmetlerine tamamlanan dosya yüklemelerini bildirme.

Dosya yükleme özelliğini kullanabilmeniz için bir Azure depolama hesabını ve blob kapsayıcısını IoT hub'ınızla ilişkilendirmeniz gerekir. Ayrıca IoT Hub Azure depolama ile kimlik doğrulamasını, IoT hub'ının cihazlara dağıttığını SAS URI'lerinin yaşam süresini (TTL) ve arka uç hizmetlerinize dosya yükleme bildirimlerini denetleyebilen ayarları yapılandırabilirsiniz. Daha fazla bilgi edinmek için bkz. Azure depolama hesabını IoT Hub ile ilişkilendirme.

Cihazlar, ilişkili blob kapsayıcısına dosya yüklemek için üç adımlı bir işlemi izler:

  1. Cihaz, IoT hub'ı ile dosya karşıya yükleme işlemini başlatır. İstekteki bir blobun adını geçirir ve karşılığında bir SAS URI'si ve bir bağıntı kimliği alır. SAS URI'sinde, blob kapsayıcısında istenen blob üzerinde cihaza okuma-yazma izni veren Azure depolama için bir SAS belirteci bulunur. Ayrıntılar için bkz . Cihaz: Karşıya dosya yükleme başlatma.

  2. Cihaz, dosyayı blob kapsayıcısına yüklemek üzere Azure blob depolama API'lerini güvenli bir şekilde çağırmak için SAS URI'sini kullanır. Ayrıntılar için bkz . Cihaz: Azure depolama API'lerini kullanarak dosya yükleme.

  3. Dosya karşıya yükleme işlemi tamamlandığında cihaz, karşıya yüklemeyi başlattığında IoT Hub aldığı bağıntı kimliğini kullanarak IoT hub'ına tamamlanma durumunu bildirir. Ayrıntılar için bkz. Cihaz: Tamamlanmış bir dosya yüklemesini IoT Hub bildirme.

Arka uç hizmetleri, IoT hub'ına yönelik hizmete yönelik dosya karşıya yükleme bildirimi uç noktasında dosya yükleme bildirimlerine abone olabilir. IoT hub'ınızda bu bildirimleri etkinleştirdiyseniz, bir cihaz hub'a bir dosya karşıya yükleme işlemini tamamlandığını bildirdiğinde bu uç noktaya teslim eder. Hizmetler bu bildirimleri kullanarak blob verilerinin daha fazla işlenmesini tetikleyebilir. Ayrıntılar için bkz . Hizmet: Dosya yükleme bildirimleri.

Dosya yükleme, Azure IoT cihaz ve hizmet SDK'ları tarafından tam olarak desteklenir. Ayrıntılar için bkz. SDK kullanarak dosya yükleme.

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

IoT Hub belirli bir dönemde başlatabileceği dosya yüklemelerinin sayısına azaltma sınırları getirir. Eşik, IoT hub'ınızın SKU'sunu ve birim sayısını temel alır. Ayrıca, her cihaz aynı anda 10 eşzamanlı etkin dosya yükleme ile sınırlıdır. Daha fazla bilgi için bkz . Azaltma ve kotalar.

Azure depolama hesabını IoT Hub ile ilişkilendirme

Dosya yükleme özelliklerini kullanmak için Bir Azure depolama hesabını ve blob kapsayıcısını IoT hub'ınızla ilişkilendirmeniz gerekir. IoT hub'ınıza kayıtlı cihazlardan yapılan tüm dosya yüklemeleri bu kapsayıcıya gider. IoT hub'ınızda bir depolama hesabı ve blob kapsayıcısı yapılandırmak için bkz. Azure portal ile dosya karşıya yüklemelerini yapılandırma, Azure CLI ile dosya karşıya yüklemelerini yapılandırma veya PowerShell ile dosya karşıya yüklemelerini yapılandırma. Dosya yüklemelerini program aracılığıyla yapılandırmak için 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 bölümüne bakın. Depolama hesabınız olduğunda , Azure blob depolama hızlı başlangıçlarında blob kapsayıcısının nasıl oluşturulacağını görebilirsiniz. varsayılan olarak Azure IoT Hub, Azure Depolama'ya bağlanmak ve yetkilendirmek için anahtar tabanlı kimlik doğrulamasını kullanır. Azure Depolama ile Azure IoT Hub kimlik doğrulaması yapmak için kullanıcı tarafından atanan veya sistem tarafından atanan yönetilen kimlikleri de yapılandırabilirsiniz. Yönetilen kimlikler, Azure hizmetlerine güvenli bir şekilde Azure AD otomatik olarak yönetilen bir kimlik sağlar. Yönetilen kimlikleri yapılandırmayı öğrenmek için bkz. Yönetilen kimliklerle dosya yüklemeyi yapılandırma.

Dosya karşıya yükleme, Azure depolamanın güvenlik duvarı ayarlarına tabidir. Kimlik doğrulama yapılandırmanıza bağlı olarak, cihazlarınızın Azure depolama ile iletişim kuradığından emin olmanız gerekir.

Dosya karşıya yükleme ve dosya karşıya yükleme bildirimlerinin davranışını denetleyebilen birkaç ayar daha vardır. Aşağıdaki bölümlerde kullanılabilir tüm ayarlar listelemektedir. Dosya yüklemelerini yapılandırmak için Azure portal, Azure CLI, PowerShell veya yönetim API'lerini kullanıp kullanmadığınıza bağlı olarak, bu ayarlardan bazıları kullanılamayabilir. Karşıya dosya yükleme tamamlandığında arka uç hizmetlerinize bildirim gönderilmesini istiyorsanız enableFileUploadNotifications ayarını ayarladığınızdan 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ızla ilişkilendirir ve hub'ınızın Azure depolama ile kimlik doğrulamasını denetler. Bu ayarlar, cihazların Azure depolama ile kimlik doğrulamasını etkilemez. Cihazlar her zaman IoT Hub alınan SAS URI'sinde sunulan SAS belirteci ile kimlik doğrulaması yapar.

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

Dosya yükleme ayarları

Aşağıdaki ayarlar cihazdan dosya yüklemelerini denetler.

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

Dosya karşıya yükleme bildirimi ayarları

Aşağıdaki ayarlar arka uç hizmetlerine dosya yükleme bildirimlerini denetler.

Özellik Açıklama Aralık ve varsayılan
enableFileUploadNotifications Dosya karşıya yükleme bildirimlerinin dosya bildirimleri uç noktasına yazıp yazılmayacağını denetler. Bool. Varsayılan: False.
fileNotifications.ttlAsIso8601 Dosya karşıya yükleme bildirimleri için varsayılan TTL. 48 saate (en az 1 dakika) kadar ISO_8601 aralık. Varsayılan: 1 saat.
fileNotifications.lockDuration Dosya karşıya yükleme bildirimleri kuyruğu için kilit süresi. 5-300 saniye. Varsayılan: 60 saniye.
fileNotifications.maxDeliveryCount Dosya karşıya yükleme bildirim kuyruğu için maksimum teslim sayısı. 1'e 100. Varsayılan: 100.

SDK kullanarak dosya yükleme

Aşağıdaki nasıl yapılır kılavuzları, Azure IoT cihazı ve hizmet SDK'larını kullanarak dosyaları karşıya yüklemek için eksiksiz ve adım adım yönergeler sağlar. Bir depolama hesabını IoT hub'ı ile ilişkilendirmek için Azure portal nasıl kullanacağınızı gösterirler ve kod parçacıkları içerirler veya karşıya yükleme işleminde size yol gösteren örneklere başvururlar.

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ükleme işlemlerini gerçekleştirmek için cihaz istemcisinde tek bir çağrı kullanır. Daha fazla bilgi için bkz. IoTHubDeviceClient_UploadToBlobAsync() ve IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Bu işlevler, karşıya yüklemeyi başlatma, dosyayı Azure depolamaya yükleme ve tamamlandığında IoT Hub bildirme gibi dosya yükleme işleminin tüm yönlerini tek bir çağrıda gerçekleştirir. Bu, cihazın IoT Hub ile iletişim kurmak için kullandığı protokole ek olarak, bu işlevler Azure depolama API'lerine çağrı yaparken Azure depolama ile HTTPS üzerinden de iletişim kurabilmesi gerektiği anlamına gelir.

Cihaz: Dosya karşıya yükleme işlemini başlatma

Cihaz, dosya karşıya yükleme işlemini başlatmak için Dosya Yükleme SAS URI'sini Oluşturma REST API'sini veya cihaz SDK'larından birinde eşdeğer API'yi çağırır.

Desteklenen protokoller: HTTPS
Uç nokta: {iot hub}.azure-devices.net/devices/{deviceId}/files
Yöntem: POST

{
    "blobName":"myfile.txt"
}

Özellik Açıklama
blobName SAS URI'sinin oluşturulacağı blobun adı.

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

{
    "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 IoT Hub'a dosya yükleme tam bildirimi gönderilirken kullanılacak cihazın tanımlayıcısı.
Hostname IoT hub'da yapılandırılan depolama hesabının Azure depolama hesabı ana bilgisayar adı
containerName IoT hub'ına yapılandırılan blob kapsayıcısının adı.
blobName Blob'un kapsayıcıda depolandığı konum. Ad aşağıdaki biçimdedir: {device ID of the device making the request}/{blobName in the request}
sasToken Azure depolama ile blob üzerinde okuma-yazma erişimi veren bir SAS belirteci. Belirteç oluşturulur ve IoT Hub tarafından imzalanır.

Yanıtı aldığında cihaz:

  • Karşıya yükleme tamamlandığında IoT hub'ına dosya yükleme tam bildirimine eklenecek bağıntı kimliğini kaydeder.

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

    Örneğin, yukarıdaki örnekte döndürülen değerler için SAS URI'sinin 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 ve SAS belirteci hakkında daha fazla bilgi için Azure depolama belgelerindeki Hizmet SAS'i oluşturma bölümüne bakın.

Cihaz: Azure depolama API'lerini kullanarak dosyayı karşıya yükleme

Cihaz, dosyayı Azure depolamadaki bloba yüklemek için Azure Blob depolama REST API'lerini veya eşdeğer Azure depolama SDK API'lerini kullanır.

Desteklenen protokoller: HTTPS

Aşağıdaki örnekte, küçük bir blok blobu oluşturmak veya güncelleştirmek için Blob Koy isteği gösterilmektedir. Bu istek için kullanılan URI'nin önceki bölümdeki IoT Hub tarafından döndürülen SAS URI'sine dikkat edin. x-ms-blob-type Üst bilgi, bu isteğin bir blok blobu için olduğunu gösterir. İstek başarılı olursa, Azure depolama bir 201 Createddö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ümde daha önce bağlanan Azure Blob depolama REST API'lerine ek olarak, başlamanıza yardımcı olması için aşağıdaki belgeleri inceleyebilirsiniz:

Cihaz: Tamamlanmış bir dosya yüklemesini IoT Hub bildirme

Cihaz, dosya yükleme işlemini tamamladığında cihaz SDK'larından birinde Dosya Yükleme Durumunu Güncelleştir REST API'sini veya eşdeğer API'yi çağırır. Cihazın, karşıya yüklemenin başarılı veya başarısız olmasına bakılmaksızın dosya yükleme durumunu IoT Hub ile güncelleştirmesi gerekir.

Desteklenen protokoller: HTTPS
Uç 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 yüklemesinin başarılı olup olmadığını gösteren boole değeri.
statusCode Karşıya yükleme dosyasının durum kodunu temsil eden bir tamsayı. Genellikle üç basamak; örneğin, 200 veya 201.
statusDescription Dosya karşıya yükleme durumunun açıklaması.

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

  • Dosya yükleme bildirimleri yapılandırılırsa arka uç hizmetlerine dosya yükleme bildirimini tetikler.

  • Dosya yüklemeyle ilişkili kaynakları serbest bırakır. Bildirim almadan IoT Hub, karşıya yüklemeyle ilişkili SAS URI yaşam süresi (TTL) süresi dolana kadar kaynakları korur.

Hizmet: Dosya yükleme bildirimleri

IoT hub'ınızda dosya karşıya yükleme bildirimleri etkinleştirildiyse, bir cihazdan dosya yükleme işleminin tamamlandığını belirten bir bildirim aldığında arka uç hizmetleri için bir bildirim iletisi oluşturur. IoT Hub bu dosya karşıya yükleme bildirimlerini hizmete yönelik bir uç nokta üzerinden teslim eder. Dosya yükleme bildirimleri için alma semantiği, buluttan cihaza iletilerle aynıdır ve ileti yaşam döngüsü aynıdır. Hizmet SDK'ları, dosya yükleme bildirimlerini işlemek için API'leri kullanıma sunar.

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

Dosya karşıya yükleme bildirimi uç noktasından 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şturulduğunu gösteren zaman damgası.
deviceId Dosyayı karşıya yükleyen cihazın Cihaz Kimliği.
blobUri Karşıya yüklenen dosyanın URI'si.
blobName Karşıya yüklenen dosyanın adı. Ad aşağıdaki biçimdedir: {device ID of the device}/{name of the blob}
lastUpdatedTime Dosyanın en son ne zaman güncelleştirildiğini gösteren zaman damgası.
blobSizeInBytes Karşıya yüklenen dosyanın boyutunu bayt cinsinden temsil eden bir tamsayı.

Hizmetler, karşıya yüklemeleri yönetmek için bildirimleri kullanabilir. Örneğin, blob verilerinin kendi işlenmesini tetikleyebilir, diğer Azure hizmetlerini kullanarak blob verilerinin işlenmesini tetikleyebilir veya daha sonra gözden geçirmek üzere dosya karşıya yükleme bildirimini günlüğe kaydedebilirler.

Sonraki adımlar