IoT Hub ile dosyaları karşıya yükleme
Cihaz verilerinizi IoT Hub'ın kabul ettiği görece küçük cihazdan buluta iletilerle kolayca eşleyememenize neden olan 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 toplu 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'ın güvenliğini ve güvenilirliğini kullanmaya devam edebilirsiniz. Ancak IoT Hub, iletileri kendi aracılığıyla aracılık etmek yerine ilişkili bir Azure depolama hesabına dağıtıcı işlevi 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'ı, blob kapsayıcısı ve hub ile önceden yapılandırılmış Azure depolama hesabı için karşıya yükleme temelinde paylaşılan erişim imzası (SAS) URI'leri sağlayarak bağlı cihazlardan dosya yükleme işlemlerini kolaylaştırır. IoT Hub ile dosya yüklemelerini 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 tamamlanmış 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'ın Azure depolama ile kimlik doğrulamasını, IoT hub'ının cihazlara dağıttığını SAS URI'lerinin yaşam süresi (TTL) ve arka uç hizmetlerinize dosya yükleme bildirimlerini denetleme ayarlarını 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:
Cihaz, IoT hub'ı ile dosya 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. Daha fazla bilgi için bkz . Cihaz: Karşıya dosya yükleme başlatma.
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. Daha fazla bilgi için bkz . Cihaz: Azure depolama API'lerini kullanarak dosya yükleme.
Dosya karşıya yükleme işlemi tamamlandığında cihaz, karşıya yüklemeyi başlattığında IoT Hub'dan aldığı bağıntı kimliğini kullanarak IoT hub'ına tamamlanma durumunu bildirir. Daha fazla bilgi için bkz . Cihaz: Tamamlanmış bir dosya yüklemesini IoT Hub'a bildirme.
Arka uç hizmetleri, IoT hub'ına yönelik hizmet 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 yükleme işlemini tamamladığını bildirdiğinde bu uç noktaya teslim eder. Hizmetler bu bildirimleri kullanarak blob verilerinin daha fazla işlenmesini tetikleyebilir. Daha fazla bilgi için bkz . Hizmet: Dosya yükleme bildirimleri.
Dosya yükleme, Azure IoT cihaz ve hizmet SDK'ları tarafından tam olarak desteklenir. Daha fazla bilgi için bkz . SDK kullanarak dosya yükleme.
Dosya 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ı uygular. 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 . IoT Hub kotaları ve azaltma.
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ını kullanarak IoT Hub dosya yüklemelerini yapılandırma, Azure CLI kullanarak IoT Hub dosya yüklemelerini yapılandırma veya PowerShell kullanarak IoT Hub dosya 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 olduktan sonra, 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 ile bağlanmak ve yetkilendirmek için anahtar tabanlı kimlik doğrulamasını kullanır. Azure IoT Hub'ın kimliğini Azure Depolama ile doğrulamak için kullanıcı tarafından atanan veya sistem tarafından atanan yönetilen kimlikleri de yapılandırabilirsiniz. Yönetilen kimlikler, Azure hizmetlerine Microsoft Entra Id'de güvenli bir şekilde otomatik olarak yönetilen bir kimlik sağlar. Yönetilen kimlikleri yapılandırmayı öğrenmek için Yönetilen kimlikler için IoT Hub desteğinin Yönetilen kimliklerle dosya yüklemeyi yapılandırma bölümüne bakın.
Dosya yükleme, Azure Depolama 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 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ını, Azure CLI'yı, PowerShell'i veya yönetim API'lerini kullanıp kullanmadığınıza bağlı olarak, bu ayarlardan bazıları kullanılamayabilir. Bir dosya karşıya 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'dan alınan SAS URI'sinde sunulan SAS belirteci ile kimlik doğrulaması yapar.
| Özellik | Tanım | Aralık ve varsayılan |
|---|---|---|
| storageEndpoints.$default.authenticationType | IoT Hub'ın 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 için veya kullanıcı tarafından atanan yönetilen kimliğin kaynak kimliğine yöneliktir. Değer anahtar tabanlı kimlik doğrulaması için kullanılmaz. Varsayılan: null. |
Dosya yükleme ayarları
Aşağıdaki ayarlar, dosya yüklemelerini cihazdan denetler.
| Özellik | Tanım | 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 bir dakika) kadar ISO_8601 aralık. Varsayılan: bir saat. |
Dosya karşıya yükleme bildirim ayarları
Aşağıdaki ayarlar arka uç hizmetlerine dosya yükleme bildirimlerini denetler.
| Özellik | Tanım | 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 yükleme bildirimleri için varsayılan TTL. | 48 saate (en az bir dakika) kadar ISO_8601 aralık. Varsayılan: bir saat. |
| fileNotifications.lockDuration | Dosya karşıya yükleme bildirimleri kuyruğunun süresini kilitleyin. | 5-300 saniye. Varsayılan: 60 saniye. |
| fileNotifications.maxDeliveryCount | Dosya karşıya yükleme bildirimi kuyruğu için en yüksek teslim sayısı. | 1 ile 100. Varsayılan: 10. |
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. Kılavuzlar, depolama hesabını bir IoT hub'ı ile ilişkilendirmek için Azure portalını nasıl kullanacağınızı gösterir. Kılavuzlar ayrıca kod parçacıkları içerir veya karşıya yükleme işleminde size yol gösteren örneklere bakın.
| Nasıl yapılır kılavuzu | Cihaz SDK'sı örneği | Hizmet SDK'sı örneği |
|---|---|---|
| .NET | Evet | Evet |
| Java | Evet | Evet |
| Node.js | Evet | Evet |
| Python | Evet | Hayır (desteklenmez) |
Dekont
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ükleme işlemini tek bir çağrıda gerçekleştirir: karşıya yüklemeyi başlatma, dosyayı Azure depolamaya yükleme ve tamamlandığında IoT Hub'a bildirme. Bu etkileşim, cihazın IoT Hub ile iletişim kurmak için kullandığı protokole ek olarak, bu işlevler Azure depolama API'lerine çağrı yaparken cihazın Azure depolama ile HTTPS üzerinden iletişim kurabilmesi gerektiği anlamına gelir.
Cihaz: Karşıya dosya yükleme başlatma
Cihaz, dosya karşıya yükleme 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 | Tanım |
|---|---|
| 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 | Tanım |
|---|---|
| correlationId | IoT Hub'a dosya yükleme tam bildirimi gönderirken kullanılacak cihazın tanımlayıcısı. |
| Hostname | IoT hub'ına 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 depolanacağı 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ç IoT Hub tarafından oluşturulur ve 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 depolamada kimlik doğrulaması için kullandığı blob için sas URI'si oluşturmak için diğer özellikleri kullanır. SAS URI'si, istenen blob ve SAS belirtecinin kaynak URI'sini içerir. Şu biçimi alır:
https://{hostName}/{containerName}/{blobName}{sasToken}(YanıttakisasTokenözellik baştaki '?' karakterini içerir.) Küme ayraçları dahil değildir.Örneğin, önceki örnekte döndürülen değerler için SAS URI'sinin değeri ş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=rwSAS 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 Put Blob isteği gösterilmektedir. Bu istek için kullanılan URI'nin önceki bölümde 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ğlanmış olan Azure Blob depolama REST API'lerine ek olarak, başlamanıza yardımcı olması için aşağıdaki belgeleri inceleyebilirsiniz:
Azure depolamada bloblarla çalışma hakkında daha fazla bilgi edinmek için Azure Blob Depolama belgelerine bakın.
Blobları karşıya yüklemek için Azure depolama istemci SDK'larını kullanma hakkında bilgi için bkz. API başvurusu Azure Blob Depolama.
Cihaz: Tamamlanmış bir dosya yüklemesini IoT Hub'a bildirme
Cihaz, dosya yükleme işlemini tamamladığında cihaz SDK'larından birinde Güncelleştirme Dosyası Karşıya Yükleme Durumu 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 | Tanım |
|---|---|
| correlationId | İlk SAS URI isteğinde alınan bağıntı kimliği. |
| isSuccess | Dosya yükleme işleminin 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 karşıya yükleme bildirimleri yapılandırılırsa arka uç hizmetlerine dosya yükleme bildirimi tetikler.
Dosya yüklemeyle ilişkili kaynakları serbest bırakır. IoT Hub bir bildirim almazsa, 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, hub'ınız bir cihazdan dosya yükleme işleminin tamamlandığını bildiren 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 sunar. Dosya karşıya 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
GET Yöntemi
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 | Tanım |
|---|---|
| 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'sini. |
| 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şlemesini tetikleyebilir, diğer Azure hizmetlerini kullanarak blob verilerinin işlenmesini tetikleyebilir veya dosya karşıya yükleme bildirimini daha sonra gözden geçirmek üzere günlüğe kaydedebilirler.
Sonraki adımlar
Azure IoT cihaz ve hizmet SDK'ları , IoT Hub ile etkileşim kuran hem cihaz hem de hizmet uygulamaları geliştirirken kullanabileceğiniz çeşitli dil SDK'larını listeler.