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.

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

IoT hub'ı, bir blob kapsayıcısı ve hub'dan dosya yükleme için 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ı ve blob kapsayıcısı yapılandırma.
• Cihazlardan dosya yükleme.
• İsteğe bağlı olarak, tamamlanmış dosya yüklemelerini arka uç hizmetlerine 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:

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

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. Daha fazla bilgi 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'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ç noktada bunları teslim eder. Hizmetler bu bildirimleri kullanarak blob verilerinin daha fazla işlenmesini tetikleyebilir. Daha fazla bilgi için bkz . Hizmet: Dosya yükleme bildirimleri.

Azure IoT cihaz ve hizmet SDK'ları dosya yüklemeyi tam olarak destekler. 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 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.

Varsayılan olarak Azure IoT Hub, Azure Depolama ile bağlantı kurmak 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 güvenli bir şekilde Azure hizmetlerine, Microsoft Entra ID üzerinde otomatik olarak yönetilen bir kimlik sağlar.

Dosya yükleme, Azure Depolama'nın güvenlik duvarı ayarlarına tabidir. Cihazlarınızın kimlik doğrulama yapılandırmanıza göre 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ı, Azure CLI, PowerShell 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. Yine de SAS URI'sini kullanarak cihazlarınızı depolamaya bağlamanız gerekir. Bugün SAS URI'sı bağlantı dizesi kullanılarak oluşturulur.

Dosya yüklemeyi kimlik tabanlı kimlik doğrulaması kullanacak şekilde yapılandırma hakkında bilgi için bkz . Yönetilen kimliklerle dosya yüklemeyi yapılandırma.

Dosya yükleme ayarları

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

Dosya karşıya yükleme bildirim ayarları

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

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.

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"
}

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"
}

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ıttaki sasToken ö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=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 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"
}

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"
}

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

• IoT Hub'da dosya yüklemelerini yapılandırma

• IoT Hub'da yönetilen kimlikleri yapılandırma