Azure İşlevleri için Azure IoT Hub bağlamaları

  • Makale

Bu makale kümesinde, IoT Hub için Azure İşlevleri bağlamalarıyla nasıl çalışılaları açıklanmaktadır. IoT Hub desteği, Azure Event Hubs Bağlamasını temel alır.

Önemli

Aşağıdaki kod örnekleri Event Hub API'sini kullansa da, verilen söz dizimi IoT Hub işlevleri için geçerlidir.

Eylem Tür
IoT hub olay akışına gönderilen olayları yanıtlama. Tetikleyici

Uzantıyı yükleme

Yüklediğiniz NuGet uzantısı, işlev uygulamanızda kullandığınız C# moduna bağlıdır:

İşlevler yalıtılmış bir C# çalışan işleminde yürütülür. Daha fazla bilgi edinmek için bkz. Yalıtılmış çalışan işleminde C# Azure İşlevleri çalıştırma kılavuzu.

Uzantının işlevselliği, uzantı sürümüne bağlı olarak değişir:

Bu sürüm gizli dizi yerine kimlik kullanarak bağlanma özelliğini tanıtır. İşlev uygulamalarınızı yönetilen kimliklerle yapılandırma öğreticisi için kimlik tabanlı bağlantılarla işlev uygulaması oluşturma öğreticisine bakın.

NuGet paketi, sürüm 5.x'i yükleyerek uzantıyı projenize ekleyin.

Paket yükleme

Event Hubs uzantısı, host.json proje dosyanızda belirtilen bir uzantı paketinin parçasıdır. Bağlamanın sürümünü değiştirmek için veya paketler henüz yüklü değilse bu paketi değiştirmeniz gerekebilir. Daha fazla bilgi edinmek için bkz . uzantı paketi.

Bu sürüm gizli dizi yerine kimlik kullanarak bağlanma özelliğini tanıtır. İşlev uygulamalarınızı yönetilen kimliklerle yapılandırma öğreticisi için kimlik tabanlı bağlantılarla işlev uygulaması oluşturma öğreticisine bakın.

Uzantı paketi v3'ten, dosyanıza host.json aşağıdaki kodu ekleyerek veya değiştirerek uzantının bu sürümünü ekleyebilirsiniz:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Daha fazla bilgi edinmek için bkz . Uzantılarınızı güncelleştirme.

Bağlama türleri

.NET için desteklenen bağlama türleri, aşağıdakilerden biri olabilecek uzantı sürümüne ve C# yürütme moduna bağlıdır:

Yalıtılmış çalışan işlem sınıfı kitaplığı derlenmiş C# işlevi çalışma zamanından yalıtılmış bir işlemde çalışır.

Modun ve sürümün bağlama türü ayrıntılarını görmek için bir sürüm seçin.

Yalıtılmış çalışan işlemi, aşağıdaki tablolara göre parametre türlerini destekler. Azure.Messaging.EventHubs'tan türlere bağlama desteği önizleme aşamasındadır.

Event Hubs tetikleyicisi

İşlevin tek bir olayı işlemesini istediğinizde Event Hubs tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
string Dize olarak olay. Olay basit bir metin olduğunda kullanın.
byte[] Olayın baytları.
JSON serileştirilebilir türler Bir olay JSON verileri içerdiğinde İşlevler, JSON verilerinin seri durumdan çıkarılarak düz eski bir CLR nesnesi (POCO) türüne dönüştürülmeye çalışılır.
Azure.Messaging.EventHubs.EventData1 Olay nesnesi.
Event Hubs SDK'larının herhangi bir eski sürümünden geçiş gerçekleştiriyorsanız, bu sürümün EventBody yerine eski Body tür için desteği bıraktığına dikkat edin.

İşlevin bir grup olayı işlemesini istediğinizde Event Hubs tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
string[] Toplu işlemden dizeler olarak bir dizi olay. Her girdi bir olayı temsil eder.
EventData[]1 Azure.Messaging.EventHubs.EventData örneği olarak toplu işlemden bir dizi olay. Her girdi bir olayı temsil eder.
T[] burada T JSON seri hale getirilebilir tür1'dir Özel POCO türünün örnekleri olarak toplu işlemden olay dizisi. Her girdi bir olayı temsil eder.

1 Bu türleri kullanmak için Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 veya sonraki sürümlerine ve SDK türü bağlamaları için ortak bağımlılıklara başvurmanız gerekir.

Event Hubs çıkış bağlaması

İşlevin tek bir olay yazmasını istediğinizde Event Hubs çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
string Dize olarak olay. Olay basit bir metin olduğunda kullanın.
byte[] Olayın baytları.
JSON serileştirilebilir türler Olayı temsil eden bir nesne. İşlevler, düz eski bir CLR nesnesi (POCO) türünü JSON verilerine seri hale getirmeye çalışır.

İşlevin birden çok olay yazmasını istediğinizde Event Hubs çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
T[] burada T tek olay türlerinden biridir Birden çok olay içeren bir dizi. Her girdi bir olayı temsil eder.

Diğer çıkış senaryoları için doğrudan Microsoft.Azure.EventHubs'dan türler oluşturun ve kullanın.

host.json ayarları

host.json dosyası, Event Hubs tetikleyicisinin davranışını denetleen ayarlar içerir. Uzantı sürümüne bağlı olarak yapılandırma farklıdır.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Özellik Varsayılan Açıklama
maxEventBatchSize2 100 Tek bir çağrı için toplu işleme dahil edilen en fazla olay sayısı. En az 1 olmalıdır.
minEventBatchSize1 1 Toplu işlemde istenen en az olay sayısı. En düşük değer yalnızca işlev birden çok olay aldığında geçerlidir ve değerinden maxEventBatchSizeküçük olmalıdır.
Minimum boyut kesinlikle garanti değildir. Tam bir toplu iş tamamlanmadan önce maxWaitTime hazırlanamıyorsa kısmi bir toplu iş gönderilir. Kısmi toplu işlemler, ölçeklendirme gerçekleştikten sonra işlevin ilk çağrılması için de olasıdır.
maxWaitTime1 00:01:00 Tetikleyicinin işlevi çağırmadan önce toplu işlemi doldurmak için beklemesi gereken maksimum aralık. Bekleme süresi yalnızca 1'den büyük olduğunda minEventBatchSize kabul edilir ve aksi takdirde yoksayılır. Bekleme süresi dolmadan önce daha az minEventBatchSize olay varsa, işlev kısmi bir toplu işlemle çağrılır. İzin verilen en uzun bekleme süresi 10 dakikadır.

NOT: Bu aralık, işlevin çağrıldığı tam zamanlama için kesin bir garanti değildir. Zamanlayıcı duyarlılığı nedeniyle küçük bir hata magin'i vardır. Ölçeklendirme gerçekleştiğinde, kısmi toplu iş ile ilk çağrı daha hızlı gerçekleşebilir veya yapılandırılan bekleme süresinin iki katına kadar sürebilir.
batchCheckpointFrequency 1 Olay hub'ı için bir denetim noktası oluşturmadan önce işlenmek üzere toplu işlem sayısı.
prefetchCount 300 Ağ işleminde beklemekten kaçınmak için okumalara izin vermek için Event Hubs'dan istekte bulunan ve yerel önbellekte tutulan olayların sayısı
transportType amqpTcp Event Hubs ile iletişim kurmak için kullanılan protokol ve aktarım. Kullanılabilir seçenekler: amqpTcp, amqpWebSockets
webProxy boş Web yuvaları üzerinden Event Hubs ile iletişim kurmak için kullanılacak proxy. Aktarım ile amqpTcp ara sunucu kullanılamaz.
customEndpointAddress boş Ağ isteklerinin bir uygulama ağ geçidi veya konak ortamı için gereken başka bir yol üzerinden yönlendirilmesine olanak tanıyarak Event Hubs'a bağlantı kurarken kullanılacak adres. Özel uç nokta adresi kullanıldığında ve açıkça veya bağlantı dizesi aracılığıyla belirtilmesi gerektiğinde olay hub'ı için tam ad alanı hala gereklidir.
targetUnprocessedEventThreshold1 boş İşlev örneği başına istenen işlenmemiş olay sayısı. Eşik, seçenekten çıkarılarak varsayılan ölçeklendirme eşiğini geçersiz kılmak için hedef tabanlı ölçeklendirmede maxEventBatchSize kullanılır. Ayarlandığında, toplam işlenmemiş olay sayısı, gereken işlev örneği sayısını belirlemek için bu değere bölünür. Örnek sayısı, dengeli bölüm dağılımı oluşturan bir sayıya yuvarlanacaktır.
initialOffsetOptions/type fromStart Depolamada bir denetim noktası olmadığında işlemeye başlamak için olay akışındaki konum. Tüm bölümler için geçerlidir. Daha fazla bilgi için OffsetType belgelerine bakın. Kullanılabilir seçenekler: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc boş İşlemenin başlatıldığı akıştaki olayın sıralanan saatini belirtir. olarak fromEnqueuedTimeyapılandırıldığında initialOffsetOptions/type bu ayar zorunludur. DateTime.Parse() tarafından desteklenen herhangi bir biçimde saati destekler; örneğin2020-10-26T20:31Z. Netlik için bir saat dilimi de belirtmeniz gerekir. Saat dilimi belirtilmediğinde İşlevler, işlev uygulamasını çalıştıran makinenin yerel saat dilimini (Azure üzerinde çalışırken UTC) varsayar.
clientRetryOptions/mode üssel Yeniden deneme gecikmelerini hesaplamak için kullanılacak yaklaşım. Üstel mod, her denemenin yeniden denemeden önce beklediği süreyi artıracağı bir geri alma stratejisine dayalı olarak denemeleri gecikmeli olarak yeniden dener. Sabit mod, her gecikmenin tutarlı bir süreye sahip olmasıyla sabit aralıklarla yeniden denemeler yapıyor. Kullanılabilir seçenekler: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Bir Event Hubs işleminin tamamlanması için deneme başına beklenme süresi üst sınırı.
clientRetryOptions/delay 00:00:00.80 Yeniden deneme girişimleri arasında uygulanacak gecikme veya geri kapatma faktörü.
clientRetryOptions/maximumDelay 00:00:01 Yeniden deneme girişimleri arasında izin vermek için en fazla gecikme.
clientRetryOptions/maximumRetries 3 İlişkili işlemin başarısız olduğu düşünülmeden önce en fazla yeniden deneme deneme sayısı.

1 ve maxWaitTime kullanmak minEventBatchSize için paketin Microsoft.Azure.WebJobs.Extensions.EventHubs v5.3.0 veya sonraki bir sürümü gerekir.

2 Paketin v6.0.0'ında Microsoft.Azure.WebJobs.Extensions.EventHubs varsayılan maxEventBatchSize değişiklik. Önceki sürümlerde bu 10'du.

clientRetryOptions İşlevler konağı ile Event Hubs (olayları getirme ve gönderme gibi) arasındaki işlemleri yeniden denemek için kullanılır. Tek tek işlevlere yeniden deneme ilkeleri uygulama hakkında bilgi için Azure İşlevleri hata işleme ve yeniden deneme yönergelerine bakın.

Azure İşlevleri 2.x ve sonraki host.json başvurusu için bkz. Azure İşlevleri için host.json başvuru.

Sonraki adımlar